Crate sim_lib_music_transform

Expand description

Music transformation layer for the SIM music constellation.

This crate applies transformations to musical material: classic operations such as transpose, invert, retrograde, augment, and diminish; exact identity-preserving staff operations for sustain, slur, expansion, delayed-note voice separation, register unwrapping, slicing, composition, and rhythm masks; configurable pitch and time remaps; pattern mutators; and a capability-gated custom event filter pipeline. Every exact staff operation returns a MusicTransform with stable identities and explicit edits. General object transforms return new Music, optionally paired with diagnostics in a TransformReport.

Structs§

AdditiveStaffPatch: Material introduced by a strictly additive staff transform.
CallableFilterDefinition: A named, reusable filter definition stored in a registry.
CallableFilterRef: A by-name reference to a registered callable filter.
CallableFilterRegistry: Lookup table of CallableFilterDefinition values by name.
CallablePitchMap: Named pitch map that applies a fixed chromatic offset to each pitch.
CustomFilter: A declared, capability-gated event filter with input/output shapes.
CustomFilterRun: Output of evaluating a custom filter: produced events and traces.
CustomFilterTrace: A single recorded step of a custom filter’s evaluation.
CustomPitchAxis: Named inversion axis carrying an explicit pitch.
ExactVoiceNote: One sounding note with the three exact score identities needed to trace it.
ExactVoicing: Exact sounding notes at one score boundary.
FilterCapabilitySet: An ordered set of FilterCapability grants.
FilterContext: Runtime grants and seed supplied when evaluating a custom filter.
FilterRule: A when -> op rule: an operation applied to matching events.
FilterShape: The set of lane kinds a filter port accepts.
FunctionMapRegistry: Lookup table of FunctionMap values addressed by name.
IntMatrix: Integer 2x3 affine matrix mapping (degree, octave, 1) to a new pitch.
InvertTransform: Inversion transform that mirrors pitch about a PitchAxis.
MapInverseWitness: Partial inverse row for a target value in a PitchMap.
MusicTransform: Exact transform value paired with identity and change evidence.
PatternLockSet: Set of source note indices held fixed (locked) during mutation.
PatternMutatorConfig: Configuration describing a sequence of pattern mutations and their controls.
PatternMutatorPlayer: Player that applies a PatternMutatorConfig to incoming material.
PitchMap: Partial map from folded source classes to absolute target offsets.
PitchMapComposition: Result of composing two PitchMap values with per-class witnesses.
PitchMapResult: Result of applying a PitchMap to one pitch.
RegisterRange: Inclusive semitone bounds and tie policy for register unwrapping.
RetrogradeTransform: Retrograde transform that reverses material under a RetrogradeMode.
RhythmMask: Periodic exact-onset rhythm mask.
SerialNoteEvidence: One retained serial note-evidence binding keyed by transformed staff identities.
SerialStaffTransform: One transformed serial staff plus explicit provenance status.
SerialTransformProvenance: Explicit serial provenance retained or retired by one transform.
SustainSpan: Exact half-open sustain-pedal interval.
TimeMapPoint: One (input -> output) breakpoint in a piecewise-linear time map.
TransformChain: An ordered pipeline of TransformStep values applied in sequence.
TransformDiagnostic: A single diagnostic emitted by a transform, tagged with its origin.
TransformReport: Result of a transform: the produced music plus any diagnostics raised.
TransposeTransform: Transpose transform that shifts pitch by a PitchDelta.
TuningRemap: Microtonal tuning offset expressed in cents.
VoiceLeading: Certified minimum-cost transition between two exact voicings.
VoiceLeadingPath: Certified adjacent voice-leading path through an exact progression.
VoiceLeadingPathCertificate: Aggregate certificate for a sequence of independently certified legs.
VoiceLeadingPolicy: Explicit costs and structural policy for exact voice leading.
VoicingChange: One directed transition in an exact voicing-change palette.
VoicingChangePalette: All directed transitions among a finite exact voicing palette.
WarpMarker: A warp anchor pairing a source time with its target time.

Enums§

AssignmentCertificate: Optimality witness for one of the two assignment solvers.
CustomFilterError: Error raised while building or evaluating a custom filter.
DelayedNoteOrder: Ordering used for simultaneous notes during delayed-note voice separation.
DeterminismPolicy: Determinism contract a custom filter promises to honor.
FilterBody: The evaluable body of a CustomFilter.
FilterCapability: A permission a custom filter must hold to perform a class of operations.
FilterOp: An operation a FilterRule performs on a matching event.
FilterPredicate: Condition selecting which events a FilterRule acts on.
FilterTraceAction: The kind of action recorded in a CustomFilterTrace.
FunctionMap: Named diatonic function (mode) used to remap scale degrees onto pitches.
MapCompositionWitness: Witness for one source class while composing two pitch maps.
MapError: Error returned by partial pitch map construction, application, or composition.
MapWitness: Witness explaining how a PitchMap handled one input pitch.
MusicTransformChange: One reversible or explicitly destructive change made by an exact transform.
MutationOp: A single mutation operation applied to a pattern’s notes.
PatternMutatorError: Error raised while parsing or validating a pattern mutator.
PitchAxis: Specification of the axis an InvertTransform mirrors about.
PitchDelta: Amount and kind of pitch displacement for a transpose transform.
PitchMapPolicy: Policy used when a PitchMap has no direct image for a source class.
PitchRemap: A pitch remapping strategy applied note by note across material.
RegisterTie: Tie direction for equally near octave placements.
RetrogradeMode: Strategy for placing notes when reversing material in time.
SerialProvenanceStatus: Whether a serial provenance facet survived a transform or was retired explicitly.
StretchPolicy: Strategy for stretching or warping material along the time axis.
TransformDiagnosticCode: Classification of a problem a transform encountered while running.
TransformError: Error returned by transforms that reject invalid scaling factors.
TransformStep: A single step in a TransformChain, wrapping one transform kind.
VoiceCrossingPolicy: Policy for assignments that reverse the order of two source voices.
VoiceLeadingMetric: Norm used to score semitone motion.
VoiceLeadingMotion: Identity-resolved interpretation of one generic assignment operation.

