xtc/docs/COMPOSITION_WORKFLOWS.md

# Arrangement and Composition Workflows

All mutations run on the control thread through the existing stop, history and
prepared-plan workflow. No new dependencies are required.

---

## Persistent Arrangement Markers

Edit/Markers/Set at cursor adds or renames a marker; Remove at cursor removes
the exact tick key. Markers draw names and vertical guides in the arrangement
and survive project save/load and undo. Up to 128 markers are supported. Names
may overlap visually when markers are close; markers do not change playback by
themselves.

---

## Section Navigation and Looping

View/Previous marker and Next marker navigate without wrapping and stop playback
before seeking. Loop current section uses the last marker at or before the
cursor through its successor; the final section ends at the final clip endpoint.
Empty final sections reject. Loop ranges remain existing UI preferences rather
than marker metadata.

---

## Ripple Time Editing

Edit/Time inserts a gap or removes a tick range beginning at the cursor. Clips
crossing either edit boundary reject the entire operation; split them first.
Contained clips and their notes are removed; later clips, markers and absolute
automation points shift together. Source notes within retained clips do not
move. No interpolation guard points are generated, so automation ramps across
the boundary may change slope. Loop preferences are unchanged.

---

## Complete Track Duplication

Edit/Duplicate complete track copies the selected non-bus track adjacent to its
source. Clips, notes, instrument settings, static mix, bus routing and mixer
automation are independent model copies with fresh IDs; WAV references remain
shared. The modular graph and live-input target are unchanged. Bus duplication
is rejected. Capacity errors leave the original document unchanged.

---

## Nondestructive MIDI Clip Splitting

The existing Split clip at cursor command (S) now handles MIDI as well as audio.
Left retains its ID; right gets fresh IDs, the same source content and an
adjusted source offset. Hidden notes remain editable. Split is nondestructive,
but instrument note envelopes may retrigger at the new boundary; original sine
rendering retains source phase. Capacity failures preserve the project.

---

## MIDI Clip Consolidation

Edit/Consolidate MIDI clips merges two or more selected MIDI clips on one track.
The new clip spans their full bounding range; gaps and overlapping notes remain.
Notes outside visible trims are discarded and crossing notes are cropped to
audible boundaries. IDs are fresh. Cropped notes start anew, so envelope/phase
behavior can change. Audio or cross-track selections reject atomically.

---

## Deterministic MIDI Humanization

Edit/MIDI tools/Humanize applies timing variation up to 960 ticks and velocity
variation up to 127, using a 32-bit seed and stable note IDs. Repeating from the
same original state reproduces results; applying repeatedly accumulates edits.
All source notes are affected, including hidden trimmed notes. Timing outside
source bounds rejects the entire edit; velocities clamp to 1..127. This is
offline editing, not live randomness.

---

## Chord Construction

Edit/MIDI tools/Build chords accepts 1..8 unique nonzero semitone intervals,
such as 4 7 for a major triad or 3 7 for minor. Originals remain; added notes
copy timing, velocity and channel. Negative intervals support lower voicings.
All source notes are processed, including hidden trimmed notes. Pitch overflow
or capacity rejects the whole operation; existing unisons are not deduplicated.

---

## Offline Arpeggio Generation

Edit/MIDI tools/Generate arpeggio replaces source notes with a written pattern.
Equal-onset notes on the same channel form a chord lasting until its longest
note end. The pattern cycles sorted pitches upward or downward, with the
selected step and gate. Each step inherits its chosen note velocity/channel. All
source notes, including hidden trimmed notes, participate. This is offline
generation with undo, not a live arpeggiator or tempo-synced MIDI effect.

---

## Audio Peak Normalization

Edit/Audio tools/Normalize source peak accepts a target from -60 to 0 dBFS. The
C API accepts a linear target above 0 and at most 1. Analysis uses the audible
native-rate source slice and the same mono downmix as playback, before fades or
mixer controls. It replaces clip gain without writing WAV data. Silence,
missing/invalid media, MIDI selections or required gain above 4 reject the
entire batch. This is sample-peak normalization, not true-peak limiting or LUFS
loudness normalization. Analysis runs synchronously on the control thread.

---

## Portable Project Collection

File/Collect project media... requires a new absolute folder. The original
document and files remain unchanged; open project.xtc inside the new folder to
use the copy. Referenced audio and track/graph sampler WAVs are deduplicated and
copied byte-for-byte, with relative references. Limits are 128 distinct assets,
256 MiB per file, 1 GiB total and a canonical folder path shorter than 480
bytes. Existing destinations, missing media, nonregular files and native graph
nodes reject. External plugin binaries/state are not collected; plugins must
remain installed. Invalid WAV data is copied rather than repaired. The folder is
visible during synchronous collection; failures remove owned outputs, and the
project file is saved last.