Warning

This documentation only applies for the development version of Funkwhale! Visit the docs for the latest release.

Import music from your server

You can import music files you have saved on your server. You need to make sure your files have the required ID3 tags. We recommend using Musicbrainz Picard for tagging.

Funkwhale supports the following import methods:

  • Copy (default) – Funkwhale copies files from your server into the media store.

  • In-place import – Funkwhale adds the storage location of your files to the database. This uses less space than the copy method and ensures your collection is always up-to-date.

To see a full list of options, run the command with the --help flag.

poetry run python manage.py import_files --help
docker-compose run --rm api python manage.py import_files --help

Get demo music

If you don’t have music on your server, you can download creative commons music to test imports with. The Funkwhale project provides a collection courtesy of Jamendo. To download these tracks:

  1. Download the shell script.

    curl -L -o download-tracks.sh "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.2.7/demo/download-tracks.sh"
  2. Download the music list.

    curl -L -o music.txt "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.2.7/demo/music.txt" chmod +x download-tracks.sh
  3. Run the shell script against the music list to download the tracks.

    ./download-tracks.sh music.txt
    

This downloads a set compressed albums to your data/music directory and unzips them. You can then import these tracks using the methods in this article.

Find your library ID

You need to create a library before you can import music. Follow the instructions in Create a library to get started.

Once you’ve created your library, you can find its ID by following these steps:

  1. Visit https://<yourdomain>/content/libraries/ in your browser. This page contains a list of your libraries.

  2. Find the library you want to upload content into. Select Library details to open the library details page.

  3. Your library’s ID is the long string of letters and numbers shown in the URL bar. Copy the content before the first hyphen (-).

For example, if your library ID is 769a2bc3-eb1d-4aff-9f84-2c4d80d5c2d1, copy the 769a2bc3. You can use this as a shorthand reference for your library.

Import your music

Copy files from your server

Once you have your library ID, you can copy content from your server and import it into the library. To do this:

  1. Log in to your server and navigate to your Funkwhale directory.

    cd /srv/funkwhale
    
  2. Export your library ID to reference it later. In this example, the library ID is “769a2bc3”. Replace this with your library ID.

    export LIBRARY_ID="769a2bc3"
    
  3. Run the import_files command to copy your files. In this example, the music is stored in data/music. Replace this with your music directory.

    poetry run python manage.py import_files $LIBRARY_ID "data/music" --recursive --noinput
    

Funkwhale copies your files to your media store.

Access your files in-place

The in-place import method references your files in their current directory. This is useful if you have limited storage space.

Import your files

To use the in-place import method, follow these steps:

  1. Log in to your server and navigate to your Funkwhale directory.

    cd /srv/funkwhale
    
  2. Add your storage location to your .env file if you don’t want to link it to the Funkwhale store. See the in-place import configuration variables for more information.

  3. Export your library ID to reference it later. In this example, the library ID is “769a2bc3”. Replace this with your library ID.

    export LIBRARY_ID="769a2bc3"
    
  4. Run your import command against your music storage directory. In this example, the storage directory is /srv/funkwhale/data/music/nfsshare. Replace this with your storage directory.

    poetry run python manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place
    

Funkwhale imports the music in your storage directory into the specified library.

  1. Add your storage location to your .env file if you don’t want to bind it to the Funkwhale store. See the in-place import configuration variables for more information.

  2. Run your import command against your music storage directory:

    docker-compose run --rm api python manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place
    

Funkwhale imports the music in your storage directory into the specified library.

Album art

Funkwhale attempts to import album art for your music library. The import process checks for the following.

  1. The cover embedded in the audio files (works with FLAC and MP3 files).

  2. A cover.jpg or cover.png in the the track’s directory.

  3. An mbid in the file’s tags. If there is an mbid, the import process tries to fetch cover art from Musicbrainz.

Watch for filesystem changes

You can run the import_files command any time you add new files or update files. For larger collections, this may not be practical. To watch for changes, run the import_files command with the --watch flag. This instructs the import_files command to watch for filesystem events and update your database when something changes.

The --watch flag performs the following actions when it detects a change:

  • File created – imports the track.

  • File moved – updates the location of the track in the database.

  • File metadata updated – updates the track metadata in the database.

  • File deleted – removes the file from the database.


The `import_files --watch` command watches for changes to the following metadata fields:

- Track mbid
- Track title
- Track position and disc number
- Track license and copyright
- Track genre
- Album cover
- Album title
- Album mbid
- Album release date
- Artist name
- Artist mbid
- Album artist name
- Album artist mbid

poetry run python manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch
docker-compose run --rm api python manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch

Prune dangling metadata

Funkwhale doesn’t delete track metadata when you delete a track. This is useful if you want to delete a file but keep a record of a track for created playlists or favorites.

If you want to remove the file’s metadata when you delete the file, run import_files with the --prune flag. This flag removes the metadata of any

Note

You can use the --prune flag with the --watch flag. This means Funkwhale removes the metadata of referenced files you delete from your storage.

poetry run python manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch --prune
docker-compose run --rm api python manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch --prune