Carriers

Carriers — non-standard [I:croma-*] / %%croma-* notations

croma round-trips MusicXML through ABC: MusicXML → ABC → MusicXML. ABC 2.1 cannot natively express every MusicXML fact (per-note instrument switches, functional <harmony> text, <forward>/<backup> cursor moves, wide tuplets, cross-voice slurs, …). Rather than drop those facts, croma stores them in namespaced carriers that travel inside the ABC text and are re-applied on the way back to MusicXML.

A carrier is not a comment a human reads — it is a structured, machine-owned annotation in croma's croma- namespace. Every other ABC tool ignores it (ABC 2.1 §3.1.2 lets a reader skip unrecognised I: instructions; §11 lets it skip unrecognised %% directives), so the ABC stays playable in abc2midi / abcm2ps / abcjs while croma keeps full fidelity.

The two vehicles

Vehicle	Form	Anchored to	Use for
inline instruction	[I:croma-<name> k=v …]	the following note / chord / barline	per-note and per-measure facts
header directive	%%croma-<name> …	a voice or the score	score/voice-level facts (e.g. the instrument list)

Fields are key=value, space-separated; a value with spaces is double-quoted. A boolean carrier carries no fields — the bare name is the flag. When a free-text value contains a character that breaks the ABC tokenizer (], %, control chars), croma emits a hex variant of the field instead (text="John" → text-hex=4a6f686e).

Discovering carriers from the CLI

croma agent is the agent-facing index of every carrier — what MusicXML fact it persists, the syntax, and a copy-paste example:

croma agent                 # list all carrier topics
croma agent xvoice-slur     # one notation in detail
croma agent syntax          # the convention itself

The same data is available to library users via croma_core::agent_topics().

Reference

• The full catalogue, the round-trip contract, and the add-a-carrier checklist: docs/carriers.md.
• The agent help surface: docs/agent.md and CLI-Usage#croma-agent--help-topics-for-ai-agents.
• How the round-trip is proven lossless at corpus scale: How-its-Proven, MusicXML-Reader.