The link is the document

A link that is the document

Most music tools treat a link as a pointer: the bytes live in a database row or an object store, and the URL is a lookup key. Soundfish compositions work the other way. An editable loop serializes to a canonical document that travels inside the URL fragment, and a song is a self-contained document that embeds every loop it is made of. Copy the link, paste it anywhere, and the whole composition arrives with it.

The fragment matters technically, not just aesthetically. Browsers do not send the part after # to a server, so a composition link is readable by the page that opens it without any request, any account, or any retained server state. There is nothing to expire, no record to delete, and no service that has to stay up for the music to keep opening.

Two envelope versions

An editable loop uses the soundfish.document/v1 protocol and serializes into a #s1.… envelope covering one to sixteen bars of notes tracks and drums tracks, tempo, authored mix, shared effects, and automation. Notes and drums are structurally distinct track types, and automation uses integer ranges with explicit hold-or-linear curves.

A song uses the soundfish.arrangement/v1 protocol in a #a1.… fragment. It embeds a bounded roster of verified child loops and keeps an ordered section strip with repeats and part variations. Opening a song re-derives every child MusicCID and admits a deeply frozen, verified document before local playback — the song never resolves sections remotely, and the embedded children cannot mutate under it.

What MusicCID addresses

MusicCID is the content address of authored musical meaning: tempo, bars, typed tracks, events, track production, shared reverb and delay, and every automation point. It deliberately excludes titles, IDs, lineage, display order, and the runtime sound assets, so the same music keeps the same address however it is named or wherever it plays.

A second digest covers the entire canonical document — titles and identities included — for transport integrity. Keeping the two separate means a composition can be renamed, reordered, or handed through an agent while its musical identity stays provably intact.

Why this is worth the constraints

A document-in-the-link design pays for itself in three places:

Portability is the visible one. A loop link works in a chat, an issue, a markdown file, or an agent transcript, and it will still open the same way in a year. Interoperability follows: the same document drives the browser editor and the published CLI, so a person and a machine can review identical bytes. And server cost collapses — the read path for a composition is static page rendering, not a database lookup.

The trade-off is real: canonical bytes in a URL bound the document's size, which is why loops stay small and why songs embed bounded rosters rather than arbitrary graphs. The limit is the feature — a composition that fits in a link is a composition that can go anywhere a link can.

• No account or request is needed to open, play, or fork a composition link.
• The same canonical bytes drive the browser editor, the soundfish CLI, and agent workflows.
• Detached sections and arranged songs produce new documents; embedded sources never mutate.

Where files still exist

Links are not the only form. The More menu exports a loop or a whole song as lossless Soundfish JSON or as a Standard MIDI projection; JSON round-trips everything, and MIDI keeps tempo, tracks, instruments, notes, velocities, and section markers while the URL remains authoritative for effects, automation, and identity. Files are views of the document, not the document itself.

The short version

The constraint a URL document accepts — bounded size, canonical encoding, verified admission — is what lets a composition travel through any medium that carries text, unchanged, forever.

More research notes