Docs file normalization.
This commit is contained in:
parent
dd32143bf8
commit
619c2d0808
46 changed files with 3587 additions and 2579 deletions
183
docs/CONTROL.md
183
docs/CONTROL.md
|
|
@ -1,41 +1,45 @@
|
|||
# Automation and expressive control
|
||||
# Automation and Expressive Control
|
||||
|
||||
Track Gain/Pan lanes in the Mixer apply to audio and scheduled instrument voices.
|
||||
They use absolute project ticks, linear or hold interpolation, hold-first/last outside
|
||||
points and the constant project tempo snapshot. A clip trim/move does not move
|
||||
track or effect automation: lanes belong to the project timeline. Instrument
|
||||
volume is controlled by its track Gain lane; the current sine has no timbre
|
||||
parameter. Track gain ramps and boundary fades are described in AUDIO_QUALITY.md.
|
||||
Track Gain/Pan lanes in the Mixer apply to audio and scheduled instrument
|
||||
voices. They use absolute project ticks, linear or hold interpolation,
|
||||
hold-first/last outside points and the constant project tempo snapshot. A clip
|
||||
trim/move does not move track or effect automation: lanes belong to the project
|
||||
timeline. Instrument volume is controlled by its track Gain lane; the current
|
||||
sine has no timbre parameter. Track gain ramps and boundary fades are described
|
||||
in AUDIO_QUALITY.md.
|
||||
|
||||
Select a LADSPA node in Modular Graph and use Edit/Selected plugin automation.
|
||||
Enter `port tick mode value`: mode 0 interpolates linearly, 1 holds until the next
|
||||
point, and -1 removes the point at that port/tick (value ignored). Port names,
|
||||
ranges and current tick are displayed. There are at most 32 points per plugin;
|
||||
setting an existing port/tick replaces it. Integer/toggle controls require step
|
||||
mode. Invalid values, ticks, ports or duplicate persisted points reject the edit
|
||||
or file. Edits are undoable and rebuild on the control thread while stopped.
|
||||
Enter `port tick mode value`: mode 0 interpolates linearly, 1 holds until the
|
||||
next point, and -1 removes the point at that port/tick (value ignored). Port
|
||||
names, ranges and current tick are displayed. There are at most 32 points per
|
||||
plugin; setting an existing port/tick replaces it. Integer/toggle controls
|
||||
require step mode. Invalid values, ticks, ports or duplicate persisted points
|
||||
reject the edit or file. Edits are undoable and rebuild on the control thread
|
||||
while stopped.
|
||||
|
||||
Effect lanes use the project tempo, hold first/last outside their range and
|
||||
apply before run at each exact sample. Distinct ticks rounding to one sample
|
||||
resolve to the later tick. Linear curves avoid stepping continuous controls;
|
||||
intentional step curves may click. The initial implementation calls run(1) while
|
||||
any lane exists, with connected preallocated buffers. CPU cost can be significant;
|
||||
only the documented LADSPA set is qualified. No worker, allocator, loader or
|
||||
clock is called from the host audio path. Native ABI 2 callers continue to use
|
||||
sample-offset parameter events, applied before equal-offset MIDI events.
|
||||
any lane exists, with connected preallocated buffers. CPU cost can be
|
||||
significant; only the documented LADSPA set is qualified. No worker, allocator,
|
||||
loader or clock is called from the host audio path. Native ABI 2 callers
|
||||
continue to use sample-offset parameter events, applied before equal-offset MIDI
|
||||
events.
|
||||
|
||||
Live MIDI input maps CC7 to per-channel volume (0..1), CC10 to pan (64 center),
|
||||
and CC64 to sustain (>=64 down). Volume/pan ramp over 5 ms. These default mappings
|
||||
apply to live sine voices, not track faders or prerecorded clips; controller
|
||||
capture, automatic learn and plugin MIDI are not supported. CC120/123 and
|
||||
Panic release all live voices and sustain and suppress already-started scheduled
|
||||
notes. Note-on velocity zero decodes to note-off. Repeated live note-on on one
|
||||
channel/pitch retriggers one voice; note-off releases it or marks it pending while
|
||||
sustain is held. Sustain-up releases pending voices, never newer retriggers.
|
||||
Seek, stop, teardown and disconnect clear live voices; plan reset returns controller
|
||||
values to unity/center. Equal-offset live events execute in input order before
|
||||
the sample; arrange note ends precede starts, and scheduled mixer values are
|
||||
evaluated at that sample. Overlapping arranged notes are independent.
|
||||
and CC64 to sustain (>=64 down). Volume/pan ramp over 5 ms. These default
|
||||
mappings apply to live sine voices, not track faders or prerecorded clips;
|
||||
controller capture, automatic learn and plugin MIDI are not supported. CC120/123
|
||||
and Panic release all live voices and sustain and suppress already-started
|
||||
scheduled notes. Note-on velocity zero decodes to note-off. Repeated live
|
||||
note-on on one channel/pitch retriggers one voice; note-off releases it or marks
|
||||
it pending while sustain is held. Sustain-up releases pending voices, never
|
||||
newer retriggers. Seek, stop, teardown and disconnect clear live voices; plan
|
||||
reset returns controller values to unity/center. Equal-offset live events
|
||||
execute in input order before the sample; arrange note ends precede starts, and
|
||||
scheduled mixer values are evaluated at that sample. Overlapping arranged notes
|
||||
are independent.
|
||||
|
||||
Format v6 preserves v5 data plus effect lanes. A v5 plugin migrates with no lane
|
||||
and the project tempo. Repeated render/save/reopen, odd block partition, exact
|
||||
|
|
@ -46,12 +50,16 @@ make test test-control test-plugins test-gui-plugins test-plugins-real
|
|||
```
|
||||
|
||||
Physical controller devices and listening remain unqualified; no tempo map,
|
||||
latency compensation, MIDI capture, pitch bend or plugin crash isolation is added.
|
||||
latency compensation, MIDI capture, pitch bend or plugin crash isolation is
|
||||
added.
|
||||
|
||||
## Common parameter targets
|
||||
---
|
||||
|
||||
`xtc_control.h` identifies a parameter by `(kind, stable owner ID, parameter ID)`.
|
||||
IDs never mean a dense list index and are not DSP pointers:
|
||||
## Common Parameter Targets
|
||||
|
||||
`xtc_control.h` identifies a parameter by
|
||||
`(kind, stable owner ID, parameter ID)`. IDs never mean a dense list index and
|
||||
are not DSP pointers:
|
||||
|
||||
| Kind | Owner | Parameter IDs | Metadata/reset defaults |
|
||||
| --- | --- | --- | --- |
|
||||
|
|
@ -59,39 +67,44 @@ IDs never mean a dense list index and are not DSP pointers:
|
|||
| PLUGIN | LADSPA graph node ID | Actual input-control port | Descriptor name, bounds, default and discrete/logarithmic hints; units unspecified |
|
||||
| LIVE | MIDI channel 0..15 | 0 volume, 1 pan, 2 sustain | Volume 0..1 default 1; pan -1..1 default 0; sustain boolean default 0 |
|
||||
|
||||
`xtc_project_parameter` returns copied metadata, static configuration and whether
|
||||
a lane exists. LIVE values are reset defaults, not callback-owned controller
|
||||
readbacks. `xtc_project_set_parameter` changes TRACK/PLUGIN static configuration
|
||||
without deleting automation. `xtc_project_automate` sets/replaces/removes points
|
||||
for TRACK/PLUGIN through one C contract. LIVE static setters and timeline lanes
|
||||
are unsupported: these controls belong to incoming MIDI events, not the arranged
|
||||
instrument. Plugin metadata/control edits execute trusted discovery on the
|
||||
control thread; they never run inside audio. Model-only clients must compile and
|
||||
publish accepted snapshots before rendering; GUI edits do this transactionally.
|
||||
`xtc_project_parameter` returns copied metadata, static configuration and
|
||||
whether a lane exists. LIVE values are reset defaults, not callback-owned
|
||||
controller readbacks. `xtc_project_set_parameter` changes TRACK/PLUGIN static
|
||||
configuration without deleting automation. `xtc_project_automate`
|
||||
sets/replaces/removes points for TRACK/PLUGIN through one C contract. LIVE
|
||||
static setters and timeline lanes are unsupported: these controls belong to
|
||||
incoming MIDI events, not the arranged instrument. Plugin metadata/control edits
|
||||
execute trusted discovery on the control thread; they never run inside audio.
|
||||
Model-only clients must compile and publish accepted snapshots before rendering;
|
||||
GUI edits do this transactionally.
|
||||
|
||||
Unknown owners/ports fail without touching the destination model/output. Missing
|
||||
plugin modules fail discovery rather than guessing ranges or installing a dummy.
|
||||
Track deletion removes its lanes; plugin deletion removes its embedded lanes.
|
||||
Compatible plugin replacement resets controls/automation as described in
|
||||
PLUGIN_HOSTING.md. Persisted dangling references reject the complete load;
|
||||
the current project remains intact. The GUI reports rejected edits/Open failures.
|
||||
PLUGIN_HOSTING.md. Persisted dangling references reject the complete load; the
|
||||
current project remains intact. The GUI reports rejected edits/Open failures.
|
||||
|
||||
## Interpolation and precedence
|
||||
---
|
||||
|
||||
## Interpolation and Precedence
|
||||
|
||||
The Mixer Interpolation chooser selects Linear or Hold (step) for the point
|
||||
being added/replaced. A point owns the segment beginning there. At a hold point,
|
||||
its value remains until the next point's exact sample. Linear segments interpolate
|
||||
between endpoint values without an extra smoothing stage. Hold first/last before/
|
||||
after the lane. Gain/pan for tracks and buses support both; integer/toggle LADSPA
|
||||
controls require hold. Existing files migrate mixer points to linear.
|
||||
its value remains until the next point's exact sample. Linear segments
|
||||
interpolate between endpoint values without an extra smoothing stage. Hold
|
||||
first/last before/ after the lane. Gain/pan for tracks and buses support both;
|
||||
integer/toggle LADSPA controls require hold. Existing files migrate mixer points
|
||||
to linear.
|
||||
|
||||
Automation is absolute project time, independent of clip starts, ends, trims,
|
||||
splits and moves; it neither restarts nor resets at a clip boundary. Tick-to-sample
|
||||
rounding uses the prepared constant tempo/rate; distinct ticks landing on the
|
||||
same sample choose the greatest tick. Empty lanes restore the static value.
|
||||
Static edits while a lane exists change the fallback value, not the audible lane.
|
||||
GUI changes stop/rebuild snapshots; live mutation of faders/plugin instances is
|
||||
not introduced. Plugin reset removes lanes only when explicitly applied.
|
||||
splits and moves; it neither restarts nor resets at a clip boundary.
|
||||
Tick-to-sample rounding uses the prepared constant tempo/rate; distinct ticks
|
||||
landing on the same sample choose the greatest tick. Empty lanes restore the
|
||||
static value. Static edits while a lane exists change the fallback value, not
|
||||
the audible lane. GUI changes stop/rebuild snapshots; live mutation of
|
||||
faders/plugin instances is not introduced. Plugin reset removes lanes only when
|
||||
explicitly applied.
|
||||
|
||||
At each sample, arranged track/bus and plugin lanes apply to their own targets.
|
||||
Incoming MIDI volume/pan/sustain affect only live sine voices on that channel,
|
||||
|
|
@ -107,41 +120,47 @@ the new position. Backward jumps evaluate the earlier timeline again; tests
|
|||
exercise explicit wraps. There is no loop transport feature or promise to
|
||||
restore opaque LADSPA delay history across jumps (transport reset retains it).
|
||||
|
||||
## Configurable live MIDI bindings
|
||||
---
|
||||
|
||||
## Configurable Live MIDI Bindings
|
||||
|
||||
Audio → MIDI controller mapping lists the current 16 channels. Enter
|
||||
`channel volume_CC pan_CC sustain_CC`, for example `2 1 74 11`. Channels are
|
||||
zero-based; CCs are 0..127, or 128 to disable a target. Enabled CCs must be distinct
|
||||
within a channel; CC120 and CC123 cannot be rebound. All channels default to
|
||||
7/10/64. Rebinding replaces the old binding; it is not an additional route. An
|
||||
unmapped CC does nothing. Other channels remain independent. The same volume,
|
||||
pan and sustain transfer functions apply regardless of the chosen CC number.
|
||||
Disabling a target leaves it at its runtime reset value until plan replacement.
|
||||
Changing a map stops/rebuilds playback and is one undoable edit; maps survive
|
||||
save/Open and undo/redo. Cancel and invalid/duplicate/reserved bindings retain
|
||||
the prior configuration. There is no automatic learn, arbitrary plugin/track CC
|
||||
mapping, MIDI capture or write/touch/latch automation mode.
|
||||
zero-based; CCs are 0..127, or 128 to disable a target. Enabled CCs must be
|
||||
distinct within a channel; CC120 and CC123 cannot be rebound. All channels
|
||||
default to 7/10/64. Rebinding replaces the old binding; it is not an additional
|
||||
route. An unmapped CC does nothing. Other channels remain independent. The same
|
||||
volume, pan and sustain transfer functions apply regardless of the chosen CC
|
||||
number. Disabling a target leaves it at its runtime reset value until plan
|
||||
replacement. Changing a map stops/rebuilds playback and is one undoable edit;
|
||||
maps survive save/Open and undo/redo. Cancel and invalid/duplicate/reserved
|
||||
bindings retain the prior configuration. There is no automatic learn, arbitrary
|
||||
plugin/track CC mapping, MIDI capture or write/touch/latch automation mode.
|
||||
|
||||
Plans copy only 48 binding bytes on the control thread. The callback compares
|
||||
at most three CC numbers per control event, uses existing preallocated ramps/
|
||||
Plans copy only 48 binding bytes on the control thread. The callback compares at
|
||||
most three CC numbers per control event, uses existing preallocated ramps/
|
||||
voices and the existing 256-event block budget. Decode now accepts all valid
|
||||
three-byte CC messages; even unmapped CCs count against that event budget.
|
||||
Mixer points compile to bounded sorted arrays with binary lane lookup; processing
|
||||
does no allocation, sort, file/module I/O, locking or GUI work. LADSPA automated
|
||||
three-byte CC messages; even unmapped CCs count against that event budget. Mixer
|
||||
points compile to bounded sorted arrays with binary lane lookup; processing does
|
||||
no allocation, sort, file/module I/O, locking or GUI work. LADSPA automated
|
||||
run(1) cost and native plugin trust limits remain unchanged.
|
||||
|
||||
## Persistence and verification
|
||||
---
|
||||
|
||||
## Persistence and Verification
|
||||
|
||||
Project v10 appends a mixer interpolation field and 16 controller-map records;
|
||||
v1–v9 migrate to linear mixer lanes and default 7/10/64 maps. LADSPA point encoding
|
||||
is unchanged. Public `xtc_automation_point` gains `step`: rebuild clients and
|
||||
initialize it to 0 (linear) or 1 (hold). See PROJECT_FORMAT.md for exact grammar.
|
||||
v1–v9 migrate to linear mixer lanes and default 7/10/64 maps. LADSPA point
|
||||
encoding is unchanged. Public `xtc_automation_point` gains `step`: rebuild
|
||||
clients and initialize it to 0 (linear) or 1 (hold). See PROJECT_FORMAT.md for
|
||||
exact grammar.
|
||||
|
||||
`test_parameters` covers metadata, missing targets, static/automation precedence,
|
||||
exact hold/linear boundaries, save/reopen, malformed maps, low-rate sample
|
||||
collisions, odd blocks, seeks and backward jumps. `test_control` compares default
|
||||
and remapped event streams, stereo pan, disabled/unmapped controls and immutable
|
||||
plan maps across resets. Plugin tests cover common-target edits and persistence;
|
||||
GUI tests cover interpolation, map rollback, undo/redo and save/Open. Existing
|
||||
callback guards and sanitizers verify host ownership constraints. Physical
|
||||
controller devices, listening and extended high-density endurance are pending.
|
||||
`test_parameters` covers metadata, missing targets, static/automation
|
||||
precedence, exact hold/linear boundaries, save/reopen, malformed maps, low-rate
|
||||
sample collisions, odd blocks, seeks and backward jumps. `test_control` compares
|
||||
default and remapped event streams, stereo pan, disabled/unmapped controls and
|
||||
immutable plan maps across resets. Plugin tests cover common-target edits and
|
||||
persistence; GUI tests cover interpolation, map rollback, undo/redo and
|
||||
save/Open. Existing callback guards and sanitizers verify host ownership
|
||||
constraints. Physical controller devices, listening and extended high-density
|
||||
endurance are pending.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue