AMA-Unraid

Unraid-friendly Automated Music Archiver
Deemix Direct · Synced Lyrics · ReplayGain · Plex/Roon Metadata Cleanup · High-Quality Album Art

Table of Contents

• What is AMA-Unraid?
• Main Features
• Docker Image and Unraid Template Updates
• Required and Optional Paths
  • Recommended Direct-mode paths
  • Optional Deemix login path
  • Legacy API-only path
• Deemix Login
• Basic Usage
• Artist List Files
• Artist Mode vs Discography Mode
• Variable Reference
  • Core setup
  • Format, quality, and conversion
  • Artwork
  • Library discovery and filtering
  • Post-processing and permissions
  • Lidarr
  • Plex
  • Optional and legacy Deemix paths
• Recommended Defaults
• Deemix Direct Flow
• Bitrate Fallback
• Conversion Notes
• Artist Tag Cleanup
• Timed LRC Lyric Fallback
• Plex Scan Path Override
• Docker Compose Example
• Docker CLI Example
• Testing Deemix Direct
• Legacy External Deemix API Mode
• Troubleshooting
  • Container starts but AMA does not run
  • Deemix Direct cannot log in
  • FLAC was requested but MP3, M4A, or OPUS was downloaded
  • Lyrics are missing
  • Permission issues
• Development Notes
• Related Projects
• Credits
• Funding
• Disclaimer

What is AMA-Unraid?

AMA-Unraid is a community-maintained Unraid-focused fork of Automated Music Archiver, originally created by RandomNinjaAtk.

It is designed for Unraid users who want an automated music archiving workflow that can process artist lists, download albums, clean metadata, add lyrics, apply ReplayGain, and notify Plex after imports complete.

The recommended workflow is:

DOWNLOAD_CLIENT=deemix_direct

Deemix Direct runs Deemix inside the AMA-Unraid container. New installs should use Deemix Direct unless they specifically need the older external Deemix API/WebUI container workflow.

Use this container only with accounts, content, and services you are authorized to access.

Main Features

• Internal Deemix Direct download flow.
• Safe per-album temp folder at /downloads-ama/temp.
• FLAC-first downloads with configurable fallback behavior.
• Optional conversion to ALAC, AAC, MP3, or OPUS.
• High-quality embedded and local album art.
• Native Deemix synced lyrics plus AMA/LRCLIB .lrc fallback.
• Artist tag cleanup for Plex and Roon-friendly libraries.
• ReplayGain tagging.
• Optional Plex library notification.
• Optional Lidarr artist list import.
• Legacy Deemix API mode remains available for advanced users.

Docker Image and Unraid Template Updates

Latest image:

ghcr.io/crywolf203/ama-unraid:2.5.2latest

Versioned image example:

ghcr.io/crywolf203/ama-unraid:2.5.2

Unraid template repository:

https://github.com/crywolf203/unraid-templates

The Unraid template keeps these update-tracking fields in place:

<Repository>ghcr.io/crywolf203/ama-unraid:2.5.2latest</Repository>
<Registry>https://github.com/crywolf203/ama-unraid/pkgs/container/ama-unraid</Registry>
<TemplateURL>https://raw.githubusercontent.com/crywolf203/unraid-templates/main/templates/ama-unraid.xml</TemplateURL>
<Project>https://github.com/crywolf203/ama-unraid</Project>
<Support>https://github.com/crywolf203/unraid-templates/issues</Support>

That lets Unraid continue tracking the container image and template metadata.

Required and Optional Paths

Recommended Direct-mode paths

Do not map /downloads-ama/temp separately. AMA creates, cleans, and manages that folder internally per album.

Optional Deemix login path

New Direct-mode installs can use ARL_TOKEN instead of mapping a separate Deemix config folder.

Legacy API-only path

Deemix Login

Deemix Direct needs one of these:

ARL_TOKEN=your_arl_token_here

or:

/deemix-config/login.json

Recommended for new Unraid users:

ARL_TOKEN=your_arl_token_here

Do not publish your ARL_TOKEN or login.json.

Basic Usage

1. Set DOWNLOAD_CLIENT=deemix_direct.
2. Map /config to your AMA appdata folder.
3. Map /downloads-ama to your final music library.
4. Set ARL_TOKEN or provide /deemix-config/login.json.
5. Add artist files to /config/list.
6. Start AMA manually or enable AUTOSTART=true.

