Identify music from the command line with the AudD CLI

audd is AudD’s command-line tool. This recipe uses it to identify a song, tag a folder of audio, list the tracks in a mix, and follow a radio stream, then puts the same commands in a shell script.

Install

Where	Command
Node.js	npm install -g @audd/cli
Python	pipx install audd-cli or uv tool install audd-cli
macOS (Homebrew)	brew install auddmusic/tap/audd
macOS, Linux (script)	curl -fsSL https://github.com/AudDMusic/audd-cli/releases/latest/download/install.sh | sh
Windows (Scoop)	scoop bucket add auddmusic https://github.com/AudDMusic/scoop-bucket then scoop install auddmusic/audd
Windows (installer)	download and run the installer for x64 or ARM64; it adds audd to your PATH
Go	go install github.com/AudDMusic/audd-cli/cmd/audd@latest
Any system	download an archive from the releases page and put audd on your PATH

The install script puts audd in ~/.local/bin and checks the download against the release’s checksums. --at clips and audd listen also need ffmpeg.

Run it without installing

npx @audd/cli recognize song.mp3          # Node.js
uvx audd-cli recognize song.mp3           # Python
docker run --rm -e AUDD_API_TOKEN -v "$PWD:/work" ghcr.io/auddmusic/audd-cli recognize song.mp3

The commands below write audd. With npx or uvx, put npx @audd/cli or uvx audd-cli in its place.

Sign in

audd login

audd login opens the browser to approve the sign-in and saves your API token. On a server, it prints a code to approve from another device instead. If you already have a token, set it:

export AUDD_API_TOKEN=your-api-token

Get your own token at dashboard.audd.io.

1. Identify one song

audd recognize song.mp3
audd recognize https://audd.tech/example.mp3

On a terminal you get a card with the cover art, artist, title, album, label, and a link to listen. Add --return apple_music,spotify for the streaming services’ IDs and metadata.

The standard endpoint analyzes up to the first 12 seconds of audio. If the song you want starts later in the file, send a clip from that moment:

audd recognize recording.mp3 --at 2:15      # needs ffmpeg

audd listen records from the microphone and identifies what’s playing near you.

2. Tag a folder of audio files into a CSV

audd recognize ./archive --max-files 500 --dry-run

A folder is a batch, and a batch always needs --max-files, so a typo in a path can’t send ten thousand files. --dry-run prints how many files it found and how many requests the run would use, without sending anything. When the plan looks right:

audd recognize ./archive --max-files 500 --format csv > archive.csv

The CLI asks you to confirm, then writes one row per file with columns such as artist, title, album, release_date, label, isrc, upc, and song_link. The status column is matched, no_match, or failed. Files without a match stay in the CSV, so you can check them by hand.

A batch saves its progress after each file. If the run stops (Ctrl-C, a dropped connection), resume it:

audd jobs list
audd jobs resume <id>

Results are cached by file contents, so running the same folder again doesn’t spend requests on files already identified.

3. Turn a mix into a tracklist

A DJ set or a recorded radio show has many songs in it, so use the enterprise endpoint, which scans the whole file. Enterprise is billed per 12 seconds of audio scanned, so it needs a limit on how many chunks to scan:

audd recognize set.mp3 --enterprise --limit 20 --dry-run
audd recognize set.mp3 --enterprise --limit none --tracklist

The dry run shows what the whole file would cost. --tracklist merges consecutive matches into one entry per track, with its start and end time in the mix. On a new kind of recording, try a small --limit and check the results before scanning whole files.

4. Watch a radio stream

audd streams add https://radio.example/stream.mp3 --id 1
audd now-playing

audd streams add subscribes the stream to recognition, and AudD identifies every song played on it. audd now-playing shows the latest song on each stream with its cover art and what played before it.

The first streams command starts a background recorder that saves every result locally, so you can report on a stream later:

audd streams history --since 24h
audd streams report --by artist --since 30d
audd streams export --since 7d --format csv > plays.csv

By default AudD sends a stream’s result when the song ends, with how long it played. Add the stream with --start to get each song when it starts instead.

Use it in a script

When its output is piped, every command prints JSON instead of a table, with "schema_version": 1 in each document:

audd recognize song.mp3 | jq -r '.result | "\(.artist) — \(.title)"'

--fields limits the output to the fields you name, and --format csv works for any command that prints rows:

audd recognize ./inbox --max-files 100 --yes --fields artist,title,isrc --format csv

Without a terminal there’s no one to answer the confirmation prompt, so a batch needs --yes.

Exit codes:

• 0: success, including files with no match (pass --fail-on-no-match to exit 1 instead).
• 3: sign-in or token problem.
• 4: quota.
• 5: network.
• 6: a safety limit stopped the command.
• 7: some files in a batch failed.

A cron job that warns before your requests run out:

audd usage --check --min-remaining 1000 || echo "AudD requests are running low" | mail -s "AudD quota" [email protected]

audd usage --check exits 8 when fewer requests remain than you asked for.

Where to go next

• CLI docs for every command and flag
• Standard vs. enterprise vs. streams to pick the right endpoint when you move from the CLI to code
• Official SDKs for the same API from Python, Node, Go, and eight more languages