Initial registry scaffold with example CTP files
This commit is contained in:
AJ Avezzano
4
.gitignore
vendored
Normal file
4
.gitignore
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
.DS_Store
|
||||
*.swp
|
||||
*~
|
||||
Thumbs.db
|
||||
59
README.md
Normal file
59
README.md
Normal file
@@ -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:
|
||||
|
||||
```
|
||||
<first-letter-of-artist-slug>/<artist-slug>/<mbid>.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** `<mbid>.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.
|
||||
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
48
j/journey/00000000-0000-0000-0000-000000000002.ctp.json
Normal file
48
j/journey/00000000-0000-0000-0000-000000000002.ctp.json
Normal file
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user