Identify music from the command line with the AudD CLI

audd is AudD’s command-line tool. It covers what most projects first need from the API (identify a song, tag a folder, list the tracks in a mix, follow a radio stream) without writing any code. This recipe walks through those four jobs, then shows how to use the same commands in a shell script.

Install and sign in

Pick whichever package manager you already have:

npx @audd/cli version                 # Node.js, no install
uvx audd-cli version                  # Python, no install
brew install auddmusic/tap/audd       # macOS

Scoop, Docker, go install, and a one-line install script are listed in the CLI docs. Then sign in:

audd login

audd login opens the browser to approve the sign-in, or prints a code to approve it from another device when you’re on a server. It fetches your API token for you. If you already have a token, set it instead:

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 a column per field: artist, title, album, release_date, label, isrc, upc, song_link, and more. The status column says matched, no_match, or failed, so files without a match stay in the CSV and you can see which ones to check by hand.

Every batch is saved as a job after each file. If the run stops (Ctrl-C, a dropped connection, a closed laptop), nothing finished is lost:

audd jobs list
audd jobs resume <id>

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

3. Turn a mix into a tracklist

A DJ set or a radio show recording holds many songs, so it goes to 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 the full cost of the file. --tracklist merges consecutive matches into one entry per track with its start and end time in the mix.

Start with a small --limit on a new kind of recording to check the results before you scan 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. AudD then identifies every song that plays on it. audd now-playing shows the latest song on each stream with its cover art and what played before.

The first streams command starts a small 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

Piped into another program, every command prints JSON instead of a table, and every document carries "schema_version": 1:

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

--fields keeps only what you need, 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, nothing can be confirmed by hand, so a batch needs --yes. The exit code tells a script what happened: 0 for success (for a single file, no match counts as success), 1 when a batch finished with files that had no match, 3 for a sign-in or token problem, 4 for quota, 5 for network, 6 when a safety limit stopped the command, and 7 when some files in a batch failed. For example, 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