@emgeebee/airfreyr

@emgeebee/airfreyr

Download music from YouTube. Fork of freyr-js with an HTTP queue server for remote track requests.

Requirements

• Node.js >= 16
• Python >= 3.2 (for youtube-dl-exec)
• AtomicParsley on your PATH

Installation

npm install -g @emgeebee/airfreyr
# or
npx @emgeebee/airfreyr <command>

From source:

git clone https://github.com/emgeebee/air-freyr.git && cd air-freyr
npm install && npm link

Queue server

Run an HTTP server that appends tracks to queue files and triggers downloads automatically.

airfreyr serve

Configuration

Precedence: CLI flags → environment variables → conf.json → defaults.

Flag	Env	conf.json	Purpose
-q, --queue-dir <DIR>	AIRFREYR_QUEUE_DIR	serve.queueDir	Queue .json files directory
-D, --output-dir <DIR>	AIRFREYR_OUTPUT_DIR	dirs.output	Download output directory
-p, --port <PORT>	AIRFREYR_PORT	serve.port	Listen port (default: 3797)
-H, --hostname <HOST>	AIRFREYR_HOSTNAME	serve.hostname	Bind address

"serve": {
  "hostname": "localhost",
  "port": 3797,
  "queueDir": "."
},
"dirs": {
  "output": "./0"
}

Downloads use dirs.output unless overridden by -D or AIRFREYR_OUTPUT_DIR.

AIRFREYR_QUEUE_DIR=./queues AIRFREYR_OUTPUT_DIR=./music airfreyr serve

API

All responses include "version" (the running @emgeebee/airfreyr package version).

POST /add — append a track and start downloading the queue file.

{
  "file": "kids.json",
  "genre": "Kids",
  "artist": "Moana",
  "title": "You're Welcome",
  "path": "https://www.youtube.com/watch?v=G8QjumNNNBY"
}

• title is optional
• path can also be sent as url
• Existing tracks in the file are skipped; only new lines are downloaded
• If a download is already running for that file, another run is queued when it finishes

GET /status?file=kids.json — check whether a download is in progress (includes lastError if the last run failed)

curl 'http://<nas-ip>:3797/status?file=kids.json'

Example when a download failed:

{
  "version": "1.0.1",
  "ok": true,
  "file": "kids.json",
  "download": {
    "running": false,
    "pending": false,
    "lastError": "airfreyr exited with code 2",
    "lastExitCode": 2,
    "lastStartedAt": "2026-06-22T20:15:00.000Z",
    "lastFinishedAt": "2026-06-22T20:15:42.000Z"
  }
}

If lastError is set, check container logs for detail: sudo docker logs --tail 100 airfreyr

GET /health — server status and configured directories

curl -X POST http://localhost:3797/add \
  -H 'Content-Type: application/json' \
  -d '{"file":"kids.json","genre":"Kids","artist":"Moana","title":"You'\''re Welcome","path":"https://www.youtube.com/watch?v=G8QjumNNNBY"}'

Batch downloads

Download tracks listed in a queue file:

airfreyr -i kids.json
airfreyr -i kids.json -d ./music   # custom output directory

Queue file format

Queue files are JSON with an entries array. Each entry has artist, title, url, and optional disabled, note, and genre (when different from the list name).

{
  "entries": [
    {
      "artist": "Moana",
      "title": "You're Welcome",
      "url": "https://www.youtube.com/watch?v=G8QjumNNNBY"
    },
    {
      "artist": "Peppa Pig",
      "title": "Jumping in Muddy Puddles",
      "url": "https://www.youtube.com/watch?v=t7dTdE8Aqtw",
      "disabled": true,
      "note": "already have this"
    }
  ]
}

Genre defaults from the filename: kids.json → Kids, folk rock.json → Folk Rock.

The queue UI and API still accept CSV lines for bulk paste (artist,title,url). Legacy .txt CSV files are migrated to .json automatically when the server starts.

Files are organised as <output>/<genre>/youtube/<artist> - <title>.<format>.

CLI

airfreyr <url-or-uri>              # download a single track
airfreyr -i queues/kids.json         # batch download from file
airfreyr serve                     # start the queue server
airfreyr urify <url>               # convert URLs to service URIs
airfreyr --help                    # full options

Common flags:

Flag	Purpose
-d, --directory <DIR>	Output directory
-f, --force	Overwrite existing files
-b, --bitrate <N>	Audio bitrate (default: 320k)
-x, --format <FORMAT>	Output format (default: mp3)
--no-logo / --no-header	Quieter output

Configuration

On first run, airfreyr creates a user config file with service credentials and defaults:

• Linux: ~/.config/AirFreyr/d3fault.x4p
• macOS: ~/Library/Preferences/AirFreyr/d3fault.x4p

Project defaults live in conf.json. Use -o, --config <FILE> to point at an alternative.

Docker (queue server)

A minimal node:20-alpine image runs npx @emgeebee/airfreyr@latest serve and restarts every 3 hours to pull the latest npm publish.

Quick start (build once)

mkdir -p docker/queues docker/music docker/config
cp docker/conf.json.example docker/config/conf.json

cd docker
docker compose up --build

No build — plain node:alpine

If you only want the stock Node image plus a mounted entrypoint script:

cd docker
docker compose -f compose.alpine.yml up -d

This uses node:20-alpine directly. Python is installed on first start (apk add python3 bash), then the entrypoint runs npx.

Queue files go in docker/queues/ (e.g. kids.json). Downloads land in docker/music/.

