Identify music from the command line with the AudD CLI
Use the audd command-line tool to identify songs in files and URLs, tag a folder of audio into a CSV, build a tracklist from a mix, and watch your streams, with no code.
audd is the command-line tool for AudD. In this recipe, you’ll use it to
identify a song, tag a folder of audio, list the tracks in a mix, and follow a
radio stream. Then you’ll put 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.
Making clips with --at and running audd listen also require
ffmpeg to be installed.
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
Where the commands below say audd, you can use npx @audd/cli or
uvx audd-cli instead.
Sign in
audd login
audd login will direct you to your browser to approve the sign-in, after
which it saves your API token. On a server, a code is displayed instead, so
you can approve the sign-in from another device. If you already have a token,
set up an environment variable that stores 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
In a terminal, you see a card with the cover art, artist, title, album,
label, and a link to listen. For the IDs and metadata from the streaming
services, add --return apple_music,spotify.
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 with
--at:
audd recognize recording.mp3 --at 2:15 # needs ffmpeg
You can also use audd listen to record from the microphone and identify the
music playing near you.
2. Tag a folder of audio files into a CSV
audd recognize ./archive --max-files 500 --dry-run
When you pass a folder, the CLI treats it as a batch of audio files. The following options matter for a batch:
| Option | What it does |
|---|---|
--max-files N | Required for a batch, so a typo in a path can’t send ten thousand files |
--dry-run | Prints how many files the CLI found and how many requests the run would use, without sending anything |
--format csv | Writes one row per file, with columns such as artist, title, album, release_date, label, isrc, upc, and song_link |
When the dry run looks right:
audd recognize ./archive --max-files 500 --format csv > archive.csv
The CLI asks you to confirm before it sends anything. In the CSV, 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), you can resume it with the following commands:
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. To recognize them, use the enterprise endpoint. It scans the whole file. Enterprise is billed per 12 seconds of scanned audio, so it requires 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 first command shows what the whole file would cost. With --tracklist,
consecutive matches are merged into one entry per track, with its start and end
time in the mix. Before scanning whole files of a new kind of recording, try a
small --limit and check the results.
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. AudD will then
identify every song played on it. audd now-playing shows the latest song on
each stream with its cover art, as well as the songs 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 will send a stream’s result when the song ends, with how
long it played. Adding the stream with --start makes AudD send each song when
it starts instead.
Use it in a script
When a command’s output is piped, it is printed as JSON instead of a table,
with "schema_version": 1 in each document:
audd recognize song.mp3 | jq -r '.result | "\(.artist) — \(.title)"'
You can limit the output to the fields you name using the --fields flag, 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 for a
batch you must include the --yes flag to skip it.
The CLI uses the following exit codes:
- 0: success, including files with no match (pass
--fail-on-no-matchto 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.
Below is an example of a cron job that warns you 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 with code 8 when fewer requests remain than you
asked for with --min-remaining.
Where to go next
- For full details of every command and flag, see the CLI docs.
- Standard vs. enterprise vs. streams helps you 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.
Reading this as an AI agent? The raw Markdown is at recipes/command-line-music-recognition.md, and the full index is /resources/llms.txt.
