LRCMux Meta 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 Meta API
  version: v1.7.0
tags:
- name: Meta
paths:
  /stats:
    get:
      operationId: get-stats
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsOutputBody'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: Server statistics
      tags:
      - Meta
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
    ProviderInfo:
      additionalProperties: false
      properties:
        health:
          $ref: '#/components/schemas/ProviderHealth'
        id:
          type: string
        name:
          type: string
        url:
          type: string
      required:
      - health
      - id
      - name
      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
    ProviderHealth:
      additionalProperties: false
      properties:
        ok:
          type: boolean
        reason:
          type: string
        ttl:
          format: int64
          type: integer
      required:
      - ok
      type: object
    StatsOutputBody:
      additionalProperties: false
      properties:
        commit:
          type: string
        providers:
          items:
            $ref: '#/components/schemas/ProviderInfo'
          type:
          - array
          - 'null'
        version:
          type: string
      required:
      - version
      - commit
      type: object