Crate sim_lib_music_transform 

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; configurable pitch and time remaps; pattern mutators; and a capability-gated custom event filter pipeline. Transforms read a MusicObject into a canonical PianoRoll and return new Music, optionally paired with diagnostics in a TransformReport.

Structs

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.

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.

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.

RetrogradeTransform

Retrograde transform that reverses material under a RetrogradeMode.

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.

WarpMarker

A warp anchor pairing a source time with its target time.

Enums

CustomFilterError

Error raised while building or evaluating a custom filter.

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.

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.

PitchRemap

A pitch remapping strategy applied note by note across material.

RetrogradeMode

Strategy for placing notes when reversing material in time.

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.

Functions

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.

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.

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.

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.

quarter

Returns the Time value for one quarter note (1/4).

retrograde

Reverses the material in time using the default RetrogradeMode::Cutout.

retrograde_invert

Applies pitch_invert then retrograde (retrograde inversion).

retrograde_with_mode

Reverses the material in time using the given RetrogradeMode.

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.

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.