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: []