https://github.com/loiccoyle/audd-cli
🎵 CLI music recognition using the AudD API
https://github.com/loiccoyle/audd-cli
audd cli music music-recognition shazam
Last synced: 12 months ago
JSON representation
🎵 CLI music recognition using the AudD API
- Host: GitHub
- URL: https://github.com/loiccoyle/audd-cli
- Owner: loiccoyle
- License: mit
- Created: 2021-06-18T20:19:10.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2021-08-13T21:01:18.000Z (almost 5 years ago)
- Last Synced: 2025-04-29T06:32:55.099Z (about 1 year ago)
- Topics: audd, cli, music, music-recognition, shazam
- Language: Shell
- Homepage:
- Size: 17.6 KB
- Stars: 9
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# audd-cli
Record audio and use the [AudD](https://audd.io) music recognition API from the command line.
The [`audd`](./audd) scripts queries the AudD API. This repository also contains [`audd-notif`](./audd-notif) which uses [`audd`](./audd) and `libnotify` to return the match result.
## Dependencies:
The `audd` script requires:
- [curl](https://github.com/curl/curl)
- [ffmpeg](https://git.ffmpeg.org/ffmpeg.git)
In addition to the above the `audd-notif` script requires:
- [jq](https://github.com/stedolan/jq)
- notify-send
- [dunstify](https://github.com/dunst-project/dunst) (optional)
## Installation
#### Manual
Just clone this repo and place the `audd` and `audd-notif` scripts on your `$PATH`.
#### Arch (AUR):
Using your favourite AUR helper:
```sh
$ paru -S audd-cli-git
```
## Usage
```
$ audd -h
Usage: audd [OPTION]... [FILE]
Query the AudD music recognition API.
Get a free API token at: https://audd.io/
The API token can be read from file:
$ echo "api-token" > "~/.config/audd/api_token"
If no FILE is provided, a recording is made using the AUDIO_SOURCE.
Usage:
-h Show this message and exit.
-a API_KEY AudD API token.
-s AUDIO_SOURCE ffmpeg audio input source, (default: "default").
-t RECORDING_TIME Length of recording time, in seconds, (default: 3).
-r API_RETURN AudD API return parameter, see https://docs.audd.io/,
(default: "apple_music,spotify").
-o Use the "recognizeWithOffset" endpoint.
```
To use `audd` you will need to get an API key from [audd]([https://audd.io).
Provide the API key with either the `-a` option or by writing the API key to `${XDG_CONFIG_HOME:-$HOME/.config}/audd/api_token`:
```sh
$ echo "api-token" > "~/.config/audd/api_token"
```
`audd` can perform a query using an audio file (the file shouldn't be too large, typically shorter than 20 seconds), or if no file is provided, it will record an audio sample from the provided audio source (`-s` option).
You can use `ffmpeg -sources pulse` to list available sources.
I recommend reading the [API docs](https://docs.audd.io/) to understand the `-r` and the `-o` options.