xtc/docs/MIDI_WORKFLOWS.md

# Application Configuration and MIDI Workflows

`~/.xtc.conf` is the application's base configuration. It is read before
creating its first project and backend. Missing keys use compiled defaults.
Preferences Apply writes every tab atomically with owner-only permissions; clean
exit also collects workspace, snap/zoom, loop, piano filters and note defaults.
A missing file is created on Apply or clean exit. Invalid files produce a
visible startup error and are preserved until an explicit successful Apply
replaces them. A save failure keeps the window open for retry. Project contents,
plugin states and session clipboards are project/session data, not application
preferences.

All persistent preference fields are listed by the shared C schema and available
in Preferences. Existing project tempo/controller maps remain project data;
Preferences project defaults apply to New. No configuration I/O runs in an audio
callback. Tests and screenshot captures use isolated configuration paths.

---

## MIDI Backend

xtc exposes `midi_in` and `midi_out` JACK ports. The output sends scheduled MIDI
clip notes from unmuted, solo-eligible tracks, retaining source channels and
velocities, with clipped note boundaries and notes chased after seeks/loops.
Tracks share one output; matching pitches/channels on different tracks can
conflict on receiving devices. Audio faders, effects and bus processing do not
alter external MIDI. MIDI CC automation, program changes, clock and SysEx output
are outside this note-output workflow.

Input can filter a single channel, and output can preserve or force a channel.
Optional thru forwards supported live notes, controllers and pitch bend while
transport is active. Thru defaults off to avoid accidental feedback. Callback
work and event buffers are bounded; overflow requests all-notes-off and
increments the MIDI-drop counter. Panic and stop send CC123 on all channels.
Immediate stop waits up to 100 ms for callback acknowledgement before
deactivation; delivery cannot be guaranteed after server/device loss or to
devices ignoring CC123. No device is connected unless a user chooses it or an
external patchbay routes it.

---

## MIDI Preferences

Preferences → midi has editable dropdowns for a default input source and output
destination, plus a Refresh MIDI devices button. Names are enumerated from the
current JACK/PipeWire server, excluding xtc's own ports. Select None or clear a
field for no automatic connection. Typed offline names remain saved. Hardware
ports are visible only when the host exposes them through its MIDI bridge.

Input channel `-1` accepts all channels; `0..15` selects MIDI channel 1..16.
Output channel `-1` preserves note channels; `0..15` forces a channel. Thru
defaults off. Apply saves these choices; the next Play/Record restores the
available selected routes. Missing ports produce a nonblocking warning; playback
continues with built-in instruments and audio clips. Saved device choices remain
unchanged and are checked again on every start, including Record. An available
counterpart still connects. Backend activation and other routing errors remain
errors. Reconnect audio after server loss, then
retry Play. Defaults also apply when playback resumes after a loop edit. MIDI
input/thru currently requires active transport. Existing editing and
project_defaults tabs contain note length, velocity, channel, filters and
new-project controller mappings.

---

## Export A Selected Clip

Select exactly one MIDI clip and choose File → Export selected clip as MIDI. The
save chooser confirms overwrites. Export writes an atomic Standard MIDI File
(type 0, 960 PPQN) with project tempo, clip name and audible notes relative to
the clip start, retaining channels and velocities. Notes crossing trimmed
boundaries are cropped and notes outside the trim are omitted. Trailing silence
remains. Export does not edit the project or undo history. Audio clips reject.
Only note messages are exported: instruments, opaque plugin data, controller
maps, automation and audio are excluded. Export is unavailable during recording.

---

## Import MIDI Files

File → Import MIDI (also in the sequencer Create menu) adds a clip at the cursor
on the selected non-bus track, or creates a track when none is selected. Import
is one undoable prepared edit; malformed files, capacity errors and failed
backend preparation retain the old project and IDs.

The reader supports Standard MIDI File types 0 and 1 with PPQN timing, including
running status and velocity-zero note-offs. File tracks merge into one clip;
channels and velocities remain. Timing rounds to 960 ticks per quarter note,
with positive sub-tick notes given one tick. Trailing silence remains. The
project tempo is retained: tempo maps, time signatures, CC/sustain, program
changes, pitch bend, SysEx and other metadata are not imported. This is a notes
workflow, not full-song or instrument reconstruction.

Limits are 1 MiB per file, 64 file tracks, 65,536 parsed events and 4,096 notes
within the project's total note capacity. SMPTE timing and type 2 reject
explicitly. Unterminated notes, zero source duration and malformed events reject
rather than silently dropping notes. Unmatched note-offs are harmless and
ignored. Overlapping same-pitch notes pair FIFO within each file track/channel.
Project save/reload uses the existing format; no format migration or extra
dependency is required.

Configured startup holds the transport clock and emits silence until selected
MIDI ports are connected, so notes at the song start are not consumed before
routing. MIDI routing retries publication for at most 100 ms on the control
thread; the callback never sleeps or calls the JACK graph connection APIs.