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
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
The commands below write audd. With npx or uvx, put npx @audd/cli or uvx audd-cli in its place.
Sign in
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:
Get your own token at dashboard.audd.io.
1. Identify one song
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 listen records from the microphone and identifies what’s playing near you.
2. Tag a folder of audio files into a CSV
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:
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:
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:
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 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:
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:
--fields limits the output to the fields you name, and --format csv works for any command that prints rows:
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 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
