Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
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