Edition draft-56 · Draft · Source-reviewed instructions · Native coverage incomplete

Chapter 25

Scripting and API

Local Lua scripts #

Open Settings > Scripts. Open Folder opens the scripts directory; add .lua files there, then choose Refresh. The list groups scripts by folder and shows the filename and any first-line description. Choose Run beside the script you reviewed.

The result notification says Script completed. or Script error: and includes captured output when available. Local scripts use the arbit command table to read or edit project data. A script can act on more than the current selection, so inspect its code and try it on a saved project copy first.

A one-shot script that reports Script error: can leave project edits made before the error in place. Inspect the changed project and use Undo as needed. Keep a saved project copy before running a script you have not tried.

Each run starts with a fresh Lua state, but it still reads and edits the current project. Lua does not expose its standard filesystem libraries here, yet the arbit command table includes import and export operations. Review those calls before running a script.

Parameterized Lua transforms use the command/API transform workflow. Installing a script does not add a toolbar button. Lua scripting is a core tool in the current app rather than an optional Store checkbox.

Video scripts #

Draft: these controls are documented from source. The installed app walkthrough is not yet verified.

Script Lab edits the project-wide per-frame visual hook in JavaScript or Lua. It is separate from Settings > Scripts, which runs note-editing scripts. Keep a saved project version before changing a working hook.

Use Compile to save the current project text and request validation. Read the diagnostics before relying on the result. Text can remain saved when validation fails or the helper is unavailable.

To remove the hook, empty the editor and use Compile. The reviewed panel has no separate Clear control.

Preview and export have source paths for the frame hook. Execution depends on existing Pro scripting availability, approval for the exact script and language support in the helper. Native behavior remains unverified.

Approve an external client #

Open Settings > External access. The External clients panel lets you name a client, choose permissions, review code and create a grant. Client names are unverified, so identify the program yourself before approval.

Choose only the permissions needed. Read access covers score, pitches, transport and change history. Score editing, transport changes and code execution are separate permissions. Code execution approval applies to the exact loaded code bytes. Changed code needs a new review and grant.

Use Load code for review... when the client needs supplied code. Read the displayed code and selected permissions, check I reviewed this client, every checked permission and any supplied code, then choose Review and create grant.... Read the final confirmation before choosing Create grant. MIDI access needs its own assigned ports. It is not granted by those checkboxes.

Credentials and revocation #

After approval, the app shows a one-time credential. Copy credential sends it to the clipboard. Give it only to the trusted client, then choose Dismiss credential. The app does not save the credential in the project or show it again after dismissal. Clipboard history may retain copied text.

Closing the panel does not revoke access. Choose the client in the local registry and use Revoke selected client to stop its grant. Ordinary grants last for the process. A permanent automation connection approved in a notification survives restart until revoked.

A Permanent connection request has Approve permanent connection and Deny controls. Permanent full automation grants broad command, code, project, file and UI access. Review full legacy automation access... is also separate from the scoped permissions. Treat either flow as full trust in that client. A scoped or controller grant is not full automation approval.

If approval or revocation cannot be saved, follow the reported storage error. Do not assume that a dismissed notification, a closed panel or a network connection proves that access was approved or revoked.

Export destinations #

Detached export writing needs a client export permission and a separately approved directory. Choose the selected client, then Approve export directory.... The app returns a destination grant handle for that client. Copy destination grant handle passes that reference to the client; the app keeps the native path.

Revoking the client denies later publication to that destination. A client credential alone is not permission to write to every folder. Use the app approval controls instead of changing project files to grant access.

Working with API results #

Read-only score snapshots and resolved-pitch queries describe the committed project. A client should use the current API information, capabilities and target addresses when preparing edits. Unsupported commands or missing permissions return errors. Do not treat a connection as proof that an edit committed.

External automation and local scripting do not expand Free into Pro authoring authority. Add-on presence, runtime availability and feature entitlement still apply. This draft describes the approval workflow, not a complete API protocol reference or a native acceptance result.

Note automation operations #

This reference describes 33 dedicated note-editing tools. Their native workflows remain UNVERIFIED. The tool contracts have been reviewed, but this draft does not establish successful edits, playback or Undo on an installed build. Existing Free and Pro requirements still apply. A listed tool is not a Free entitlement.

Targets and shared defaults #

Each dedicated tool accepts targetScope as selection or all, defaulting to selection, and mode as preview or apply, defaulting to apply. Optional noteIds must contain between 1 and 16384 IDs. Supplying noteIds together with targetScope all is rejected. Selection uses the external-client note selection.

