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 selected routes. A missing port rejects that start and stops the backend, preserving the saved choice for retry. 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.