Start manually:

docker exec -it AMA-Unraid bash -lc 'bash /config/scripts/start.bash'

Watch Docker logs:

docker logs -f --tail=300 AMA-Unraid

View saved run logs:

docker exec -it AMA-Unraid bash -lc 'ls -lah /config/logs && tail -f -n 300 "$(ls -t /config/logs/*.log | head -1)"'

Artist List Files

AMA processes artists from:

/config/list

Artist files should use this format:

DEEZER_ARTIST_ID-Artist Name.file

Examples:

9262400-Jessie Reyez.file
85065212-Leon Thomas.file
5828-DJ Khaled.file

To process only one artist from the Unraid host:

mkdir -p /mnt/cache/appdata/ama-unraid/list
rm -f /mnt/cache/appdata/ama-unraid/list/*
touch "/mnt/cache/appdata/ama-unraid/list/5828-DJ Khaled.file"

Artist Mode vs Discography Mode

The existing AMA variable is:

MODE=artist

Supported values:

artist
discography

artist mode downloads albums listed directly under the selected artist.

discography mode downloads albums listed under the selected artist plus albums where that artist appears as a contributor or featured artist.

Recommended default:

MODE=artist

Use artist for tighter libraries. Use discography when you want the broadest possible collection and do not mind featured-artist or contributor albums being included.

Variable Reference

The table below mirrors the Unraid template order and keeps the app repo and template descriptions in sync.

Core setup

Format, quality, and conversion

Artwork

Library discovery and filtering

Post-processing and permissions

Lidarr

Plex

Optional and legacy Deemix paths

Recommended Defaults

DOWNLOAD_CLIENT=deemix_direct
MODE=artist
AUTOSTART=false
SCRIPTINTERVAL=7d
FORMAT=FLAC
BITRATE=320
FORCECONVERT=false
REQUIRE_QUALITY=false
DEEMIX_FALLBACK_BITRATE=true
DEEMIX_QUEUE_CONCURRENCY=1
DEEMIX_EMBEDDED_ARTWORK_SIZE=1400
DEEMIX_LOCAL_ARTWORK_SIZE=1400
DEEMIX_JPEG_IMAGE_QUALITY=100
REPLAYGAIN=true
ENABLE_ARTIST_TAG_CLEANUP=true
ENABLE_TAG_NORMALIZER=false
NOTIFYPLEX=false
LIDARR_LIST_IMPORT=false
FILE_PERMISSIONS=777
FOLDER_PERMISSIONS=777

Deemix Direct Flow

The safe direct-temp flow works like this:

1. AMA cleans /downloads-ama/temp before each album.
2. Deemix downloads the album directly into /downloads-ama/temp.
3. AMA finds the downloaded album folder.
4. AMA adds the album ID to the temporary album folder when needed.
5. AMA runs lrc_fallback.py with /downloads-ama/temp and the album ID.
6. AMA flattens audio files, .lrc files, and cover.jpg into /downloads-ama/temp.
7. AMA continues import, tag cleanup, ReplayGain, permissions, and Plex notification.

Deemix Direct writes its runtime config under:

/config/deemix/xdg/deemix/config.json

It does not need a separate Deemix Downloads folder.

Bitrate Fallback

Deemix Direct supports:

DEEMIX_FALLBACK_BITRATE=true

When enabled, Deemix can fall back to another available quality if the requested quality is unavailable.

Example: if FORMAT=FLAC is requested but FLAC is unavailable, Deemix may download MP3, M4A, or OPUS instead of failing the album.

The direct script logs the setting and final file summary:

DEEMIX_DIRECT :: fallbackBitrate=True
DEEMIX_DIRECT :: requested=FLAC actual_summary flac=0 mp3=1 m4a=0 opus=0
DEEMIX_DIRECT :: WARNING fallback format used because requested FLAC was unavailable

Use stricter settings if you do not want fallback behavior:

DEEMIX_FALLBACK_BITRATE=false
REQUIRE_QUALITY=true

Conversion Notes

FORMAT controls the desired final format.

• FLAC keeps lossless files when available.
• ALAC converts lossless FLAC to Apple-friendly ALAC/M4A.
• AAC converts lossless FLAC to AAC/M4A using BITRATE.
• MP3 downloads or converts to MP3 depending on bitrate and source availability.
• OPUS converts lossless FLAC to OPUS using BITRATE.

Recommended default:

FORMAT=FLAC
FORCECONVERT=false

Set FORCECONVERT=true only when you intentionally want AMA to force the library into the requested output format.

Artist Tag Cleanup

Artist cleanup is enabled by default:

ENABLE_ARTIST_TAG_CLEANUP=true

It keeps featured artists in the track title while keeping ARTIST and ALBUMARTIST clean.

Supported cleanup formats:

.flac
.mp3
.m4a
.opus

Example before cleanup:

TITLE=Crash & Burn (Remix)
ARTIST=Leon Thomas;Blxst
album_artist=Leon Thomas

Example after cleanup:

TITLE=Crash & Burn (Remix) (feat. Blxst)
ARTIST=Leon Thomas
ALBUMARTIST=Leon Thomas

Timed LRC Lyric Fallback

After Deemix finishes downloading an album, AMA checks for .lrc files.

If Deemix does not provide timed lyrics, AMA attempts to find synced lyrics from LRCLIB.

Possible outcomes:

Created timed .lrc from LRCLIB synced
Created plain .lrc from LRCLIB plain
Created plain .lrc from embedded plain lyrics
No lyrics found

For Deemix Direct, fallback runs with:

lrc_fallback.py /downloads-ama/temp ALBUM_ID

Plex Scan Path Override

If Plex sees the music path differently than AMA, set:

PLEXSCANPATH=/media/music

Example:

• AMA writes to /downloads-ama/Artist/Album.
• Plex sees the same files as /media/music/Artist/Album.
• PLEXSCANPATH=/media/music tells AMA to notify Plex using the Plex-visible path.

Docker Compose Example

services:
  ama-unraid:2.5.2
    image: ghcr.io/crywolf203/ama-unraid:2.5.2latest
    container_name: AMA-Unraid
    restart: unless-stopped
    network_mode: bridge
    environment:
      TZ: "America/New_York"
      PUID: "99"
      PGID: "100"
      AUTOSTART: "false"
      SCRIPTINTERVAL: "7d"
      DOWNLOAD_CLIENT: "deemix_direct"
      MODE: "artist"
      ARL_TOKEN: "YOUR-ARL-TOKEN"
      FORMAT: "FLAC"
      BITRATE: "320"
      FORCECONVERT: "false"
      REQUIRE_QUALITY: "false"
      DEEMIX_FALLBACK_BITRATE: "true"
      DEEMIX_QUEUE_CONCURRENCY: "1"
      DEEMIX_EMBEDDED_ARTWORK_SIZE: "1400"
      DEEMIX_LOCAL_ARTWORK_SIZE: "1400"
      DEEMIX_JPEG_IMAGE_QUALITY: "100"
      REPLAYGAIN: "true"
      ENABLE_ARTIST_TAG_CLEANUP: "true"
      ENABLE_TAG_NORMALIZER: "false"
      NOTIFYPLEX: "false"
      LIDARR_LIST_IMPORT: "false"
      FILE_PERMISSIONS: "777"
      FOLDER_PERMISSIONS: "777"
    volumes:
      - /mnt/cache/appdata/ama-unraid:2.5.2/config:rw
      - /mnt/user/media/music:/downloads-ama:rw

Optional login.json volume if you do not use ARL_TOKEN:

      - /mnt/cache/appdata/Deemix-1:/deemix-config:rw

Docker CLI Example

docker run -d \
  --name AMA-Unraid \
  --restart unless-stopped \
  --net bridge \
  -e TZ="America/New_York" \
  -e PUID="99" \
  -e PGID="100" \
  -e AUTOSTART="false" \
  -e SCRIPTINTERVAL="7d" \
  -e DOWNLOAD_CLIENT="deemix_direct" \
  -e MODE="artist" \
  -e ARL_TOKEN="YOUR-ARL-TOKEN" \
  -e FORMAT="FLAC" \
  -e BITRATE="320" \
  -e FORCECONVERT="false" \
  -e REQUIRE_QUALITY="false" \
  -e DEEMIX_FALLBACK_BITRATE="true" \
  -e DEEMIX_QUEUE_CONCURRENCY="1" \
  -e DEEMIX_EMBEDDED_ARTWORK_SIZE="1400" \
  -e DEEMIX_LOCAL_ARTWORK_SIZE="1400" \
  -e DEEMIX_JPEG_IMAGE_QUALITY="100" \
  -e REPLAYGAIN="true" \
  -e ENABLE_ARTIST_TAG_CLEANUP="true" \
  -e ENABLE_TAG_NORMALIZER="false" \
  -e NOTIFYPLEX="false" \
  -e LIDARR_LIST_IMPORT="false" \
  -e FILE_PERMISSIONS="777" \
  -e FOLDER_PERMISSIONS="777" \
  -v /mnt/cache/appdata/ama-unraid:2.5.2/config:rw \
  -v /mnt/user/media/music:/downloads-ama:rw \
  ghcr.io/crywolf203/ama-unraid:2.5.2latest

Testing Deemix Direct

Test one album URL:

docker exec -it AMA-Unraid bash -lc '
DOWNLOAD_CLIENT=deemix_direct \
FORMAT=FLAC \
DEEMIX_FALLBACK_BITRATE=true \
bash /config/scripts/deemix_direct_download.bash "https://www.deezer.com/album/ALBUM_ID"
'

Check temp-root output:

docker exec -it AMA-Unraid bash -lc 'find /downloads-ama/temp -maxdepth 1 -type f | sort'

Expected examples:

/downloads-ama/temp/01 - Track.flac
/downloads-ama/temp/01 - Track.lrc
/downloads-ama/temp/cover.jpg

If FLAC is unavailable and fallback is enabled, the audio file may be a fallback format:

/downloads-ama/temp/01 - Track.mp3
/downloads-ama/temp/01 - Track.lrc
/downloads-ama/temp/cover.jpg

Legacy External Deemix API Mode

The older external Deemix API workflow remains available:

DOWNLOAD_CLIENT=deemix_api

This mode requires a separate running Deemix WebUI/API container.

Legacy variables:

DEEMIX_API_URL=http://SERVER-IP:6595
DEEMIX_CONFIG_PATH=/deemix-config
DEEMIX_DOWNLOAD_PATH=/deemix-downloads

Legacy extra path:

/mnt/user/media2/deemix-1:/deemix-downloads:rw

New installs should prefer Deemix Direct.

Troubleshooting

Container starts but AMA does not run

If the log shows:

Automatic Start Disabled, manually run using this command:
bash /config/scripts/start.bash

Either start manually:

docker exec -it AMA-Unraid bash -lc 'bash /config/scripts/start.bash'

or set:

AUTOSTART=true

Deemix Direct cannot log in

Confirm one of these is configured:

ARL_TOKEN=your_arl_token_here

or:

/deemix-config/login.json

FLAC was requested but MP3, M4A, or OPUS was downloaded

This can happen when fallback is enabled and FLAC is unavailable.

Check the Deemix Direct log for:

DEEMIX_DIRECT :: fallbackBitrate=True
DEEMIX_DIRECT :: requested=FLAC actual_summary flac=0 mp3=1 m4a=0 opus=0

Lyrics are missing

Check the direct log:

docker exec -it AMA-Unraid bash -lc '
grep -nE "Running LRC fallback|LRC summary|Missing LRC|Created timed|Created plain|No lyrics" /config/logs/*.log | tail -n 200
'

Permission issues

Check:

PUID=99
PGID=100
FILE_PERMISSIONS=777
FOLDER_PERMISSIONS=777

Also confirm /downloads-ama is mapped read/write.

Development Notes

Useful repo path on Unraid:

cd /mnt/cache/appdata/ama-unraid

Validate the Deemix Direct Bash script:

bash -n root/scripts/deemix_direct_download.bash

Validate the artist cleanup Python script:

python3 -m py_compile root/scripts/artist_tag_cleanup.py

Related Projects

Credits

AMA-Unraid builds on the work of several open-source projects and maintainers.

• RandomNinjaAtk for the original AMA project.
• crywolf203 for maintaining and extending AMA-Unraid.
• bambanah for the revived Deemix project.
• RemixDev for the original Deemix project.
• Bockiii for Deemix Docker inspiration.

Funding

If this Unraid-focused fork, template work, documentation, or troubleshooting saves you time, you can support this maintenance work here:

https://buymeacoffee.com/crywolf203

Disclaimer

Use this container only with accounts, content, and services you are authorized to access.

This repository does not claim ownership of upstream projects. It packages, documents, and extends the workflow for Unraid users.