89 lines
5.4 KiB
Markdown
89 lines
5.4 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 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.
|
|
|
|
## 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.
|