xtc/docs/PREFERENCES.md

Application preferences and looping

Open Edit / Preferences (Ctrl+,). Each tab edits application settings. Apply validates every tab, saves ~/.xtc.conf, and applies the values. Close discards edits made since the last Apply. Apply stops playback; stop recording before opening Preferences. Clean exit also saves collected application settings. Startup reads ~/.xtc.conf before project/backend creation; missing keys use defaults. Malformed configuration reports an error and uses defaults without overwriting it. Invalid input or failed writes preserve the previous saved configuration.

The file is INI with [audio], [plugins], [midi], [interface], [editing], [project_defaults] and [transport] sections. Save uses a mode-0600 temporary file, flushes and fsyncs it, then atomically renames it. Unknown keys/sections, duplicate keys, invalid ranges, embedded NULs and files larger than 64 KiB are rejected. Blank lines and full-line ; / # comments are supported. Strings may be quoted, with \\ and \" escapes. Apply rewrites comments and formatting.

Section	Settings and defaults
audio	client_name="xtc", max_frames=65536, channels=2, transition_ms=5, offline_rate=48000, recording_seconds=2
plugins	clap_paths, vst2_paths, vst3_paths, ladspa_paths: colon-separated ~/.clap, ~/.vst, ~/.vst3, ~/.ladspa, followed by corresponding /usr/local/lib/ and /usr/lib/ directories
midi	midi_input_port="", midi_output_port="", midi_input_channel=-1, midi_output_channel=-1, midi_thru=0; ports connect on Play/Record
interface	main_x=0, main_y=0, inspector_visible=0, width=1280, height=800, piano_width=900, piano_height=620, refresh_ms=100
editing	sequencer_snap=240, piano_snap=240, sequencer_zoom=48, clip_ticks=3840, note_ticks=960, note_velocity=100, note_channel=0, filter_channel=-1, filter_low=0, filter_high=127
project_defaults	tempo=120000 (milli-BPM), volume_cc=7, pan_cc=10, sustain_cc=64 (128 disables a mapping)
transport	loop_start=0, loop_end=3840, loop_enabled=0, follow_playhead=0

Audio client name, block capacity, output channels and fades take effect on Reconnect. JACK chooses the actual device, rate and hardware buffer size; these remain JACK server settings. Offline rate is used when disconnected. Recording capacity applies to the next take. Tempo and CC maps apply to New projects. Track mix, routing, instruments, plugin parameters, automation and musical content remain project data, saved through Save Project. Internal safety limits and plugin ABI requirements are not runtime preferences.

Snap accepts 1 (Off), 120, 160, 240, 320, 480, 960, 1920 or 3840 ticks. Zoom accepts 24, 48, 96, 192 or 384 pixels per beat. MIDI channels are zero-based; filter channel -1 shows all channels. Window sizes, grids and filters currently in use populate Preferences when it opens; Apply or a clean application exit persists them.

Plugin selection now opens a library of .clap and .so files from the search paths. ~/ expands to the home directory; empty/nonabsolute roots are skipped. Traversal does not follow directory symlinks and stops at depth six, 4096 entries or 512 files. Linux VST3 bundle binaries are found inside bundle directories. Listing reads filenames only. Inspect plugin explicitly loads the selected trusted binary through the existing descriptor chooser; Browse files allows other locations. It is not a plugin certification or isolation service.

Loop playback

Shift-drag the sequencer ruler to select a region using the selected Snap. Dragging in either direction works. A band shows the region; Loop enables or disables it. Loop range... also accepts start and end in ticks. Selection and toggling take effect immediately; Apply or clean exit persists the region. The region is global application configuration and is not stored in .xtc projects. Changing a region during playback stops, reconfigures and restarts the backend. Selecting a region does not itself enable looping.

Playback wraps at the exclusive end sample, including inside an audio block, and starts at the region beginning when the transport lies outside the region. The region follows the current project's tempo. Enabled regions must span at least 64 samples at the active rate. Scheduled MIDI uses the existing seek/reset and note-chase behavior at a wrap. Effects retain tails/state. No loop-boundary crossfade is added, so discontinuous audio can click. Recording requires looping to be disabled. Export retains its explicit linear range.

Validation covers settings roundtrips, malformed/duplicate/overflow/NUL input, private permissions, save failure, GUI Apply/Close/reload and plugin listing, plus JACK callback wrap positions and existing GUI/core regressions. Tests use temporary configuration paths and do not write the user's configuration.

[transport] tail_ms=3000 (0..60000) and stop_after_tail=0 (0/1) are supported. Export always includes the configured tail; optional playback stopping uses the GUI timer and is disabled during looping/recording. See BUILTIN_DEVICES.md for endpoint, cancellation and reset semantics.

[interface] provides transport_detached, mixer_detached, and each panel's _x, _y, _width, _height rectangle. Use Preferences / Apply or close the application cleanly after moving panels to save the captured layout. Restoration clamps rectangles to the current display; the floating transport wraps at narrow widths.

[interface] also includes sequencer_detached, graph_detached, piano_detached, editor window geometry and track_header_width (180..360). Piano retains piano_width/piano_height and adds piano_x/piano_y. Reset workspace layout changes the session; Preferences / Apply or clean exit persists it. Only original-tab docking and floating windows are supported.

Configuration also includes complete workspace collection and MIDI ports/channels/thru. Invalid startup files are preserved on exit; explicit Apply can replace them after validation. If saving fails, the window stays open for retry. See MIDI_WORKFLOWS.md for device setup and notes-only Standard MIDI File import/export. JACK server hardware settings and musical project contents remain owned by the server and project respectively.