LRCMux Compatibility 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 Compatibility API
  version: v1.7.0
tags:
- name: Compatibility
paths:
  /compat/kpoe/v2/lyrics/get:
    get:
      operationId: kpoe-get-lyrics
      parameters:
      - description: Artist name
        explode: false
        in: query
        name: artist
        schema:
          description: Artist name
          type: string
      - description: Song title
        explode: false
        in: query
        name: title
        schema:
          description: Song title
          type: string
      - description: Album name
        explode: false
        in: query
        name: album
        schema:
          description: Album name
          type: string
      - description: ISRC of the track
        explode: false
        in: query
        name: isrc
        schema:
          description: ISRC of the track
          type: string
      - description: Track duration in seconds
        explode: false
        in: query
        name: duration
        schema:
          description: Track duration in seconds
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KpoeResponse'
          description: OK
          headers:
            Cache-Control:
              schema:
                type: string
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: LyricsPlus/KPOE
      tags:
      - Compatibility
  /compat/lrclib/api/get:
    get:
      operationId: lrclib-get-lyrics
      parameters:
      - description: Track name
        explode: false
        in: query
        name: track_name
        schema:
          description: Track name
          type: string
      - description: Artist name
        explode: false
        in: query
        name: artist_name
        schema:
          description: Artist name
          type: string
      - description: Album name
        explode: false
        in: query
        name: album_name
        schema:
          description: Album name
          type: string
      - description: ISRC of the track
        explode: false
        in: query
        name: isrc
        schema:
          description: ISRC of the track
          type: string
      - description: Track duration in seconds
        explode: false
        in: query
        name: duration
        schema:
          description: Track duration in seconds
          format: double
          type: number
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LrclibResponse'
          description: OK
          headers:
            Cache-Control:
              schema:
                type: string
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: LRCLIB
      tags:
      - Compatibility
  /compat/lrclib/api/search:
    get:
      operationId: lrclib-search-lyrics
      parameters:
      - description: Track name
        explode: false
        in: query
        name: track_name
        schema:
          description: Track name
          type: string
      - description: Artist name
        explode: false
        in: query
        name: artist_name
        schema:
          description: Artist name
          type: string
      - description: Album name
        explode: false
        in: query
        name: album_name
        schema:
          description: Album name
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/LrclibResponse'
                type:
                - array
                - 'null'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: LRCLIB
      tags:
      - Compatibility
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
    KpoeElement:
      additionalProperties: false
      properties:
        key:
          type: string
      required:
      - key
      type: object
    KpoeMetadata:
      additionalProperties: false
      properties:
        source:
          type: string
      required:
      - source
      type: object
    LrclibResponse:
      additionalProperties: false
      properties:
        albumName:
          type: string
        artistName:
          type: string
        duration:
          format: double
          type: number
        id:
          format: int64
          type: integer
        instrumental:
          type: boolean
        lyricsfile:
          type: string
        plainLyrics:
          type:
          - string
          - 'null'
        syncedLyrics:
          type:
          - string
          - 'null'
        trackName:
          type: string
      required:
      - syncedLyrics
      - plainLyrics
      - trackName
      - artistName
      - albumName
      - lyricsfile
      - id
      - duration
      - instrumental
      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
    KpoeResponse:
      additionalProperties: false
      properties:
        KpoeTools:
          type: string
        cached:
          type: string
        lyrics:
          items:
            $ref: '#/components/schemas/KpoeLine'
          type:
          - array
          - 'null'
        metadata:
          $ref: '#/components/schemas/KpoeMetadata'
        type:
          type: string
      required:
      - KpoeTools
      - type
      - metadata
      - cached
      - lyrics
      type: object
    KpoeSyllabus:
      additionalProperties: false
      properties:
        duration:
          format: int64
          type: integer
        text:
          type: string
        time:
          format: int64
          type: integer
      required:
      - text
      - time
      - duration
      type: object
    KpoeLine:
      additionalProperties: false
      properties:
        duration:
          format: int64
          type: integer
        element:
          $ref: '#/components/schemas/KpoeElement'
        syllabus:
          items:
            $ref: '#/components/schemas/KpoeSyllabus'
          type:
          - array
          - 'null'
        text:
          type: string
        time:
          format: int64
          type: integer
      required:
      - text
      - element
      - syllabus
      type: object