60 lines
2.6 KiB
Markdown
60 lines
2.6 KiB
Markdown
# 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.
|