AudD Humming Recognition API
Identifies a song from a recording of a person humming or singing the melody, delivered through the recognizeWithOffset method against the AudD humming database.
OpenAPI Specification
openapi: 3.0.1
info:
title: AudD Music Recognition API
description: >-
AudD is a music recognition service. The API identifies songs from an
uploaded audio file, a remote audio/video URL, or base64-encoded audio and
returns rich track metadata. It also supports recognition with offset
(including humming/singing) and lyrics search. All methods authenticate with
an `api_token` and accept either form-encoded or multipart/form-data input.
termsOfService: https://audd.io/terms/
contact:
name: AudD Support
email: api@audd.io
url: https://audd.io/
version: '1.0'
servers:
- url: https://api.audd.io
description: Primary music recognition and lyrics API
- url: https://enterprise.audd.io
description: Enterprise endpoint for scanning long audio/video files
paths:
/:
post:
operationId: recognize
tags:
- Recognition
summary: Recognize music from a file, URL, or base64 audio
description: >-
Identifies a song from a short audio sample. Provide the audio as a
multipart file upload, a remote `url`, or a base64-encoded `audio`
string. Returns matched track metadata and, optionally, links to
streaming services.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/RecognizeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RecognizeRequest'
responses:
'200':
description: Recognition result
content:
application/json:
schema:
$ref: '#/components/schemas/RecognizeResponse'
/recognizeWithOffset/:
post:
operationId: recognizeWithOffset
tags:
- Recognition
summary: Recognize music and return the offset of the match
description: >-
Recognition variant that returns the offset (position) of the matched
fragment within the submitted audio. This is also the method used for
recognition by humming or singing a melody.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/RecognizeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RecognizeRequest'
responses:
'200':
description: Recognition result with offset
content:
application/json:
schema:
$ref: '#/components/schemas/RecognizeResponse'
/findLyrics/:
post:
operationId: findLyrics
tags:
- Lyrics
summary: Search for song lyrics
description: >-
Searches for songs and their lyrics by title and artist or by an
excerpt of the lyrics, using the `q` query parameter.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FindLyricsRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/FindLyricsRequest'
responses:
'200':
description: Lyrics search result
content:
application/json:
schema:
$ref: '#/components/schemas/FindLyricsResponse'
components:
securitySchemes:
api_token:
type: apiKey
in: query
name: api_token
description: >-
API token obtained from the AudD dashboard. May also be supplied as a
form field in the request body.
schemas:
RecognizeRequest:
type: object
properties:
api_token:
type: string
description: Your AudD API token.
url:
type: string
format: uri
description: >-
HTTP URL of an audio file or a webpage/video containing audio to be
recognized. Use instead of `file`.
file:
type: string
format: binary
description: Audio file uploaded via multipart/form-data. Use instead of `url`.
audio:
type: string
description: Base64-encoded audio (limited support). Alternative to `file`/`url`.
return:
type: string
description: >-
Comma-separated list of additional metadata providers to include,
e.g. `apple_music,spotify,deezer,napster,musicbrainz`.
example: apple_music,spotify
market:
type: string
description: >-
Two-letter country code for Apple Music / iTunes / Spotify results.
default: us
required:
- api_token
FindLyricsRequest:
type: object
properties:
api_token:
type: string
description: Your AudD API token.
q:
type: string
description: >-
Search query - a song title and artist, or an excerpt from the
lyrics.
required:
- api_token
- q
RecognizeResponse:
type: object
properties:
status:
type: string
description: '`success` or `error`.'
example: success
result:
oneOf:
- $ref: '#/components/schemas/Track'
- type: 'null'
description: The matched track, or null when nothing is recognized.
Track:
type: object
properties:
artist:
type: string
example: Imagine Dragons
title:
type: string
example: Believer
album:
type: string
example: Evolve
release_date:
type: string
format: date
example: '2017-02-01'
label:
type: string
example: Interscope Records
timecode:
type: string
description: Position of the match within the recognized song (mm:ss).
example: '00:42'
offset:
type: string
description: >-
Position of the matched fragment within the submitted audio
(recognizeWithOffset only).
song_link:
type: string
format: uri
example: https://lis.tn/Believer
isrc:
type: string
example: USUM71700626
apple_music:
type: object
additionalProperties: true
description: Apple Music metadata when requested via the `return` parameter.
spotify:
type: object
additionalProperties: true
description: Spotify metadata when requested via the `return` parameter.
FindLyricsResponse:
type: object
properties:
status:
type: string
example: success
result:
type: array
items:
type: object
properties:
song_id:
type: string
artist:
type: string
title:
type: string
lyrics:
type: string
media:
type: string
full_title:
type: string
EnterpriseRequest:
type: object
description: Request body for the enterprise file-scan endpoint (enterprise.audd.io).
properties:
api_token:
type: string
description: Your AudD API token.
url:
type: string
format: uri
description: URL of the audio/video file or webpage to scan.
file:
type: string
format: binary
description: Audio/video file uploaded via multipart/form-data.
skip:
type: integer
description: Number of 12-second chunks to skip after each scanned chunk.
every:
type: integer
description: Number of consecutive chunks to scan.
limit:
type: integer
description: Maximum number of chunks to recognize.
skip_first_seconds:
type: integer
description: Number of seconds to skip before recognition starts.
accurate_offsets:
type: string
description: Set to "true" for precise per-fragment track boundaries.
required:
- api_token
security:
- api_token: []