This repository contains the canonical specification documents for BTM (Beat-Tracking Media), a family of backward-compatible file format extensions that enable musical structure of an animation or video — allowing a player to retempo the content in real time to match accompanying music.
For project context, motivation, and the broader format family overview, see the btm-format organization page.
The current specification is v0.2, consisting of the schema plus three container profiles:
The shared metadata schema. Container-independent. Defines the binary layout of the BTM1Sync block and the playback semantics that all conforming implementations must follow. The profile documents below reference this document normatively.
The GIF profile (Beat-Tracking Media — Animation). Specifies how the BTM1Sync block is embedded in a GIF89a Application Extension, the GIF-fallback frame delay computation, and the GIF-to-BTMA conversion workflow. File extension: .btma (or .gif — extensions are interchangeable).
The WebP profile (Beat-Tracking Media — WebP). Specifies the BTMS RIFF chunk layout for animated WebP files, the WebP-fallback frame duration computation, and the WebP-to-BTMW conversion workflow. File extension: .btmw (or .webp — extensions are interchangeable).
The MP4 profile (Beat-Tracking Media — Video). Specifies the BTM1Sync UUID box layout, presentation-order frame indexing, codec recommendations, and the MP4-to-BTMV conversion workflow. File extension: .btmv (or .mp4 — extensions are interchangeable).
An AVIF profile is planned but not yet specified; AVIF's ISO BMFF container reuses BTMV's UUID box mechanism, so the eventual document will be a small amendment rather than a full new profile.
v0.2 is binary-incompatible with v0.1. It adds a beats_per_beatmarker field (sub-beat and reverse-playback loops) and switches beatmarker indices to 16.16 fixed-point (sub-frame anti-jitter). v0.1-aware decoders will fall back to native container timing on v0.2 files; v0.2-aware decoders SHOULD also support v0.1 payloads for backward compatibility with older files. See each v0.2 document's "Changes from v0.1" section for details.
The v0.1 documents remain available for historical reference: BTM1Sync-schema-v0.1.md, BTMA-spec-v0.1.md, BTMV-spec-v0.1.md.
If you're implementing BTM, read the schema document first, then whichever container profile is relevant to your use case. The schema document is short and self-contained; the profile documents reference it for shared semantics and add only container-specific details.
If you're evaluating BTM for adoption, the abstracts and motivation sections at the top of each document give the full picture in a few paragraphs.
v0.2 — Draft. Stable enough to implement against. The v0.x → v1.0 transition will occur once at least one working implementation has been built and tested end-to-end. Further breaking changes between v0.2 and v1.0 are possible but unlikely.
Spec ambiguity, edge cases, or implementation pain points are the most valuable feedback at this stage. Open an issue describing the case and what behavior would be most useful.
Use-case feedback from DJs, VJs, livestreamers, emote artists, and platform engineers is also welcome — particularly on whether the conversion workflows match how you'd actually want to work with these files.
This specification is released under Creative Commons Attribution 4.0 International License (CC-BY-4.0). It is dedicated to the public domain; you can use it, implement it, redistribute it, modify it, or fork it for any purpose, with or without attribution.