Recipe

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.

view .md auddclicommand lineterminal

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

WhereCommand
Node.jsnpm install -g @audd/cli
Pythonpipx 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
Gogo install github.com/AudDMusic/audd-cli/cmd/audd@latest
Any systemdownload 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:

OptionWhat it does
--max-files NRequired for a batch, so a typo in a path can’t send ten thousand files
--dry-runPrints how many files the CLI found and how many requests the run would use, without sending anything
--format csvWrites 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-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.

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

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.