xlrcdb

Official community lyrics database for the XLRC format

xlrcdb stores XLRC lyric files and generated lookup indexes as plain files in this repository. The repository is designed to be served as static files and checked by CI.

Repository Layout

• artists/ contains canonical artist records as TOML.
• tracks/ contains canonical XLRC files.
• incoming/ is the temporary holding area for raw submitted .xlrc files.
• index/ is generated from artists/ and tracks/.
• scripts/ contains the local maintenance CLIs.

Local Checks

Install dependencies once:

npm install

Run the same check used by CI:

npm run check

This runs tests, validates source data, validates any pending incoming/ submissions, regenerates index/, and fails if the generated index differs from what is committed.

Static Data Source

xlrcdb is intended to be served directly from GitHub Pages.

The default project-site URL is:

https://boof2015.github.io/xlrcdb/

Clients using @boof2015/xlrc should pass that URL as the lookup source:

await lookup({
  artist: "Artist Name",
  title: "Track Title",
  length: 222,
  source: "https://boof2015.github.io/xlrcdb/"
});

Adding Lyrics Locally

For contributor-facing instructions, see CONTRIBUTING.md.

For the current v0 workflow, add raw contribution files under incoming/:

incoming/my-track.xlrc

Each incoming XLRC file must include:

[ar:Artist Name]
[ti:Track Title]
[length:mm:ss]

Then normalize the repository:

npm run normalize

Normalization promotes incoming files into canonical sharded paths under artists/ and tracks/, creates artist records when needed, removes processed incoming files, and regenerates index/.

After normalizing, run:

npm run check

To validate incoming files without moving or rewriting anything, run:

npm run validate:incoming

Maintainer Workflow

The Check GitHub Actions workflow runs automatically on pull requests and pushes to main.

On pull requests, Check also verifies that PRs are data submissions. A normal submission PR may only change xlrcdb data paths: incoming/, artists/, tracks/, and index/. Backend, workflow, package, and documentation changes intentionally fail this check so they require explicit maintainer review.

The PR check is deliberately gated:

1. Classify the PR as a data submission, normalized data, manual review, or invalid mixed change.
2. Validate raw incoming/*.xlrc files for data submissions.
3. Run normalization in a temporary dry-run copy for data submissions.
4. Run the full repository check.

The check workflow reports and fails. A follow-up comment workflow updates a single bot comment with the gate report when a PR check fails. It does not close or merge pull requests.

After a raw same-repository incoming/*.xlrc PR passes Check, the Normalize Incoming workflow runs automatically. It refuses the base branch, requires a raw incoming data submission, validates the incoming files, runs a dry-run normalization, commits generated changes back to that branch, runs the full check on the normalized commit, and publishes a commit status for the PR. It does not merge pull requests.

Maintainers can also run Normalize Incoming manually with a target branch name when a branch needs to be reprocessed.