xtc/docs/MODERN_EDITING.md

# Modern Editing Workflows

These control-thread edits were introduced without changing format 15. The
current writer uses format 16 for arrangement markers and still reads older
projects. Session selections, clipboard and comparison snapshots are not saved
in projects. Audio callbacks continue to consume prepared plans; edits use the
existing stop/history workflow.

---

## Arrangement Multi-Selection

Shift-click clips to toggle selection; Ctrl+A in the sequencer or Edit/Select
all clips selects every clip. Plain clicking replaces the selection. Selection
is session UI state; no marquee selection yet.

---

## Transactional Group Editing

Use Left/Right in the sequencer (or Edit/Nudge selection) to move the selected
phrase by the current snap step. Ctrl+D duplicates after its complete bounding
span; Delete removes selected clips. Edits are atomic and undoable. Mouse
dragging remains a single-clip gesture.

---

## Arrangement Clipboard

Ctrl+C/Ctrl+V in the sequencer, or Edit/Copy clips and Paste clips at cursor,
copy/paste the selection. Earliest clip lands on the cursor. The earliest source
track maps to the currently selected destination track; intervening track
spacing is retained. All required tracks must already exist and must not be
buses. Instruments, automation and media bytes are not copied. The clipboard
survives document changes within the window but is not the OS clipboard.

---

## Repeat Arrangement Patterns

Edit/Repeat selected phrase asks for 1..1024 additional copies. The bounding
span includes gaps and overlaps; copies remain on their original tracks. The
entire repeat is one undo step. Clip/note capacity and timeline endpoints can
limit the requested count.

---

## Align and Slip Editing

Edit/Align clip starts to cursor places every selected start at the cursor. Slip
sources earlier/later changes source offsets by the snap step while retaining
timeline positions and durations. Trimming must leave source material available;
an invalid slip rejects the whole selection. No time stretching or destructive
media edits are performed.

---

## MIDI Swing Quantization

Select MIDI clips and use Edit/MIDI tools/Swing quantize. Grid is in source
ticks; swing delays alternate subdivisions by 0..half a grid step, while
strength blends the old start toward the nearest swung point. Durations stay
fixed. All source notes are affected, including notes outside visible trims.
Mixed audio/MIDI selections and notes that would exceed source bounds reject the
entire edit. This is destructive note editing with undo, not a live groove
engine.

---

## MIDI Legato and Gate Tools

Edit/MIDI tools/Note gate scales lengths from 1 to 400 percent, rounded to at
least one tick. Legato ends notes at the next strictly later onset in the same
clip and channel; notes in a chord end together. The final onset extends to
source end. Gate expansion beyond the source rejects the whole edit. Undo
restores original durations.

---

## MIDI Scale Correction

Edit/MIDI tools/Correct to scale takes a root (0=C through 11=B) and chromatic,
major or natural minor. Each pitch moves to the nearest permitted MIDI note;
ties choose the lower pitch. Timing, channel and velocity remain unchanged.
Corrections can produce unison notes; notes are not merged. This changes MIDI
notes, not audio pitch or a live scale filter.

---

## MIDI Velocity Shaping

Edit/MIDI tools/Shape velocities scales from 0 to 400 percent, rounds, then
applies an offset from -127 to 127. Results clamp to 1..127, keeping every note
audible rather than introducing velocity-zero note-offs. Use 0 percent with a
positive offset for a fixed velocity. No randomization is applied.

---

## Batch Audio Fade Tools

Edit/Audio tools/Set boundary fades sets linear fade-in and fade-out lengths in
ticks; 0 or Remove boundary fades clears them. Each fade must fit within half of
every selected clip duration. Gain and source offsets stay unchanged. These are
boundary envelopes, not overlap-aware crossfades, equal-power curves or
destructive WAV processing.

---

## Mixer A/B Comparison

Edit/Mixer comparison captures or recalls A and B. Capture stores static gain,
pan, mute and solo for every track and bus without changing the document. Recall
requires the same stable track IDs, stops playback through the normal edit guard
and creates one undo step. Track order may change. Routing, plugins and
automation are excluded; automation still overrides static gain and pan. Slots
are session-only and clear on New/Open. This is static mix comparison, not
seamless live scene morphing.

---

## Validation and Remaining Scope

The code is built with warnings enabled and tested. Reproduce the core,
transaction and allocation-failure checks with:

```sh
cmake --build build/roadmap-audit --parallel && cmake --build build/roadmap-audit --target gui test-reliability
cmake --build build/roadmap-audit --target test-gui-modern-editing
```

The full GUI, instrument/effect plugin fixtures, software JACK lifecycle, Clang
static analysis, AddressSanitizer/UBSan and staged default/custom installation
checks also cover the integrated changes. GUI leak checks use only the existing
system Fontconfig suppression. Save/reload comparisons render identical nonzero
MIDI output after musical transforms; no project format migration is required.

These workflows improve arrangement and musical editing workflows. They do not
provide DAW feature parity: time stretching, comping, a clip launcher, tempo
maps, track insert chains and customizable shortcuts need separate designs. No
new dependencies or audio-callback operations are introduced. Human listening,
physical devices and arbitrary third-party plugins remain unqualified.