Target support varies. Arpeggio, Ratchet, Subdivide and Voicing Spread can resolve editable MIDI-clip occurrences and note-loop owners. Auto Chord, Perfect Harmony and Root Path Tune accept timeline notes including clip notes. The other tools here operate on freeform notes and reject explicit clip-note IDs. Quantize, Legato and Transpose also reject all scope when clip notes exist, rather than editing only part of that scope.

Preview and apply #

API preview is separate from a native transform dialog preview. Arpeggio, Ratchet, Subdivide and Voicing Spread prepare a candidate preview without committing it. Auto Chord, Perfect Harmony, Root Path Tune and versioned Transpose support planner previews. Quantize, Legato, Humanize and Set Velocity have read-only previews. The remaining dedicated operations reject preview with transform.preview.unsupported.

The shared transform registry has nine entries, including Tonal Guidance and Convert to 12-TET. This dedicated-tool reference covers its listed operations; registry membership does not establish another supported API request. Registration also does not mean every Apply request uses the same path as Preview. Humanize and Set Velocity retain separate Apply paths; do not infer identical results or one atomic Undo transaction for every operation.

Auto Chord preview requires Pro expert access. Root Path Tune custom expert parameters also require Pro. This reference does not replace the licensing guide or describe new client approval steps.

Raw batch compatibility requests #

The raw batch_transform tool has a shared compatibility schema rather than a dedicated schema for each transform. Omitted noteIds and targetScope target all notes, unlike the dedicated tools' selection default. Its advertised schema omits targetScope and mode. Do not rely on dedicated defaults, bounds or preview validation when using this older request format.

The dedicated tool join_notes corresponds to the raw transform name join. Parameter differences for Mute, Quantize, Scale Velocity, Set Track, Set Velocity and Staccato appear below.

articulation_humanizer #

Vary note timing, velocity and duration using a preset and seed.

API preview is unsupported for this operation.

Dedicated API fields: preset is Piano, Strings, Guitar, Drums or Winds (default Piano); seed is an integer from 0 through 4294967295 (default 678679).

  • Operation parameters: preset, seed.

arpeggio #

Turn the target phrase into an arpeggio. The result includes the generated note IDs.

API preview is supported. Read the preview and apply distinctions above before using it.

Dedicated API: pattern is up, down, up_down, down_up or random (default up); rateBeats must be positive (default 0.5); gate must be greater than 0 and at most 1 (default 0.8); seed is optional uint32 and defaults effectively to 0.

  • Operation parameters: pattern, rateBeats, gate, seed.

auto_chord #

Generate just-intonation chord voices and harmonic links from guide notes.

Planner preview requires Pro expert access. Native Auto Chord controls are a separate workflow whose current behavior remains unverified here.

API preview is supported. Read the preview and apply distinctions above before using it.

An unconfigured Apply uses the Free factory request. API preview or any operation-specific configured option, including deterministicSeed, requires Pro expert access. Auto Chord requires the enabled Harmonic Tuning workspace and is unavailable in effective 12-TET.

  • Parameter names: minZoneBeats, maxZoneBeats, preferredZoneBeats, onsetGroupingToleranceBeats, onsetBoundaryWeight, releaseBoundaryWeight, pitchSetChangeBoundaryWeight, segmentationVariation, minVoicesPerZone, maxVoicesPerZone.
  • Parameter names: primeLimit, localTenneyCeiling, simultaneousTenneyCeiling, transitionTenneyMinimum, transitionTenneyCeiling, maxChordSpanCents, maxResidualCents, maxParentsPerNote, parentAgreementCents, minTemporalLinksPerBoundary.
  • Parameter names: maxTemporalLinksPerBoundary, temporalLinkMaxGapBeats, commonToneReachBeats, voiceLeadingStrength, maxCandidateFamiliesPerZone, maxGraphStatesPerZone, globalBeamWidth, considerLoopTransition, adventure, lowestGeneratedMidi.
  • Parameter names: highestGeneratedMidi, registerCenterMidi, outputTrackId, gate, releaseTailBeats, linkPolicy, boundaryOverrides, lockedZoneStableIds, referenceOnlyZoneStableIds, zoneRegenerationOrdinals.
  • Parameter names: deterministicSeed.

bow_split #

Split long notes according to a bow budget scaled by velocity, carrying expression into the segments.

API preview is unsupported for this operation.