docker run (without compose)

docker build -f docker/Dockerfile -t airfreyr-serve .

docker run -d --name airfreyr \
  --restart unless-stopped \
  -p 3797:3797 \
  -e AIRFREYR_HOSTNAME=0.0.0.0 \
  -e AIRFREYR_REFRESH_HOURS=3 \
  -v "$PWD/queues:/data/queues" \
  -v "$PWD/music:/data/music" \
  -v "$PWD/config:/data/config" \
  airfreyr-serve

Put conf.json at config/conf.json inside the mounted config volume.

Synology Container Manager

Use docker/synology-compose.yml and docker/conf.json.example.

1. Create folders on the NAS

In File Station, create:

/volume1/docker/airfreyr/queues    ← queue .json files (kids.json, pop.json, …)
/volume1/docker/airfreyr/music     ← downloaded tracks
/volume1/docker/airfreyr/config    ← conf.json

Change volume1 if your shared folder lives on a different volume.

2. Copy config and compose onto the NAS

NAS path	Source in repo
/volume1/docker/airfreyr/config/conf.json	docker/conf.json.example
/volume1/docker/airfreyr/docker-compose.yml	docker/synology-compose.yml

Edit paths in docker-compose.yml if not using volume1. Put queue files in queues/.

3. Create the container project

Container Manager → Project → Create

• Project name: airfreyr
• Path: /volume1/docker/airfreyr/docker-compose.yml
• Start the project (pulls node:20-alpine, no build step)

Directory mappings

NAS folder	Container path	Purpose
/volume1/docker/airfreyr/queues	/data/queues	Queue .json files
/volume1/docker/airfreyr/music	/data/music	Downloaded music
/volume1/docker/airfreyr/config	/data/config	conf.json (+ saved auth after first run)

Port

Map host port 3797 → container 3797. Then from your LAN:

curl http://<nas-ip>:3797/health

Manual container (UI fields)

If you prefer Container → Create instead of a Project:

Setting	Value
Image	node:20-alpine
Command	apk add --no-cache python3 bash && exec /entrypoint.sh
Entrypoint	mount serve-entrypoint.sh → /entrypoint.sh
Port	3797:3797
AIRFREYR_HOSTNAME	0.0.0.0
AIRFREYR_QUEUE_DIR	/data/queues
AIRFREYR_OUTPUT_DIR	/data/music
AIRFREYR_CONFIG	/data/config/conf.json
Volume	/volume1/docker/airfreyr/queues → /data/queues
Volume	/volume1/docker/airfreyr/music → /data/music
Volume	/volume1/docker/airfreyr/config → /data/config
Restart policy	Unless stopped

The container runs npx @emgeebee/airfreyr@latest serve and refreshes every 3 hours.

"Build project failed" (no useful logs)

Synology often shows only Build project '…' failed with no detail. The real error is elsewhere.

1. Check the folders exist first (most common cause):

ls -la /volume1/docker/airfreyr/queues
ls -la /volume1/docker/airfreyr/music
ls -la /volume1/docker/airfreyr/config/conf.json

Synology will fail if any mapped folder or conf.json is missing.

2. Get the real error via SSH (Control Panel → Terminal & SNMP → Enable SSH):

cd /volume1/docker/airfreyr
sudo docker compose config          # validate compose syntax
sudo docker compose up              # run in foreground — errors print here
# or after a failed project start:
sudo docker compose logs --tail 50
sudo docker logs airfreyr 2>&1

3. In Container Manager UI

• Container → select airfreyr → Details → Log tab (runtime logs, after container starts)
• Project → your project → Action → delete and recreate after fixing paths
• Log Center → search for docker / container around the failure time

4. Common fixes

Problem	Fix
Volume path wrong	Use absolute paths; edit volume1 in docker-compose.yml
conf.json missing	Copy docker/conf.json.example to config/conf.json
Old project stuck	Delete project + container, recreate
Still using build:	Use docker/synology-compose.yml — it has no build step
Port in use	Change 3797:3797 to e.g. 3798:3797

Environment

Variable	Default	Purpose
AIRFREYR_HOSTNAME	0.0.0.0	Bind address (use 0.0.0.0 in Docker)
AIRFREYR_PORT	3797	HTTP port
AIRFREYR_QUEUE_DIR	/data/queues	Queue .json directory
AIRFREYR_OUTPUT_DIR	/data/music	Download output directory
AIRFREYR_CONFIG	/data/config/conf.json	Config file for download runs
AIRFREYR_REFRESH_HOURS	3	Restart interval to pull latest from npm
AIRFREYR_REFRESH_SECONDS	—	Override refresh interval in seconds

On each restart the entrypoint clears the npx cache and runs npx --yes @emgeebee/airfreyr@latest serve.

Publishing to npm

Pushes to main or master run .github/workflows/publish.yml, matching the simple pipeline in phone_cli:

1. npm ci
2. npm publish --access public

Uses npm trusted publishing (OIDC, no NPM_TOKEN secret). On npmjs.com, link the GitHub repo to the @emgeebee scope before the first publish.

You can also trigger manually: Actions → publish → Run workflow.

Test the API

curl http://localhost:3797/health

curl -X POST http://localhost:3797/add \
  -H 'Content-Type: application/json' \
  -d '{"file":"kids.json","genre":"Kids","artist":"Moana","title":"You'\''re Welcome","path":"https://www.youtube.com/watch?v=G8QjumNNNBY"}'

License

Apache-2.0. Based on freyr-js by Miraculous Owonubi.