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.