Dedicated API bounds/defaults: budget is positive and at most 128 (default 4); refVelocity is positive and at most 127 (default 80); minSegment is positive and at most 64 (default 0.2); gap is 0 through 16 (default 0).

  • Operation parameters: budget, refVelocity, minSegment, gap.

consolidate #

Combine nearby notes of the same pitch when their grouping and links permit it.

API preview is unsupported for this operation.

Dedicated API: maxGapBeats is finite and nonnegative (default 0.25; no upper bound); distance is end_start or start_start (default end_start); crossMasters defaults false; includeUnlinked defaults true. The editor dialog caps Max Gap (beats) at 4.

  • Operation parameters: maxGapBeats, distance, crossMasters, includeUnlinked.

double_length #

Double durations and onset distances from the earliest target start.

API preview is unsupported for this operation.

  • No operation-specific parameters. Use the shared target and mode fields.

euclidean #

Place existing starts on Euclidean pulses. Keep the note count, pitches, durations, velocities and tuning offsets.

API preview is unsupported for this operation.

Dedicated API defaults to 8 steps, 5 pulses and rotation 0; steps are integers 1..64, pulses integers 0..64 and cannot exceed steps, and rotation is an integer from -4096 through 4096. The native dialog exposes narrower bounds.

  • Operation parameters: steps, pulses, rotation.

flam #

Add grace notes before each target note.

API preview is unsupported for this operation.

Dedicated API defaults to flamOffsetBeats 0.0625 beats, rollCount 1 and graceVelocityScale 0.6. flamOffsetBeats must be greater than 0 and at most 16; rollCount is an integer 1..16; graceVelocityScale is 0.01..1. The editor dialog has narrower limits.

  • Operation parameters: flamOffsetBeats, rollCount, graceVelocityScale.

generative #

Create harmonic overtones, Euclidean patterns or stochastic notes.

API preview is unsupported for this operation.

generationMode is required and accepts harmonic, euclidean or stochastic. harmonic adds linked overtones and retains the source notes. euclidean and stochastic delete the selected source notes and generate replacements. Keep a saved project version before applying a replacement mode.

  • generationMode selects harmonic, euclidean or stochastic.
  • harmonic parameters: maxHarmonic, velocityFalloff, noteLengthBeats.
  • euclidean parameters: steps, pulses, rotation, stepSizeBeats, gate.
  • stochastic parameters: probability, steps, stepSizeBeats, velocityMin, velocityMax, gate, seed.

ghost #

Add quieter notes before or after targets on grid positions, skipping occupied positions.

API preview is unsupported for this operation.

Dedicated API defaults to grid 0.25, velocityScale 0.35 and placement both. grid must be positive and at most 16; velocityScale is 0.01..1; placement is anticipation, followup or both.

  • Operation parameters: grid, velocityScale, placement.

groove #

Take timing and velocity deviations from reference notes and apply that groove to the targets.

API preview is unsupported for this operation.

Dedicated API requires referenceNoteIds, a list of 1..16384 nonnegative note IDs. grid must be positive and at most 16 (default 0.25); strength is 0..1 (default 1); applyTiming and applyVelocity both default true. The native dialog uses built-in Swing, Laid Back and Push feels on a fixed 16th-note grid instead of reference IDs.

  • Operation parameters: referenceNoteIds, grid, strength, applyTiming, applyVelocity.

halve_length #

Halve durations and onset distances from the earliest target start. The resulting duration has a minimum of 0.01 beats.

API preview is unsupported for this operation.

  • No operation-specific parameters. Use the shared target and mode fields.

humanize #

Add seeded variation to timing, velocity and duration. preserveRhythm keeps note starts unchanged.

API preview is supported. Read the preview and apply distinctions above before using it.

Dedicated API fields: timing is 0..0.1 (default 0.02), velocity 0..30 (default 10), length 0..20 (default 5), preserveRhythm defaults false, and optional seed is uint32. If seed is omitted, Apply generates one from the system random source. The API preview is read-only; the native dialog has a separate planner path and clip-repeat controls.

  • Operation parameters: timing, velocity, length, preserveRhythm, seed.

join_notes #

Join a compatible run into one note with pitch bends.

API preview is unsupported for this operation.

Join requires at least two target notes in the same note owner and track. It rejects simultaneous onsets and onsets separated by no more than 0.0001 beats. The dedicated API operates on freeform notes; native selected clip preparation is a separate workflow.

  • No operation-specific parameters. Use the shared target and mode fields.

