Bundles, and exchanging pieces smaller than a patch #98

New issue

Open

opened 2026-09-22 23:26:06 +00:00 by bcox · 0 comments

bcox commented

2026-09-22 23:26:06 +00:00

Owner

The preset-library spike (#97) kept producing the same answer from different
directions: the thing a person wants to load is not always one patch. Four
times over eighteen categories, the honest answer to "how is this really
played" landed outside a single .tymp. This ticket collects that question
and the related one beside it — moving pieces smaller than a patch around.

Nothing here is a decision. It is a question worth having in one place
instead of four patch lists.

Where the question came from

A convincing guitar is six monophonic channels feeding a group, one
note per string, a retrigger stealing its own string rather than the oldest
voice. Strum is a gesture and belongs to the part, but the six channels and
their routing are a structure someone has to build and would rather load.
(Eventually some of this may be expressible with future patch features
instead; that does not remove the case.)
A drum kit is not a patch. Under one primary category per patch, each
drum is its own patch — which is right, because a bundle can gather patches
and a kit-shaped patch cannot be taken apart. But nobody thinks in single
drums; people load a kit.
An effect on a return is a channel with routing, not just a patch.
Birdsong is a phrase, and phrases are parts. A library that ships demo
patches might reasonably ship demo parts too — which is a content
question rather than a format one, but it lands in the same place: the unit
someone loads.

What a bundle would have to carry

A first sketch, to be argued with:

a named set of channels, each with its patch, its strip and its routes;
the group or bus they feed, and any sends;
optionally the MIDI assignment shape (which channels a controller reaches,
and how notes are distributed across them);
provenance for each embedded patch, as a channel already carries
(project::Provenance, name plus FNV-1a hash of the PTCH bytes).

Open questions:

Does a bundle get a primary category from #97's list, or is it a
different kind of object that browses separately? A "kit" is not a patch
and a category list built for patches may not fit it.
Does loading one replace channels, or claim the next free ones?
How does it interact with undo and with the project's own channel
state?
Is a project file already most of this? A project holds sixty-four channels
with their patches and routes; a bundle may be a slice of a project
rather than a new format — which would be the cheapest possible answer and
is worth disproving before designing anything.

The other half: exchanging pieces smaller than a patch

We also want to import and export the parts a patch is built from —
spectra, materials, layers, and the chiff and atmosphere assets beside
them.

Much of this exists already. format/ defines standalone layer, table,
material, atmosphere and chiff files, and format/exchange.h moves a layer
or an asset between patches. What is not yet answered is the part a person
touches:

how a user exports a material or a spectral table out of a patch they
are editing, and imports one into another;
whether those files live in a browsable library alongside patches, with
their own names, tags and provenance, or stay loose files on disk;
whether an imported asset is copied into the patch (today's posture —
a patch carries its own assets) or referenced, and if referenced, what
happens when the referent changes or goes missing;
whether a shared asset needs a hash the way a channel's patch does, so a
patch can say which version of a material it was built against.

The copy-versus-reference question is the substantive one, and it is the same
shape as the provenance question a channel's embedded patch already answers.
Whatever is decided should match that answer rather than invent a second
model.

Why this is not urgent

Every category list on #97 ships without any of it. The guitar, the kit and
the effect return are all buildable by hand today; a bundle only saves the
building. This is a convenience and a library-management question, not a
blocker — but it has now come up four times, and the next person to hit it
should find this ticket rather than re-derive it.

Related: #97.

The preset-library spike (#97) kept producing the same answer from different directions: *the thing a person wants to load is not always one patch*. Four times over eighteen categories, the honest answer to "how is this really played" landed outside a single `.tymp`. This ticket collects that question and the related one beside it — moving pieces *smaller* than a patch around. Nothing here is a decision. It is a question worth having in one place instead of four patch lists. ## Where the question came from - **A convincing guitar is six monophonic channels feeding a group**, one note per string, a retrigger stealing its own string rather than the oldest voice. Strum is a gesture and belongs to the part, but the six channels and their routing are a structure someone has to build and would rather load. (Eventually some of this may be expressible with future patch features instead; that does not remove the case.) - **A drum kit is not a patch.** Under one primary category per patch, each drum is its own patch — which is right, because a bundle can gather patches and a kit-shaped patch cannot be taken apart. But nobody thinks in single drums; people load a kit. - **An effect on a return** is a channel with routing, not just a patch. - **Birdsong is a phrase**, and phrases are parts. A library that ships demo patches might reasonably ship demo *parts* too — which is a content question rather than a format one, but it lands in the same place: the unit someone loads. ## What a bundle would have to carry A first sketch, to be argued with: - a named set of channels, each with its patch, its strip and its routes; - the group or bus they feed, and any sends; - optionally the MIDI assignment shape (which channels a controller reaches, and how notes are distributed across them); - provenance for each embedded patch, as a channel already carries (`project::Provenance`, name plus FNV-1a hash of the PTCH bytes). Open questions: - Does a bundle get a **primary category** from #97's list, or is it a different kind of object that browses separately? A "kit" is not a patch and a category list built for patches may not fit it. - Does loading one **replace** channels, or claim the next free ones? - How does it interact with **undo** and with the project's own channel state? - Is a project file already most of this? A project holds sixty-four channels with their patches and routes; a bundle may be a *slice* of a project rather than a new format — which would be the cheapest possible answer and is worth disproving before designing anything. ## The other half: exchanging pieces smaller than a patch We also want to import and export the parts a patch is built from — **spectra, materials, layers**, and the chiff and atmosphere assets beside them. Much of this exists already. `format/` defines standalone layer, table, material, atmosphere and chiff files, and `format/exchange.h` moves a layer or an asset between patches. What is not yet answered is the part a person touches: - how a user **exports** a material or a spectral table out of a patch they are editing, and **imports** one into another; - whether those files live in a browsable library alongside patches, with their own names, tags and provenance, or stay loose files on disk; - whether an imported asset is **copied** into the patch (today's posture — a patch carries its own assets) or **referenced**, and if referenced, what happens when the referent changes or goes missing; - whether a shared asset needs a hash the way a channel's patch does, so a patch can say which version of a material it was built against. The copy-versus-reference question is the substantive one, and it is the same shape as the provenance question a channel's embedded patch already answers. Whatever is decided should match that answer rather than invent a second model. ## Why this is not urgent Every category list on #97 ships without any of it. The guitar, the kit and the effect return are all buildable by hand today; a bundle only saves the building. This is a convenience and a library-management question, not a blocker — but it has now come up four times, and the next person to hit it should find this ticket rather than re-derive it. Related: #97.