clicktrack-registry/README.md

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.

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. 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.