Statics§

RECIPES: Cookbook recipes for this lib, embedded at build time.

Functions§

apply_additive_staff_patch: Applies new voices and notes while retaining every source value verbatim.
apply_rhythm_mask: Keeps notes whose exact onset lands on a true periodic mask slot.
apply_serial_row_operation: Applies a total row operation to the realized pitches and time order.
augment: Lengthens every onset and duration by factor (time augmentation).
chord_tones_in: Snaps every note to the nearest pitch belonging to the given scale.
compose_pitch_map_report: Composes a followed by b, returning witnesses for lossy classes.
compose_pitch_maps: Composes a followed by b, discarding per-class witnesses.
diminish: Shortens every onset and duration by factor (time diminution).
ensure_custom_filter_codec: Checks that a codec name is supported by the custom filter surface.
expand_staff: Expands every onset, note duration, and voice span by a positive exact factor.
invert_serial: Inverts every realized pitch class around axis, preserving ids but retiring row-form labels.
lane_kind_from_wire: Parses a lane kind from its wire label, if recognized.
loop_n: Repeats the material n times back to back along the time axis.
map_to_function: Remaps each in-key note to the same scale degree under another function.
mutate_pattern: Applies a PatternMutatorConfig to material and returns the mutated music.
parallel_staff: Composes staffs in parallel, retaining exact onsets and maximum duration.
pitch_class_name: Returns the canonical name of a pitch class.
pitch_invert: Inverts every note’s pitch about the given axis pitch.
player_mutator: Builds a PatternMutatorPlayer from a mutator configuration.
progression_multiply: Multiplies every exact onset, duration, and trailing span in a progression.
progression_overlay: Overlays exact progressions at the same origin.
progression_repeat: Repeats a progression back to back while keeping global identity unique.
progression_slice: Extracts an exact half-open progression window.
quantize_serial: Quantizes only when the result is already exact on the requested grid; otherwise fails closed.
quarter: Returns the Time value for one quarter note (1/4).
remap_serial_voices: Renames voices through an explicit mapping while retaining note/event origins.
remove_additive_staff_patch: Removes exactly the material named by an additive patch.
render_serial_notation_score: Renders realized serial material to a notation-compatible score surface.
restore_register: Restores the original pitches recorded by unwrap_register.
retrograde: Reverses the material in time using the default RetrogradeMode::Cutout.
retrograde_invert: Applies pitch_invert then retrograde (retrograde inversion).
retrograde_serial: Reverses realized chronology and retires chronology-dependent provenance explicitly.
retrograde_with_mode: Reverses the material in time using the given RetrogradeMode.
scale_serial_time: Scales exact onsets and durations while retaining pitch and serial evidence.
separate_delayed_notes: Splits delayed overlapping notes into monophonic voices without moving them.
sequence_staff: Composes staffs in sequence, shifting later onsets by exact prior durations.
shift_octave: Shifts every note by the given number of whole octaves.
silence: Builds a Rest spanning the given duration.
simple_melody: Builds a single-voice Melody from (MIDI key, duration) pairs.
slice: Extracts the [start, end) time window, clipping note spans to the bounds.
slice_staff: Extracts an exact half-open staff slice and reports clipping/removal.
slur_staff: Connects each note in a voice to its next onset and marks it legato.
sustain_staff: Extends note releases that occur while one of spans is active.
time_invert: Mirrors note onsets about the total duration, then rebases to start at zero.
transpose: Transposes every note chromatically by the given number of semitones.
transpose_diatonic: Transposes every note by steps scale degrees within the given scale.
transpose_serial: Transposes every realized pitch while retaining event and note identities.
unwrap_register: Chooses octave placements that minimize adjacent motion within range.
verify_voice_leading: Re-checks exact endpoints, operation projection, and the discrete optimality certificate.
verify_voice_leading_path: Re-checks all leg certificates, adjacency, and the aggregate path total.
voice_leading: Finds certified minimum-cost voice leading without factorial permutation search.
voice_leading_path: Finds every adjacent optimum and returns their checked path certificate.
voicing_change_palette: Builds a duplicate-free, deterministic palette of every directed transition between distinct exact voicings.