AudD Lyrics API
Searches for song lyrics by title, artist, or an excerpt of the lyrics via the findLyrics method, returning matching songs with full lyrics and metadata.
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: []