# 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.