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.

Debian

venv/bin/funkwhale-manage import_files --help

Docker

docker compose run --rm api funkwhale-manage 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:

Download the shell script.

curl -L -o download-tracks.sh "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.4.0/demo/download-tracks.sh"

Download the music list.

curl -L -o music.txt "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.4.0/demo/music.txt" chmod +x download-tracks.sh

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:

Visit https://<yourdomain>/content/libraries/ in your browser. This page contains a list of your libraries.
Find the library you want to upload content into. Select Library details to open the library details page.
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:

Log in to your server and navigate to your Funkwhale directory.
```
cd /srv/funkwhale
```
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"
```
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.
```
venv/bin/funkwhale-manage 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.

We recommend you symbolically link your music directories to /srv/funkwhale/data/music. You can then run the import_files command from that directory. This means you can use many directories without needing to add to them to your webserver.

Debian

To link your storage directory to the Funkwhale store, use the ln -s command. For example, if you have an NFS share at /media/nfsshare, you can link it to a folder like this:

ln -s ln -s /media/mynfsshare /srv/funkwhale/data/music/nfsshare

You can then run the import_files command against /srv/funkwhale/data/music/nfsshare.

Docker

On a Docker install you can use bind mounts to reference your storage directory. To do this, you need to add the directory to the api and celeryworker blocks in your docker-compose.yml file. For example, if you have an NFS share at /media/nfsshare, you can add the following to your docker-compose.yml file:

celeryworker:
  volumes:
   - ./data/music:/music:ro
   - ./data/media:/app/funkwhale_api/media
   # Add your bind here
   - type: bind
      source: /media/nfsshare
      destination: /srv/funkwhale/data/music/nfsshare

api:
   volumes:
   - ./data/music:/music:ro
   - ./data/media:/app/funkwhale_api/media
   # Add your bind here
   - type: bind
      source: /media/nfsshare
      destination: /srv/funkwhale/data/music/nfsshare

You can then run the import_files command against /srv/funkwhale/data/music/nfsshare.

Import your files 

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

Debian

Log in to your server and navigate to your Funkwhale directory.
```
cd /srv/funkwhale
```
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.
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"
```
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.
```
venv/bin/funkwhale-manage 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.

Docker

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.

Run your import command against your music storage directory:

docker compose run --rm api funkwhale-manage 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.

The cover embedded in the audio files (works with FLAC and MP3 files).
A cover.jpg or cover.png in the the track’s directory.
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.

Debian

venv/bin/funkwhale-manage import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch

Docker

docker compose run --rm api funkwhale-manage 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.

Debian

venv/bin/funkwhale-manage import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch --prune

Docker

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