The Amber-Cast Archive Daemon (acad) is a simple daemon that archives SoundCloud and
YouTube playlists using yt-dlp. This tool will download every
song in the playlists given to it and write .m3u
playlist definitions for each playlist. The index
automatically deduplicates songs, so if multiple playlists contain the same song, it will only be
downloaded once per streaming platform. The index is intended to be used as a music library for MPD
(See MPD Integration).
This tool also keeps track of changes in the playlist and will update the definitions and index accordingly. Below is a summary of operations performed in response to playlist changes:
Change | Action |
---|---|
Song added to playlist | Song is downloaded and added to playlist definition |
Song removed from playlist | Song is removed from playlist definition (audio is kept in the index) |
Song deleted from SoundCloud/YouTube | Song is kept in the playlist definition and index |
Song became geo-restricted | Song is kept in the playlist definition and index |
In no situation will acad delete an audio file. The point of acad is to make a permanent record of all of your music.
The only supported way to use acad is through Docker:
docker run -d \
--name acad \
--restart unless-stopped \
-v /path/to/acad/data:/data \
-e ACAD_DATA_FOLDER=/data \
ghcr.io/campbellcole/acad:latest
# you can enable logging using the RUST_LOG environment variable. e.g.:
# -e RUST_LOG="acad=trace,info"
acad is configured using a JSON file. This file must be at $ACAD_DATA_FOLDER/config.json
in the
Docker container. The following is an example configuration file (comments are supported, as well as
trailing commas):
{
// save thumbnails for songs. saves the thumbnail as `$ACAD_DATA_FOLDER/audio/<id>/cover.jpg`
// can be retrieved through MPDs `albumart` command (NOT `readpicture`!)
"save_thumbnails": true,
// optional. forces playlist definitions to use absolute paths. if you are having trouble getting
// MPD to read the playlists, set this option to the exact path given to MPD's `music_directory`
// option
"mpd_music_dir": "/path/to/mpd/music_directory",
// optional. define when refreshes should happen using a cron expression. if not provided, acad
// will refresh every ~24 hours (starting after indexing finishes; prone to drifting). see
// https://crontab.guru/ for help with cron expressions
"refresh_cron": "0 0 * * *",
// optional. overrides the system timezone. the timezone is used for localizing the `refresh_cron`
// option. accepts an IANA timezone specifier.
"timezone": "America/Los_Angeles",
// here is where you define your playlists
"sources": [
{
"type": "soundcloud",
// the URL of the soundcloud playlist. supports private playlists if URL is a private share
// URL. if you use a private share URL, remove the query parameters from the URL so it looks
// like this:
"url": "https://soundcloud.com/artist/sets/playlist-name/s-XXXXXXXXXXX",
// optional. if `true`, this playlist will only be indexed once
"inactive": true
},
{
"type": "youtube",
// the URL of the youtube playlist. supports public and unlisted playlists.
"url": "https://youtube.com/playlist?list=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
]
}
acad officially supports SoundCloud and YouTube but it does not make any attempt to ensure a
source's URL matches it's source type. This means that, if you are feeling lucky, you can try to use
any URL that yt-dlp supports as a source URL and acad will attempt to index it. Currently, the only
platform specific code in acad is responsible for interpreting error messages from yt-dlp and
determining if a song is geo-restricted/missing. I personally have not tried using another platform
but I suspect that it will work fine, especially if you set the source type to youtube
.
If you want to try this, make sure you only provide playlist URLs. The program will absolutely crash if you provide a track URL because acad assumes yt-dlp will output a playlist manifest, not a track manifest (though this could easily be modified).
acad nicely integrates with MPD. If you do not have an existing MPD installation, you can simply set
MPD's music_directory
option to $ACAD_DATA_FOLDER/audio
, as well as MPD's playlist_directory
option to $ACAD_DATA_FOLDER/playlists
. With this setup, your MPD library will be 1:1 with your
playlists.
If you already have an MPD library set up, symlink $ACAD_DATA_FOLDER/audio
to your existing
music_directory
. You will likely have to change mpd_music_dir
to make sure the playlist
definitions correctly reference the audio files. See Configuration for more
information.
acad is licensed under the MIT license. See LICENSE for more information.