LRCMux Lyrics API

openapi: 3.2.0
info:
  description: '**lrcmux** is a lyrics aggregation API. It queries multiple providers, caches results, and returns the best available lyrics for a given track.


    ## Providers


    | Provider | ID | Notes |

    | -------- | -- | ----- |

    | **Genius** | `genius` | Best song coverage, but only plain text lyrics |

    | **KuGou** | `kugou` | Word-level sync for most songs (AI?), censors profanity |

    | **LRCLIB** | `lrclib` | Community-sourced lyrics database |

    | **YouTube Music** | `ytmusic` | Uses various sources, mix of line-synced and plain text |


    ## Sync levels


    | Level | Description |

    | ----- | ----------- |

    | `word` | Per-word timestamps, suitable for karaoke-style highlighting |

    | `line` | Per-line timestamps, suitable for scrolling displays |

    | `none` | Unsynced plain text |


    ## Formats


    The same result can be returned in any of these formats via the `format` query parameter. If the underlying lyrics do not meet a format''s minimum sync level, the request fails with a `400`.


    | Format | Content-Type | Min level | Notes |

    | ------ | ------------ | --------- | -------- |

    | `json` | `application/json; charset=utf-8` | none | Default, structured lines and metadata |

    | `lrc` | `text/plain; charset=utf-8` | none | Standard .lrc files for music players |

    | `lyricsfile` | `text/yaml; charset=utf-8` | none | Used by LRCLIB/LRCGET |

    | `srt` | `text/plain; charset=utf-8` | line | Subtitles for video editors and media players |

    | `txt` | `text/plain; charset=utf-8` | none | Plain unsynced text |

    | `vtt` | `text/vtt; charset=utf-8` | line | WebVTT for browser-based players |


    ## User agent


    While it''s not mandatory, we encourage you to include a `User-Agent` header identifying your app and a link to its repo (or a way to contact you if something goes wrong).


    ```

    User-Agent: MyApp v1.0.0 (https://github.com/example/myapp)

    ```


    ## Rate limiting


    Up to **60** requests per **1m** window. Cache hits are free and do not count against the limit.


    You should respect the `Retry-After` header on 429 responses.'
  title: lrcmux Lyrics API
  version: v1.7.0
tags:
- name: Lyrics
paths:
  /get:
    get:
      description: Searches various providers and returns the best available result.
      operationId: get-lyrics
      parameters:
      - description: Artist name
        explode: false
        in: query
        name: artist
        schema:
          description: Artist name
          examples:
          - Rick Astley
          type: string
      - description: Song title
        explode: false
        in: query
        name: title
        schema:
          description: Song title
          examples:
          - Never Gonna Give You Up
          type: string
      - description: Album name
        explode: false
        in: query
        name: album
        schema:
          description: Album name
          type: string
      - description: ISRC of the track, has priority over artist and title
        explode: false
        in: query
        name: isrc
        schema:
          description: ISRC of the track, has priority over artist and title
          type: string
      - description: Highest sync level to accept, or exact level if strict is set
        explode: false
        in: query
        name: level
        schema:
          default: word
          description: Highest sync level to accept, or exact level if strict is set
          enum:
          - word
          - line
          - none
          type: string
      - description: Response format
        explode: false
        in: query
        name: format
        schema:
          default: json
          description: Response format
          enum:
          - lrc
          - txt
          - json
          - srt
          - vtt
          - lyricsfile
          type: string
      - description: Cache strategy
        explode: false
        in: query
        name: fetch
        schema:
          default: default
          description: Cache strategy
          enum:
          - default
          - cache
          - force
          type: string
      - description: Comma-separated providers to restrict the fanout to, prefix with '!' to exclude
        explode: false
        in: query
        name: sources
        schema:
          description: Comma-separated providers to restrict the fanout to, prefix with '!' to exclude
          type: string
      - description: Track duration in seconds
        explode: false
        in: query
        name: duration
        schema:
          description: Track duration in seconds
          format: int64
          type: integer
      - description: Fail instead of falling back to a lower sync level
        explode: false
        in: query
        name: strict
        schema:
          description: Fail instead of falling back to a lower sync level
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JSONResponse'
            text/plain:
              schema:
                description: Lyrics in the requested format
                type: string
          description: Lyrics in the requested format
          headers:
            X-Cache:
              description: '`HIT` if served from cache, `MISS` if freshly fetched from a provider'
              schema:
                type: string
            X-Source:
              description: Provider that supplied the lyrics
              schema:
                type: string
            X-Sync-Level:
              description: Actual sync level of the returned lyrics, may be lower than requested when `strict=false`
              schema:
                type: string
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: Get lyrics for a song
      tags:
      - Lyrics
components:
  schemas:
    ErrorModel:
      additionalProperties: false
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
          - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
          - array
          - 'null'
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
          - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
          - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
          - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
          - https://example.com/errors/example
          format: uri
          type: string
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    Track:
      additionalProperties: false
      properties:
        album:
          type: string
        artist:
          type: string
        cover:
          $ref: '#/components/schemas/TrackCover'
        duration:
          format: int64
          type: integer
        isrc:
          type: string
        title:
          type: string
      required:
      - cover
      - isrc
      - title
      - artist
      - album
      - duration
      type: object
    JSONLine:
      additionalProperties: false
      properties:
        end:
          description: in milliseconds
          format: int64
          type: integer
        start:
          description: in milliseconds
          format: int64
          type: integer
        text:
          type: string
        words:
          items:
            $ref: '#/components/schemas/Word'
          type:
          - array
          - 'null'
      required:
      - text
      type: object
    JSONResponse:
      additionalProperties: false
      properties:
        lines:
          items:
            $ref: '#/components/schemas/JSONLine'
          type:
          - array
          - 'null'
        meta:
          $ref: '#/components/schemas/JSONMeta'
        track:
          $ref: '#/components/schemas/Track'
      required:
      - track
      - meta
      - lines
      type: object
    JSONMeta:
      additionalProperties: false
      properties:
        instrumental:
          description: Whether the track has no lyrics
          type: boolean
        level:
          description: Sync level of the returned lyrics
          enum:
          - word
          - line
          - none
          type: string
        source:
          $ref: '#/components/schemas/Source'
          description: Provider that returned the result
      required:
      - level
      type: object
    Source:
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
      required:
      - id
      - name
      type: object
    Word:
      additionalProperties: false
      properties:
        end:
          description: in milliseconds
          format: int64
          type: integer
        start:
          description: in milliseconds
          format: int64
          type: integer
        text:
          type: string
      required:
      - text
      - start
      - end
      type: object
    TrackCover:
      additionalProperties: false
      properties:
        big:
          type: string
        medium:
          type: string
        small:
          type: string
      type: object