Unison

Crowdsourced lyrics API for Better Lyrics.

Authentication

All write operations require signed requests using ECDSA P-256:

{
  "payload": {
    "keyId": "<sha256-hash-of-public-key>",
    "timestamp": 1703520000000,
    "nonce": "<random-16+-char-string>",
    ...request data
  },
  "signature": "<base64-ecdsa-signature>",
  "publicKey": { "kty": "EC", "crv": "P-256", ... }
}

• keyId: SHA-256 hash of the public key (hex)
• timestamp: Must be within ±5 minutes of server time
• nonce: Unique per request (replay prevention)
• signature: ECDSA signature over the canonical JSON payload
• publicKey: Required on first request to register the key

API

Get lyrics

GET /lyrics?v=<videoId>
GET /lyrics?song=<song>&artist=<artist>
GET /lyrics?song=<song>&artist=<artist>&album=<album>&duration=<seconds>

Returns the highest-scored match. Optional album and duration narrow results. Duration matching uses ±2s tolerance (configurable in src/config.ts).

Search lyrics

Returns all matching entries sorted by score (highest first).

GET /lyrics/search?q=<query>
GET /lyrics/search?song=<song>&artist=<artist>
GET /lyrics/search?song=<song>&artist=<artist>&album=<album>
GET /lyrics/search?song=<song>&artist=<artist>&duration=<seconds>

The q parameter searches across video ID, ISRC, metadata (song/artist/album via trigram similarity), and lyrics content (full-text search). Results are ranked in three tiers: exact identifier match > metadata similarity > lyrics content match.

Get by ID

GET /lyrics/:id

Submit lyrics

Accepts TTML, LRC, or plain text via the format field.

POST /lyrics/submit
{
  "videoId": "dQw4w9WgXcQ",
  "song": "Song Title",
  "artist": "Artist Name",
  "duration": 180,
  "lyrics": "[00:15.00]First line...",
  "format": "lrc",
  "album": "Album Name",
  "language": "en",
  "syncType": "linesync"
}

Formats: ttml, lrc, plain Sync Types: richsync, linesync, plain

Vote

POST /lyrics/:id/vote
{ "vote": 1 }   // upvote
{ "vote": -1 }  // downvote

DELETE /lyrics/:id/vote  // remove vote

Report

POST /lyrics/:id/report
{
  "reason": "wrong_song",
  "details": "optional"
}

Reasons: wrong_song, bad_sync, offensive, spam, other

Response format

{
  "success": true,
  "data": {
    "id": 123,
    "videoId": "dQw4w9WgXcQ",
    "song": "Never Gonna Give You Up",
    "artist": "Rick Astley",
    "lyrics": "...",
    "format": "lrc",
    "language": "en",
    "syncType": "linesync",
    "score": 5,
    "effectiveScore": 4.2,
    "voteCount": 12,
    "confidence": "high"
  }
}

Confidence levels

• low: Fewer than 5 votes
• medium: 5+ votes from similar users
• high: 5+ votes with diversity bonus (both harsh and generous raters agree)

Development

pnpm install
pnpm run dev      # local server
pnpm run test     # tests
pnpm run check    # lint

License

MIT