289 lines
9.5 KiB
Markdown
289 lines
9.5 KiB
Markdown
# 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](../../user/libraries/content/tag.md). We recommend using [Musicbrainz Picard](https://picard.musicbrainz.org/) 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.
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: debian
|
||
|
||
```{code-block} sh
|
||
venv/bin/funkwhale-manage import_files --help
|
||
```
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: docker
|
||
|
||
```{code-block} sh
|
||
sudo docker compose run --rm api funkwhale-manage import_files --help
|
||
```
|
||
|
||
:::
|
||
::::
|
||
|
||
```{contents}
|
||
:local:
|
||
```
|
||
|
||
## 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](https://jamendo.com). To download these tracks:
|
||
|
||
1. Download the shell script.
|
||
|
||
```{parsed-literal}
|
||
curl -L -o download-tracks.sh "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/{sub-ref}`version`/demo/download-tracks.sh"
|
||
```
|
||
|
||
2. Download the music list.
|
||
|
||
```{parsed-literal}
|
||
curl -L -o music.txt "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/{sub-ref}`version`/demo/music.txt" chmod +x download-tracks.sh
|
||
```
|
||
|
||
3. Run the shell script against the music list to download the tracks.
|
||
|
||
```{code-block} sh
|
||
./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](../../user/libraries/create.md) 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 {guilabel}`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.
|
||
|
||
```{code-block} sh
|
||
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.
|
||
|
||
```{code-block} sh
|
||
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.
|
||
|
||
```{code-block} sh
|
||
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.
|
||
|
||
#### Link your file directory
|
||
|
||
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.
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: 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:
|
||
|
||
```{code-block} sh
|
||
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`.
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: 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:
|
||
|
||
```{code-block} yaml
|
||
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:
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: debian
|
||
|
||
1. Log in to your server and navigate to your Funkwhale directory.
|
||
|
||
```{code-block} sh
|
||
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](../configuration/env_file.md#in-place-import-configuration) 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.
|
||
|
||
```{code-block} sh
|
||
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.
|
||
|
||
```{code-block} sh
|
||
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.
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: docker
|
||
|
||
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](../configuration/env_file.md#in-place-import-configuration) for more information.
|
||
2. Run your import command against your music storage directory:
|
||
|
||
```{code-block} sh
|
||
sudo 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.
|
||
|
||
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.
|
||
|
||
:::{dropdown} Watched metadata
|
||
|
||
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
|
||
|
||
:::
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: debian
|
||
|
||
```{code-block} sh
|
||
venv/bin/funkwhale-manage import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch
|
||
```
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: docker
|
||
|
||
```{code-block} sh
|
||
sudo 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.
|
||
```
|
||
|
||
::::{tab-set}
|
||
|
||
:::{tab-item} Debian
|
||
:sync: debian
|
||
|
||
```{code-block} sh
|
||
venv/bin/funkwhale-manage import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch --prune
|
||
```
|
||
|
||
:::
|
||
|
||
:::{tab-item} Docker
|
||
:sync: docker
|
||
|
||
```{code-block} sh
|
||
sudo docker compose run --rm api funkwhale-manage import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/" --recursive --noinput --in-place --watch --prune
|
||
```
|
||
|
||
:::
|
||
::::
|