legato #

Extend each group of simultaneous target starts to the next distinct target start on the same track, regardless of pitch. The final start group stays unchanged. Note-loop targets are unsupported for this operation.

API preview is supported. Read the preview and apply distinctions above before using it.

  • No operation-specific parameters. Use the shared target and mode fields.

merge_notes #

Combine same-track, same-pitch notes. Keep the earliest note ID, join the lyrics and remove the later notes.

API preview is unsupported for this operation.

Selected same-track, same-pitch notes need not be adjacent in time. The merged note spans from the earliest start to latest end; the operation keeps the earliest note ID, joins nonempty lyrics and clears phoneme data.

  • No operation-specific parameters. Use the shared target and mode fields.

mute #

Set the mute state of each target.

muted is an optional boolean and defaults to true. This sets a state; it does not toggle. The raw compatibility request also uses true when omitted.

API preview is unsupported for this operation.

  • Operation parameters: muted.

perfect_harmony #

Build a deterministic just-intonation link graph and return graph measurements.

API preview is supported. Read the preview and apply distinctions above before using it.

Supplying any operation-specific Perfect Harmony option requires Pro expert access. Omit those options to use the default action. The dedicated tool accepts primeLimit from 2 to 43, maxParentsPerNote from 1 to 64 and maxTemporalLinksPerZoneBoundary from 0 to 64. The planner uses effective ranges of 3 to 11, 1 to 12 and 0 to 4 respectively.

  • Operation parameters: primeLimit, tenneyCeiling, maxResidualCents, maxScanDistanceBeats, nearOverlapBeats, maxParentsPerNote, redundantParentAgreementCents, connectTemporalZones, temporalZoneMaxGapBeats, maxTemporalLinksPerZoneBoundary, linkCommonTones, commonToneReachBeats.

quantize #

Snap target starts to a beat grid. Structured Advanced Quantize uses a separate versioned request.

grid is required, finite and greater than zero. The dedicated tool caps it at 1024. The raw compatibility request and core transform require a positive grid without that upper limit; omission is an error.

API preview is supported. Read the preview and apply distinctions above before using it.

The editor toolbar uses the active performance grid. The dedicated API tool requires an explicit grid duration in beats.

  • Operation parameters: grid.

Structured Advanced Quantize request #

Use batch_transform with transform set to quantize for structured Advanced Quantize. This versioned request is separate from note_quantize and the basic grid request above. It requires Advanced Transforms & Groove to be enabled and available, plus Pro Advanced Quantize authoring authority.

This route applies immediately and has no API preview. The Advanced Quantize dialog has its own preview. Do not send mode, targetScope or parameters, or combine this request with grid or noteIds.

Target identities and captured times must match the current project. A request that passes field validation can still be rejected when it no longer matches. The operation captures meter and the current groove from the project.

Results report status as applied, no_op or rejected, with counters, diagnostics and remaps. Errors can occur before structured execution. These instructions are source-reviewed; native workflows remain unverified.

  • Required fields: transform set to quantize, schemaVersion set to the integer 1, and targets containing 1 to 16384 targets.
  • Allowed top-level fields: transform, schemaVersion, targets, divisionOfBeatUnit, phaseOfBeatUnit, direction, strength, edges, gridSource, collisionPolicy and minimumLength. Unknown or incompatible fields are rejected.
  • Rational fields use objects with integer numerator and denominator. divisionOfBeatUnit and minimumLength must be positive valid rationals; phaseOfBeatUnit must be a valid rational. Defaults are division 1/4 beat unit, phase 0 and minimum length 1/960.
  • direction accepts nearest, earlier or later, default nearest. strength must be a finite number from 0 to 1, default 1. edges accepts starts, ends or both, default starts.
  • gridSource accepts straight or current_groove, default straight. collisionPolicy accepts allow_overlap, clamp_next_onset or preserve_order, default allow_overlap.
  • Every target requires kind, trackId as an integer from 0 to 255, capturedStartBeat as a finite number at least 0, and capturedEndBeat as a finite number greater than capturedStartBeat.
  • A freeform target also requires noteId as a nonnegative integer. A clip_note_instance target also requires clipId, clipNoteId and repeatIndex as nonnegative integers. Targets reject unknown or incompatible fields.

ratchet #

Split notes into equal-duration repetitions with velocity decay.

API preview is supported. Read the preview and apply distinctions above before using it.

