104 lines
5.6 KiB
Markdown
104 lines
5.6 KiB
Markdown
# 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.
|