From c97b452f727ca4da7d07d0a12b4669f55939ff44 Mon Sep 17 00:00:00 2001 From: AJ Avezzano Date: Fri, 3 Apr 2026 13:35:13 -0400 Subject: [PATCH] Initial registry scaffold with example CTP files --- .gitignore | 4 ++ README.md | 59 +++++++++++++++++++ ...00000-0000-0000-0000-000000000001.ctp.json | 47 +++++++++++++++ ...00000-0000-0000-0000-000000000002.ctp.json | 48 +++++++++++++++ 4 files changed, 158 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 a/example-artist/00000000-0000-0000-0000-000000000001.ctp.json create mode 100644 j/journey/00000000-0000-0000-0000-000000000002.ctp.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..52c8137 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.DS_Store +*.swp +*~ +Thumbs.db diff --git a/README.md b/README.md new file mode 100644 index 0000000..c259d38 --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ +# ClickTrack Registry + +A community collection of CTP 1.0 tempo map files for use with ClickTrack. + +## What is this? + +This repository contains crowd-sourced tempo maps in the CTP (Click Track Protocol) 1.0 format. ClickTrack syncs these files on a configurable interval and imports them into its database, making them available to all users of your instance. + +Files must be valid CTP 1.0 JSON. ClickTrack validates each file on sync and skips any that fail validation, logging the errors. + +## File Format + +Each file is a `.ctp.json` document describing the tempo map for a single recording. See the example files in this repo for the full structure. Required top-level fields: `version`, `metadata`, `count_in`, `sections`. + +For full schema documentation, refer to the [ClickTrack project](https://github.com/your-org/clicktrack). + +## Folder Structure + +Files are organized by artist to keep the repo navigable: + +``` +//.ctp.json +``` + +The artist slug is the artist name lowercased, spaces replaced with hyphens, non-alphanumeric characters removed: + +| Artist | Slug | Path prefix | +|------------|----------------|-----------------| +| Journey | `journey` | `j/journey/` | +| Don Henley | `don-henley` | `d/don-henley/` | +| AC/DC | `acdc` | `a/acdc/` | +| The Beatles| `the-beatles` | `t/the-beatles/`| + +The filename is the MusicBrainz Recording UUID with the `.ctp.json` extension. + +## Contributing a Tempo Map + +1. **Find the MusicBrainz Recording ID** for the song at [musicbrainz.org](https://musicbrainz.org). It's the UUID in the recording URL — make sure it's a *Recording* ID, not an album or artist ID. + +2. **Create the folder path** from the artist name using the slug convention above. + +3. **Name the file** `.ctp.json`. + +4. **Fill in all required fields.** Use the example files as a reference: + - `metadata.mbid` must be the real MusicBrainz Recording UUID + - `metadata.verified` should be `false` unless you have listened to the song and confirmed the tempo map is accurate + - `metadata.contributed_by` should be your name or handle + +5. **Open a merge/pull request.** + +## Notes + +### MusicBrainz ID + +`mbid` must be a real MusicBrainz Recording UUID. ClickTrack skips any file where `mbid` is null or missing — it is required for the file to be imported. + +### Verified Flag + +`verified: true` means a human has listened to the recording and confirmed the tempo map is accurate. Verified maps are ranked higher in ClickTrack search results. Leave it `false` for AI-generated or unconfirmed maps. diff --git a/a/example-artist/00000000-0000-0000-0000-000000000001.ctp.json b/a/example-artist/00000000-0000-0000-0000-000000000001.ctp.json new file mode 100644 index 0000000..3d11295 --- /dev/null +++ b/a/example-artist/00000000-0000-0000-0000-000000000001.ctp.json @@ -0,0 +1,47 @@ +{ + "version": "1.0", + "metadata": { + "title": "Example Song", + "artist": "Example Artist", + "mbid": "00000000-0000-0000-0000-000000000001", + "duration_seconds": 214, + "contributed_by": "your-name", + "verified": false, + "created_at": "2026-01-01T00:00:00.000Z" + }, + "count_in": { + "enabled": true, + "bars": 2, + "use_first_section_tempo": true + }, + "sections": [ + { + "label": "Intro", + "start_bar": 1, + "bpm": 120, + "time_signature": { "numerator": 4, "denominator": 4 }, + "transition": "step" + }, + { + "label": "Verse", + "start_bar": 5, + "bpm": 120, + "time_signature": { "numerator": 4, "denominator": 4 }, + "transition": "step" + }, + { + "label": "Chorus", + "start_bar": 13, + "bpm": 120, + "time_signature": { "numerator": 4, "denominator": 4 }, + "transition": "step" + }, + { + "label": "Outro", + "start_bar": 57, + "bpm": 120, + "time_signature": { "numerator": 4, "denominator": 4 }, + "transition": "step" + } + ] +} diff --git a/j/journey/00000000-0000-0000-0000-000000000002.ctp.json b/j/journey/00000000-0000-0000-0000-000000000002.ctp.json new file mode 100644 index 0000000..da7a615 --- /dev/null +++ b/j/journey/00000000-0000-0000-0000-000000000002.ctp.json @@ -0,0 +1,48 @@ +{ + "version": "1.0", + "metadata": { + "title": "Don't Stop Believin'", + "artist": "Journey", + "mbid": "00000000-0000-0000-0000-000000000002", + "duration_seconds": 251, + "contributed_by": "your-name", + "verified": false, + "created_at": "2026-01-01T00:00:00.000Z" + }, + "count_in": { + "enabled": true, + "bars": 2, + "use_first_section_tempo": true + }, + "sections": [ + { + "label": "Intro", + "start_bar": 1, + "bpm": 118, + "time_signature": { "numerator": 4, "denominator": 4 }, + "transition": "step" + }, + { + "label": "Verse 1", + "start_bar": 5, + "bpm": 118, + "time_signature": { "numerator": 4, "denominator": 4 }, + "transition": "step" + }, + { + "label": "Chorus", + "start_bar": 21, + "bpm": 118, + "time_signature": { "numerator": 4, "denominator": 4 }, + "transition": "step" + }, + { + "label": "Outro", + "start_bar": 57, + "bpm_start": 118, + "bpm_end": 108, + "time_signature": { "numerator": 4, "denominator": 4 }, + "transition": "ramp" + } + ] +}