count is an integer from 1 to 64, default 4. velocityDecay is from 0 to 1, default 0. Ratchet uses equal full-note divisions with midpoint skew. The native editor exposes the related Subdivide controls rather than a separate Ratchet action.

  • Operation parameters: count, velocityDecay.

reverse #

Mirror target positions within the span of the targets. Durations stay unchanged.

API preview is unsupported for this operation.

  • No operation-specific parameters. Use the shared target and mode fields.

riff_machine #

Create a seeded riff after the target phrase using its pitches.

API preview is unsupported for this operation.

density is from 0 to 1, default 0.6; length is greater than 0 through 4096 beats, default 4. seed is a signed 32-bit integer, default 12345. grid is greater than 0 through 64 beats, default 0.25. The generator uses a grid of at least 0.01 beats and a length of at least both 0.25 beats and that grid.

The native dialog uses density from 0.1 to 1 and length from 1 to 16 beats. It does not expose the API grid field. Its dialog preview is separate from API preview.

  • Operation parameters: density, length, seed, grid.

root_path_tune #

Choose a harmonic root path and optionally link its root chain.

Custom expert parameters require Pro. Preview is available through the optimizer; this reference does not promise transaction-wide rollback.

API preview is supported. Read the preview and apply distinctions above before using it.

  • Parameter names: chordPurity, internalVoice, driftGuard, driftReach, commonTone, repeatGapBeats, unisonLock, virtualRoots, includeNeighborRootCandidates, onsetThreshold.
  • Parameter names: analysisQuantizeGridBeats, contextRadius, neighborCandidateRadius, transitionWeight, rootChangePenalty, shortFrameRootPenalty, shortFrameBeatThreshold, virtualRootStartPenalty, shortFrameVirtualRootStartPenalty, weakBeatVirtualRootStartPenalty.
  • Parameter names: weakBeatRootChangeEpsilonBeats, rootEvidenceLookbackBeats, rootEvidenceLookaheadBeats, rootEvidenceNeighborWeight, enableBoundaryMergeRefinement, minimumBoundaryGain, boundaryMergeDriftWeight, maxBoundaryMergeDriftCents, maxBoundaryMergeSpanBeats, maxBoundaryMergeOwnedNotes.
  • Parameter names: enableHarmonicZoneSpanSearch, maxHarmonicZoneSpanFrames, maxHarmonicZoneSpanBeats, maxHarmonicZoneBoundaryDriftCents, matchComplexityWeight, chordTemplateFitWeight, boundaryOnsetWeight, boundaryTransitionEaseWeight, sameRootBoundarySoftPenalty, sameRootBoundaryStrongPenalty.
  • Parameter names: sameRootBoundaryStrongThreshold, contextFirstNeighborWeight, contextSecondNeighborWeight, internalIntervalMeanWeight, internalIntervalMaxWeight, internalIntervalOutlierThresholdCents, internalIntervalOutlierWeight, samePitchUnisonWeight, samePitchUnisonOutlierThresholdCents, samePitchUnisonOutlierWeight.
  • Parameter names: frameDurationWeightReferenceBeats, frameDurationWeightPower, frameDecisionWeightFloor, frameDecisionWeightCeiling, frameVelocityWeight, linkRootChain, maxChainStatesPerFrame, internalIntervalPreservationWeight, internalHarmonicFitWeight, internalHarmonicDistanceWeight.
  • Parameter names: internalHarmonicMaxWeight, harmonicDistanceUnisonWeight, harmonicRootConsonanceRewardWeight, onsetRootConsonanceRewardWeight, triadRootEvidenceRewardWeight, harmonicRootConsonanceFitToleranceCents, harmonicRootConsonanceActiveRootBonus, harmonicRootConsonanceWorstTenneyHeight, harmonicRootConsonanceHeightPower, commonToneShiftWeight.
  • Parameter names: commonToneShiftOutlierThresholdCents, commonToneShiftOutlierWeight, repeatedPitchContinuityMaxGapBeats, repeatedPitchContinuityWeight, repeatedPitchContinuityOutlierThresholdCents, repeatedPitchContinuityOutlierWeight, heldNoteRetuneWeight, heldNoteRetuneOutlierThresholdCents, heldNoteRetuneOutlierWeight, antiDriftAdjacentZoneRadius.
  • Parameter names: scopeVirtualRootsToHarmonicZones, virtualRootZoneBoundaryThreshold, synthesizeVirtualRoots.

scale_velocity #

Multiply velocities and clamp the resulting values to 1 through 127.

factor is optional, finite and between 0 and 16 inclusive, defaulting to 1. The raw compatibility request does not enforce these bounds or the dedicated finite check; its omitted factor is 1. A final velocity clamp does not validate the factor.

API preview is unsupported for this operation.

  • Operation parameters: factor.

set_track #

Move targets to a track that exists in the project.

trackId is required and must be an integer from 0 through 255 that identifies a current project track. The raw compatibility request allows omission and then tries track 0, which must still exist.

API preview is unsupported for this operation.

  • Operation parameters: trackId.

set_velocity #

Give every target the same velocity.

velocity is required and must be an integer from 1 through 127. The raw compatibility schema accepts a broader numeric field, but the command rejects fractional values and uses 100 when omitted.

API preview is supported. Read the preview and apply distinctions above before using it.

  • Operation parameters: velocity.

split_sentence #

Split lyric notes and distribute their durations using equal, syllable or phoneme weights.

API preview is unsupported for this operation.

distribution defaults to syllable. In the current operation, syllable and phoneme both weight each word by its phonemizer token count. equal gives every word the same weight. Only multi-word lyric notes are split.

  • Operation parameters: distribution.

staccato #

Scale note durations, with a minimum resulting duration of 0.01 beats.

factor is optional, finite and between 0 and 1 inclusive, defaulting to 0.5. The raw compatibility request also defaults to 0.5, but does not enforce the dedicated bounds or finite check. Its 0.01-beat minimum applies to the resulting duration.

API preview is unsupported for this operation.

  • Operation parameters: factor.

strum #

Offset simultaneous chord notes by pitch, with controls for spread, easing, velocity and shortening.

API preview is unsupported for this operation.

direction accepts up, down, alternate or random, default up. The editor labels these Up, Down, Alt and Rnd. spread is from 0.01 to 2, default 0.1; ease and velocity are from -100 to 100, default 0; humanize is from 0 to 100, default 0. shorten defaults to false.

The native Strum toolbar appears with at least two selected notes when Advanced Transforms & Groove is active. Its dialog preview is separate from API preview.

  • Operation parameters: direction, spread, ease, velocity, humanize, shorten, seed.

subdivide #

Split notes using division, length, skew and velocity-decay controls.

API preview is supported. Read the preview and apply distinctions above before using it.

divisions is an integer from 2 to 64, default 4. lengthPct is from 1 to 100, default 100; skew is from 0 to 100, default 50; velocityDecay is from 0 to 1, default 0. The native dialog limits Divisions to 2 through 16 and starts at 2.

  • Operation parameters: divisions, lengthPct, skew, velocityDecay.

swing #

Write swing-grid displacement into note starts.

API preview is unsupported for this operation.

division is an optional integer from 1 to 64; grid is optional and greater than 0 through 64 beats. amount is from 0 to 1 and defaults to 0.5 in the dedicated API tool. Omitted division and grid derive from the project swing division and beat denominator.

The native editor action reads the stored swing amount and division, with a zero amount falling back to 50%. Its toolbar requires Advanced Transforms & Groove.

  • Operation parameters: division, grid, amount.

transpose #

Shift pitches using the versioned semitone, cent, EDO or ratio specification. The raw compatibility request also accepts legacy integer semitones.

API preview is supported. Read the preview and apply distinctions above before using it.

version defaults to 1 and unit is required. semitones, cents and edo_steps require amount; edo_steps requires an integer amount. edoDivisions accepts an integer from 1 to 1200 and uses the project EDO divisions when omitted. ratio requires positive integer ratioNumerator and ratioDenominator and does not accept amount.

octave defaults to 0, graphPolicy to component, and rangePolicy to reject. graphPolicy also accepts selection_reanchor and detach_boundary. EDO, ratio and non-component graph policies require Harmonic Tuning authority. The raw legacy semitone request retains separate compatibility behavior.

  • Operation parameters: version, unit, amount, edoDivisions, ratioNumerator, ratioDenominator, octave, graphPolicy, rangePolicy.

voicing_spread #

Spread chord voicings across a register, optionally adding voices.

API preview is supported. Read the preview and apply distinctions above before using it.

spread is an integer from 1 to 24, default 4; octaves is an integer from 1 to 8, default 2; octaveTranspose is an integer from -4 to 4, default 0. allowExtraNotes defaults to true. The native toolbar appears with at least two selected notes when Advanced Transforms & Groove is active.

  • Operation parameters: spread, octaves, octaveTranspose, allowExtraNotes.