Apply beat-aware velocity accents to notes based on their position.

Unlike apply_velocity_pattern (which cycles by note index), this determines accent strength from each note's beat position — downbeats get strong, off-beats get weak. This is how real drummers and musicians play.

Accent patterns:

• "4/4" — beat 1 strong, 2 medium, 3 medium, 4 weak (classic rock/pop)

• "backbeat" — beats 1+3 medium, 2+4 strong (rock, funk, soul)

• "3/4" — beat 1 strong, 2 weak, 3 medium (waltz)

• "6/8" — beats 1+4 strong, others weak (compound duple)

• "off_beat" — downbeats weak, off-beats strong (syncopated, reggae skank)

• "four_on_floor" — every quarter strong (house, techno)

Notes that fall on exact beat boundaries get accent levels. Notes between beats (e.g. 16th notes) get interpolated: closer to a strong beat → higher.

Use cases:

• Make drum patterns feel groovy instead of flat

• Add natural dynamics to programmed basslines

• Emphasise downbeats in chord stabs

• Create backbeat feel on snare/hihat

unit_index: AU index. track_index: Note track index. accent_pattern: Beat accent scheme (4/4, backbeat, 3/4, 6/8, off_beat, four_on_floor). strong_velocity: Velocity for strong beats (0-1). medium_velocity: Velocity for medium beats (0-1). weak_velocity: Velocity for weak beats (0-1). region_index: Region (-1 = first region).

Returns count of notes accented and per-level breakdown.

Example:

Backbeat feel — accent beats 2 and 4

accent_beats(0, 0, "backbeat", strong_velocity=1.0, weak_velocity=0.5)

Four-on-the-floor — every beat loud

accent_beats(0, 0, "four_on_floor", strong_velocity=0.95)

Add anticipation notes before strong-beat notes.

Anticipation is the fourth classic non-chord tone technique: a note that arrives early — on the weak part of the beat before a strong beat — anticipating the pitch of the upcoming note. This creates forward rhythmic motion and is ubiquitous in jazz, pop, and Latin music.

Unlike passing tones (which connect two different pitches stepwise), suspensions (which hold a note into the next chord), and neighbor tones (which ornament a single note), anticipation reaches forward to the next melodic/harmonic goal before the beat arrives.

Structure: [original note shortened] → [anticipation on weak beat] → [strong beat note]

The tool finds notes on strong beats (integer beat positions) and inserts an anticipation note just before them. The anticipation has the same pitch as the target note (or a related scale tone if direction is set), placed on the weak portion of the beat.

Jazz syncopation, pop vocal anticipations, salsa montuno, and funk guitar stabs all rely on this device.

Args: unit_index: Audio unit index track_index: Note track index region_index: Region index (-1 = first region) scale: Scale for anticipation pitch selection ("major", "minor", "dorian", "phrygian", "lydian", "mixolydian", "locrian", "harmonic_minor", "melodic_minor", "pentatonic", "blues", "chromatic") root: Root note for scale (C, C#, D, ... B) anticipation_offset: How early the anticipation arrives, in beats before the strong beat (0.0625-0.5, default 0.25 = sixteenth note before). Smaller = more subtle, larger = more pronounced. anticipation_fraction: Duration of anticipation as fraction of the offset gap (0.1-1.0, default 0.33). Controls how long the anticipation note lasts relative to the gap before the strong beat. anticipation_velocity: Velocity of anticipation note (0-1, default 0.55 — softer than the main note, as it is on a weak beat). direction: Anticipation pitch direction — "auto": same pitch as target note (classic anticipation) "upper": one scale step above target "lower": one scale step below target "approach": scale step approaching target from the direction of the previous note min_duration_beats: Minimum note duration in beats to qualify (0.5-4.0, default 1.5). Ensures the target note is long enough to anticipate meaningfully. cross_track: If >= 0, place anticipations on this track index instead of source track (preserves original notes).

Add parameter automation to an effect on an audio unit.

Creates an automation track + value clip + value events. Automation points control the parameter over time.

unit_index: Audio unit index. effect_index: Effect position in the chain. parameter_name: Parameter to automate (e.g. "cutoff", "volume", "mix"). points: JSON array of [position_beats, value_0_to_1] pairs. Example: "[[0, 0.5], [4, 1.0], [8, 0.5]]"

The parameter must be automatable (Field<Pointers.Automation>).

Add a ready-made bass processing chain to an audio unit — EQ → Compressor (+ optional Waveshaper drive).

One call replaces 2-3 individual add_effect + set_effect_parameter calls. Designed for bass tracks but works on any low-frequency content.

unit_index: Target audio unit (the bass track). style: Preset character:

• "deep" — sub boost, slow comp, thick low end (hip-hop, trap, 808s)

• "round" — low-mid warmth, gentle comp (R&B, jazz, soul)

• "driven" — low cut, mid boost, comp + drive (rock, punk bass)

• "clean" — transparent, minimal coloration (electronic, house)

• "tight" — fast comp, controlled, punchy (disco, funk, pop)

drive_amount: Waveshaper saturation (0-1, default 0 = off). Use 0.2-0.5 for grit.

Creates: Revamp EQ → Compressor (→ Waveshaper) on the target AU. Returns effect indices and parameter values set.

Example:

Deep sub bass chain

add_bass_chain(0)

Driven rock bass with grit

add_bass_chain(0, style="driven", drive_amount=0.4)

Clean electronic bass

add_bass_chain(0, style="clean")

Add a tension/extension note to an existing chord — jazz harmony.

Adds an extension note (9th, 11th, 13th, or alterations) to a chord already on the timeline. This is how triads become jazz chords — stack a 9th on a C major triad and it becomes Cmaj9, add a b13 to a G7 and it becomes G7b13. The extension is calculated from the chord root, so you don't need to know the exact pitch.

extension: The tension note to add:

• "9" — major 9th (2 semitones above root, +14 from root). Adds color and warmth. C → D. The most common jazz extension.

• "b9" — minor 9th (1 semitone above root, +13). Dark, tense. Dominant chords in minor keys, flamenco, film scores. C → Db.

• "#9" — augmented 9th (3 semitones, +15). The Hendrix chord sound. Bluesy, gritty. C → D#.

• "11" — perfect 11th (5 semitones above root, +17). Suspended, open. C → F. Can clash with 3rd — use carefully.

• "#11" — augmented 11th (6 semitones, +18). Lydian sound. Dreamy, floating. C → F#. Common in modal jazz.

• "13" — major 13th (9 semitones above root, +21). Full, rich. The ultimate jazz extension. C → A. Adds completeness.

• "b13" — minor 13th (8 semitones, +20). Dark, dramatic. Minor key dominants. C → Ab. Spanish/orchestral feel.

chord_position: Beat position of the chord (finds root = lowest note). octave: Which octave to place the extension in (3-7, default 5). Higher = more color, lower = more grounded. velocity: Velocity of the added note (0-1, default 0.6 = subtle).

Returns root pitch, extension pitch, extension name, chord size.

Example:

Add 9th to first chord — Cmaj → Cmaj9

add_chord_tension(0, 2, 0, 0.0, extension="9")

Add b13 for dark dominant — G7 → G7b13

add_chord_tension(0, 2, 0, 4.0, extension="b13")

Add a ready-made drum processing chain to an audio unit — Gate → EQ → Compressor (+ optional Reverb).

One call replaces 3-4 individual add_effect + set_effect_parameter calls. Designed for drum tracks but works on any rhythmic content.

unit_index: Target audio unit (the drum track). style: Preset character:

• "punchy" — tight gate, bright EQ, fast comp (pop, rock drums)

• "deep" — loose gate, sub boost, slow comp (hip-hop, trap, 808s)

• "crisp" — bright EQ, fast attack comp (techno, house, electronic)

• "roomy" — medium gate, warm EQ, lush reverb (rock, live drums)

• "tight" — transparent, just cleanup (jazz, acoustic, lofi)

reverb_amount: Reverb wet/dry (0-1, default 0 = off). Use 0.1-0.3 for room sound.

Creates: Gate → Revamp EQ → Compressor (→ Reverb) on the target AU. Returns effect indices and parameter values set.

Example:

Punchy drum chain on track 0

add_drum_chain(0)

Deep 808 chain

add_drum_chain(0, style="deep")

Roomy rock drums with reverb

add_drum_chain(0, style="roomy", reverb_amount=0.25)

Add an audio effect to an audio unit's effect chain.

effect_type: One of the audio effect names from mcp_opendaw_list_effects: Compressor, Crusher, DattorroReverb, Delay, Fold, Gate, Maximizer, NeuralAmp (Tone3000), Reverb, Revamp, StereoTool, Tidal, Vocoder, Waveshaper, Werkstatt

Returns effect_index — use it with mcp_opendaw_set_effect_parameter.

Automate a parameter on the instrument connected to an audio unit.

Works with any automatable instrument field: Vaporisateur (cutoff, resonance, volume, etc), Playfield sample mute, Tape flutter/wow, Nano volume/release, and more.

For Playfield sample-level params (mute, volume, pan, etc), set sample_index to the sample slot index (0-based). For top-level instrument params, leave sample_index as -1.

unit_index: Audio unit index containing the instrument. parameter_name: Field name to automate (e.g. "cutoff", "mute", "flutter"). points: JSON array of [position_beats, value] pairs. Example: "[[0, 0.5], [4, 1.0]]" sample_index: For Playfield, which sample slot to target (-1 = top-level instrument field).

Returns automation track info and number of events created.

Add a ready-made instrument processing chain — EQ → Compressor → Reverb (+ optional Delay).

Universal chain for guitars, keys, synth leads, strings, pads — any melodic/harmonic instrument. One call replaces 3-4 individual add_effect + set_effect_parameter calls.

unit_index: Target audio unit (the instrument track). style: Preset character:

• "clean" — transparent EQ, light comp, subtle reverb (keys, piano, clean guitar)

• "warm" — low-mid warmth, tube-like comp (jazz guitar, Rhodes, warm synths)

• "bright" — air boost, present mids, short reverb (lead guitar, synth lead, pop keys)

• "ambient" — wide EQ, minimal comp, lush reverb (pads, strings, atmospheres)

• "driven" — mid crunch, drive comp, room reverb (rock guitar, aggressive synths)

reverb_amount: Reverb wet/dry (0-1, default 0.15 = subtle). delay_amount: Optional delay wet/dry (0-1, default 0 = off).

Creates: Revamp EQ → Compressor → Reverb (→ Delay) on the target AU. Returns effect indices and parameter values set.

Example:

Clean keys chain

add_instrument_chain(0)

Ambient pad with lush reverb

add_instrument_chain(0, style="ambient", reverb_amount=0.4)

Driven rock guitar

add_instrument_chain(0, style="driven", reverb_amount=0.2)

Synth lead with delay

add_instrument_chain(0, style="bright", delay_amount=0.2)

Add a timeline marker at a position.

Markers label song structure points (Verse, Chorus, Bridge, etc.). Visible on the timeline ruler.

position_beats: Position in beats. label: Marker text (e.g. "Verse 1", "Chorus", "Drop").

Add a ready-made mastering chain to the output bus — EQ + compressor + maximizer in one call.

target_lufs: Target loudness (-14 = Spotify, -16 = Apple, -10 = loud). style: Preset character:

• "balanced" — transparent EQ, gentle comp, clean limiter

• "warm" — low shelf boost, slower comp attack, soft saturation

• "loud" — aggressive comp, fast release, hard limit

• "transparent" — minimal EQ, light comp, true peak limiting

Creates: Revamp EQ → Compressor → Maximizer on the output/master AU. Returns the effect indices and parameter values set.

Add a MIDI effect to an audio unit's MIDI effect chain.

MIDI effects process note data before the instrument. They are chained on au.midiEffects (separate from audio effects on au.audioEffects).

effect_type: One of: Arpeggio, Pitch, Velocity, Zeitgeist, Spielwerk

unit_index: Audio unit index (must be an instrument AU, not output). Returns effect_index in the MIDI chain.

Add a module to a Modular device.

au_index: Audio unit index. effect_index: Effect index within the AU. module_type: One of "gain", "delay", "multiplier", "audio-input", "audio-output". label: Optional label for the module. x, y: Position in the modular editor grid.

Returns the new module's index and info.

Add upper/lower neighbor tones to embellish existing notes.

A neighbor tone is a non-chord tone that steps away from the main note by one scale step (up or down) and then returns. Unlike passing tones which connect two different notes, neighbor tones ornament a single sustained note.

Structure: [main first part] → [neighbor (dissonance)] → [main return]

The original note is split into three parts:

1. First part: original pitch from start to neighbor_offset

2. Neighbor: one scale step away, duration = neighbor_fraction of original

3. Return: original pitch for the remainder

This is the third of the four classic non-chord tone techniques: passing tones, suspensions, neighbor tones, and anticipation.

Bach ornaments, jazz ballad fills, country chicken pickin', and classical cadenzas all use neighbor tones extensively.

Args: unit_index: Audio unit index track_index: Note track index region_index: Region index (-1 = first region) scale: Scale for diatonic neighbor step ("major", "minor", "dorian", "phrygian", "lydian", "mixolydian", "locrian", "harmonic_minor", "melodic_minor", "pentatonic", "blues", "chromatic") root: Root note for scale (C, C#, D, ... B) direction: Neighbor direction — "upper": step up from main note (most common) "lower": step down from main note "alternating": alternate upper/lower per note neighbor_fraction: Duration of neighbor as fraction of original note (0.1-0.5, default 0.25 = quarter of original). Smaller values create subtle ornaments, larger create more prominent embellishments. neighbor_offset: Position of neighbor within the note (0.1-0.9, default 0.5 = middle). 0.15 = near start, 0.5 = middle, 0.85 = near end. neighbor_velocity: Velocity of neighbor note (0-1, default 0.6 — softer than the main note, as is traditional for ornaments). min_duration_beats: Minimum note duration in beats to embellish (0.5-4.0, default 1.0). Short notes are skipped — ornaments need room to breathe. cross_track: If >= 0, place neighbors on this track index instead of source track (preserves original notes).

Add passing tones between existing notes for smoother melodic lines.

Inserting diatonic passing tones in gaps where consecutive notes have an interval larger than a 2nd. The passing tone is placed on the weak part of the beat, connecting the two notes stepwise through the scale.

This is a fundamental counterpoint technique — makes large melodic leaps sound smoother by filling them with scale steps. Bach inventions, jazz walking lines, and pop vocal melismas all use passing tones.

Passing tones are only added when:

• The interval between consecutive notes is > 2 semitones

• There is enough time gap between notes (at least 1/8 note)

• The interval does not exceed max_interval semitones

Args: unit_index: Audio unit index track_index: Note track index region_index: Region index (-1 = first region) scale: Scale for diatonic passing tones ("major", "minor", "dorian", "phrygian", "lydian", "mixolydian", "locrian", "harmonic_minor", "melodic_minor", "pentatonic", "blues", "chromatic") root: Root note for scale (C, C#, D, ... B) max_interval: Maximum interval (semitones) to fill with passing tones (3-12, default 7 = perfect 5th). Intervals larger than this are left as leaps. velocity: Velocity of passing tones (0-1, default 0.6 — slightly quieter than melodic notes, as is traditional) duration_fraction: Duration of passing tones as fraction of the gap between notes (0.25-1.0, default 0.5) direction: Passing tone direction — "auto": choose direction that fits scale better "ascending": always step up from lower to higher note "descending": always step down from higher to lower note "nearest": use nearest scale tone to midpoint cross_track: If >= 0, place passing tones on this track index instead of source track (preserves original melody)

Add a time signature change at a specific position in the track.

Unlike set_time_signature (which sets the global default), this creates a SignatureEventBox on the timeline's signature track, allowing time signature changes mid-track (e.g. 4/4 → 3/4 → 4/4).

position_beats: Position in beats where the change occurs. numerator: Number of beats per bar (top number). denominator: Note value per beat (bottom number: 4=quarter, 8=eighth).

Returns the created signature event details.

Add suspension-resolutions to existing notes.

A suspension is a non-chord tone technique where a note from the previous chord is held over (suspended) into the next chord on a strong beat, creating dissonance, then resolves by step (usually downward) to a chord tone.

Structure: Preparation (held note) → Suspension (dissonance on strong beat) → Resolution (step down/up to chord tone).

This tool finds notes on strong beats (downbeats) and creates a suspension before them: a preparatory note a step above (or below) the target, held into the strong beat, then resolving to the target note.

This is one of the most expressive devices in Western music — Bach chorales, jazz ballads, film scores all rely on suspensions for emotional tension-release.

Args: unit_index: Audio unit index track_index: Note track index region_index: Region index (-1 = first region) scale: Scale for resolution step ("major", "minor", "dorian", "phrygian", "lydian", "mixolydian", "locrian", "harmonic_minor", "melodic_minor", "chromatic") root: Root note for scale resolution: Resolution direction — "down": resolve downward by step (classic 4-3, 9-8, 7-6 suspension) "up": resolve upward by step (rare, retardation) "both": alternate down/up per note suspension_offset: Semitone offset of suspension from target (1-7, default 2 = step above for down resolution). The suspension is placed this many semitones above (for "down" resolution) or below (for "up" resolution) the target note, then snaps to nearest scale tone. preparation_beats: Duration of the preparation note in beats (0.25-2.0, default 0.5 = eighth note before strong beat). suspension_velocity: Velocity of suspension note (0-1, default 0.75 — slightly accented, it is on a strong beat). resolution_velocity: Velocity of resolution note (0-1, default 0.65 — resolution is typically softer). cross_track: If >= 0, place suspensions on this track index instead of source track (preserves original melody).

Add a tempo (BPM) change at a specific position in the track.

Creates a ValueEventBox on the timeline's tempo track, allowing BPM automation mid-track (e.g. 120 BPM → 90 BPM → 140 BPM).

The tempo track uses normalized values (0..1) mapped to minBpm..maxBpm (default 60..240). This tool handles the conversion automatically.

position_beats: Position in beats where the tempo change occurs. bpm: Target BPM (60-240). interpolation: 'linear' for smooth transition, 'hold' for instant jump.

Returns the created tempo event and full tempo map.

Add a ready-made vocal processing chain to an audio unit — EQ + compressor + reverb (+ optional delay).

One call replaces 3-4 individual add_effect + set_effect_parameter calls. Designed for vocal tracks but works on any melodic content.

unit_index: Target audio unit (the vocal track). style: Preset character:

• "balanced" — transparent EQ, gentle comp, medium reverb (pop)

• "warm" — low-mid warmth, slower comp, lush reverb (R&B, soul)

• "bright" — air boost, fast comp, short reverb (pop, radio)

• "intimate" — minimal EQ, light comp, small room (ballad, acoustic)

• "aggressive" — presence boost, hard comp, plate reverb (rock, rap)

reverb_amount: Reverb wet/dry (0-1, default 0.25 = subtle). delay_amount: Optional slap delay wet/dry (0-1, default 0 = off).

Creates: Revamp EQ → Compressor → Reverb (→ Delay) on the target AU. Returns effect indices and parameter values set.

Example:

Balanced vocal chain on track 0

add_vocal_chain(0)

Warm R&B vocal with lush reverb

add_vocal_chain(0, style="warm", reverb_amount=0.35)

Pop vocal with slap delay

add_vocal_chain(0, style="bright", delay_amount=0.15)

Dynamics analysis — crest factor, loudness range, transient density, segment RMS.

Measures the dynamic character of a track:

• crest_factor_db: Peak/RMS ratio in dB (high = dynamic, low = compressed/squashed)

• loudness_range_db: LRA — 95th-10th percentile of short-term RMS (high = varied dynamics)

• dynamic_range_db: max-min window RMS (total loudness variation)

• transient_density: energy spikes per second (high = percussive/transient-rich)

• segment_variation_db: RMS variation across 10 segments of the track

• segments: per-segment RMS (dB) with time positions

Compression decision guidance:

• crest_factor < 6 dB → heavily compressed, low headroom

• crest_factor > 15 dB → very dynamic, may need compression

• loudness_range < 4 dB → flat/squashed, lacks dynamic interest

• loudness_range > 12 dB → very dynamic, may need leveling

• transient_density > 10 → percussive/transient-heavy content

• segment_variation > 6 dB → significant level changes between sections

Args: filename: Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.

Returns dynamics descriptors, 10-segment RMS contour, and compression suggestions.

Analyze harmonic rhythm — how fast chords change and where.

Identifies chords from MIDI notes (same logic as identify_chords), then analyses the rhythm of chord changes:

• Chord change positions: exact beat where each new chord starts

• Chord durations: how long each chord lasts (in beats and bars)

• Harmonic rhythm rate: fast (<2 bars), medium (2-4 bars), slow (>4 bars)

• Harmonic density: chords per bar

• Chord sequence: ordered list of chords with durations

• Stable sections: where harmony stays the same for 4+ bars

• Active sections: where chords change every bar or faster

• Total harmonic events: number of distinct chord changes

This complements identify_chords (which lists chords) by focusing on the temporal pattern of harmony — essential for understanding arrangement, predicting where tension builds, and planning variations.

Use with:

• analyze_song_structure (structure + harmonic rhythm = full form picture)

• reharmonize_progression (know what to reharmonize and where)

• create_arrangement_variation (match or contrast harmonic rhythm)

unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = first, -2 = all regions on track). group_tolerance: Beats of tolerance for grouping notes (default 0.25). min_notes: Minimum notes for chord identification (default 3).

Returns harmonic rhythm analysis with chord timeline and section classification.

Analyze melodic content — contour, intervals, direction, climax.

Returns a detailed melodic analysis of notes in a region:

• Contour profile: direction (up/down/static) for each consecutive interval

• Interval histogram: count of each interval size (semitones)

• Step vs leap ratio: percentage of steps (≤2 semitones) vs leaps (>2)

• Direction changes: how often melody changes direction

• Climax: highest pitch and its position

• Nadir: lowest pitch and its position

• Phrase analysis: groups by rests (gaps > 1 beat) into phrases

• Contour shape classification: ascending/descending/arch/v_shape/wave/static

• Melodic range: semitone span between lowest and highest

• Average interval size

Useful for:

• Understanding a melody before variation/reharmonization

• Comparing melodies (which is more jagged, which more stepwise?)

• Identifying climax placement (is the high point early, middle, late?)

• Feeding analysis to create_motif_variations

• Evaluating AI-generated melodies for contour interest

unit_index: AU index. track_index: Note track index. region_index: Region (-1 = first region).

Returns analysis object.

Example: analysis = analyze_melody(0, 3)

contour_shape, climax_position, step_leap_ratio, interval_histogram

Complete mix diagnosis in one call — combines track + spectrum + stereo + dynamics.

Runs all four analysis modules and synthesizes a single prioritized report:

1. analyze_track: BPM, key, LUFS, duration

2. analyze_spectrum: 7-band frequency balance, spectral centroid, rolloff

3. analyze_stereo: width, L/R balance, phase correlation, mono compat

4. analyze_dynamics: crest factor, LRA, transient density, segment contour

Produces prioritized mix_suggestions (sorted by severity) and a master_check with platform-specific LUFS targets:

• Spotify: -14 LUFS

• Apple Music: -16 LUFS

• YouTube: -14 LUFS

• CD: no target (full dynamics)

The agent can call this single tool instead of 4 separate calls, getting a complete picture for mix decisions: EQ, compression, stereo, mastering.

Args: filename: Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.

Returns combined analysis + prioritized suggestions + master check.

Per-band phase analysis — coherence, polarity, inter-channel delay.

Checks for phase problems that destroy mono compatibility:

• Per-band phase correlation (sub, bass, mid, high)

• Polarity check (inverted channels?)

• Inter-channel sample delay (misaligned mics, plugin latency)

• Mono compatibility score (what happens when L+R collapse to mono)

Low-frequency phase issues are critical: bass should be mono. High-frequency phase issues widen stereo but risk mono cancellation.

filename: WAV file in exports dir, or absolute path.

Returns per-band phase coherence + mono compatibility assessment.

Analyze song structure by segmenting MIDI content into structural parts.

Scans all note tracks bar-by-bar, computes per-bar features (note density, pitch range, average velocity, active track count), groups consecutive bars into segments, and classifies each segment as intro/verse/chorus/bridge/ outro/breakdown based on density and energy patterns.

Essential for: understanding existing arrangements, finding where sections change, verifying song form, and planning variations or extensions.

unit_index: AU index (-1 = all AUs). bars_per_segment: Minimum bars per structural segment (default 4). Groups of bars with similar density are merged into segments of at least this length.

Returns per-segment classification with bar range, density, energy, and feature summary.

Spectral analysis of audio across 7 ISO frequency bands.

Divides the spectrum into standard bands:

• sub_bass (20-60 Hz), bass (60-250 Hz), low_mids (250-500 Hz), mids (500-2000 Hz), high_mids (2000-4000 Hz), presence (4000-6000 Hz), brilliance (6000-20000 Hz)

Per band: RMS (linear + dB), peak (dB), energy percentage. Global descriptors:

• spectral_centroid_hz: brightness (weighted mean frequency)

• spectral_spread_hz: frequency variance around centroid

• spectral_rolloff_95_hz: frequency below which 95% of energy lies

• low_high_ratio: energy <250 Hz / energy >250 Hz (tonal balance)

• spectral_crest: peak/mean power ratio (tonal vs noisy)

Use after analyze_track for mix decisions:

• High low_high_ratio → bass-heavy mix, may need EQ cut in low mids

• Low spectral_centroid → dark/muffled, consider high shelf boost

• High spectral_centroid → bright/harsh, consider high shelf cut

• Dominant band energy_pct → where the mix lives

Args: filename: Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.

Returns band-by-band analysis + global spectral descriptors + mix suggestions.

Stereo analysis of audio — width, L/R balance, mono compatibility, mid/side energy.

Analyzes the stereo field of a track:

• stereo_width: Side/Mid RMS ratio (0 = mono, 0.5+ = wide, 1.0 = hard panned)

• lr_balance: L/R energy difference (-1 = fully left, 0 = centered, +1 = fully right)

• phase_correlation: -1 to +1 (+1 = mono safe, 0 = uncorrelated, -1 = out of phase)

• mono_compatible: True if phase correlation > 0 (collapses to mono without cancellation)

• phase_issues_pct: % of samples where L and R have opposite polarity

• Per-region width: low (<250Hz), mid (250-4000Hz), high (4000+Hz) Helps identify if stereo width is well-distributed or concentrated in one region

Mix decision guidance:

• stereo_width < 0.1 → narrow/mono mix, consider widening

• stereo_width > 0.8 → very wide, check mono compatibility

• phase_correlation < 0 → phase issues, will cancel in mono

• lr_balance > 0.2 → right-heavy, consider rebalancing

• lr_balance < -0.2 → left-heavy, consider rebalancing

• Low-freq width > 0.3 → bass is wide (usually undesirable, keep bass mono)

Args: filename: Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.

Returns stereo descriptors, per-region width, and mix suggestions.

Full audio analysis in one call — BPM + key + LUFS + duration + dynamic range.

Composite tool that runs detect_bpm + detect_key + measure_lufs in a single call. Eliminates 3 separate calls for track analysis. Essential for Suno remix pipeline: download_audio → analyze_track → set_bpm + matching progression → import → mix → render.

filename: Name of the WAV file in the exports directory (without path), or absolute path to any WAV file.

Returns: bpm, bpm_confidence, key, mode, key_confidence, lufs_integrated, true_peak_db, duration_seconds, sample_rate, channels, dynamic_range, alternatives (key alternatives), chroma.

Examples: result = analyze_track("suno_track.wav")

→ {bpm: 128.0, bpm_confidence: 0.85, key: "A", mode: "minor",

lufs_integrated: -14.2, duration_seconds: 30.0, ...}

Then use results for remix:

set_bpm(result.bpm) create_progression_from_key(result.key, result.mode, "synthwave")

Apply articulation to existing notes — staccato, legato, tenuto, accent.

Reshapes note durations relative to their grid position to change phrasing character. Unlike velocity_curve (dynamics) or humanize (random), this applies deterministic duration ratios — the fundamental dimension of musical articulation.

unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = all regions on the track). articulation: Articulation type:

• "staccato" — shorten notes to fraction of their grid slot (default 50%)

• "legato" — extend notes to nearly the next note's start (default 95%)

• "tenuto" — hold notes to full grid slot (100%, no gap, no overlap)

• "accent" — boost velocity on notes that fall on beat boundaries (downbeats) amount: Articulation depth 0-1 (default 0.5):

• staccato: fraction of slot (0.3 = very short, 0.7 = moderate)

• legato: overlap fraction (0.9 = near-full, 0.5 = half-fill)

• tenuto: (unused, always full)

• accent: velocity boost amount (0.3 = subtle, 1.0 = strong accent)

Returns per-region note counts and total notes reshaped.

Examples: apply_articulation(articulation="staccato", amount=0.3) # crisp, detached apply_articulation(articulation="legato", amount=0.95) # smooth, connected apply_articulation(articulation="accent", amount=0.8) # strong downbeat accents

Apply a melodic contour shape to existing notes.

Redistributes note pitches to follow a specified contour profile while keeping timing and duration unchanged. Unlike transpose_notes (uniform shift), this reshapes the melody direction — ascending, descending, arch, inverted arch, wave, or custom.

The tool calculates a target pitch for each note based on its position in the sequence (0..1 normalized) mapped through the contour function, then snaps to the nearest scale degree if requested. The original pitch range center is preserved.

Contours:

• "ascending": low to high across the phrase

• "descending": high to low

• "arch": rise then fall (peak at midpoint)

• "inverted_arch": fall then rise (valley at midpoint)

• "wave": sinusoidal up-down-up

• "escalating": stepwise ascending with plateaus

Args: unit_index: Audio unit index track_index: Note track index region_index: Region index (-1 = first region) contour: Contour shape name range_semitones: Pitch range span in semitones (1-48, default 12=octave) snap_to_scale: Scale for snapping results (""=chromatic, "major", "minor", "dorian", "phrygian", "lydian", "mixolydian", "locrian", "harmonic_minor", "melodic_minor", "pentatonic", "blues") root: Root note for scale snapping preserve_first: Keep first note pitch unchanged preserve_last: Keep last note pitch unchanged

Apply a complete mix in one call — genre-aware processing chains on every track + mastering.

Replaces 5-6 separate calls (add_drum_chain + add_bass_chain + add_instrument_chain × N + add_mastering_chain). Each track gets the right chain with genre-appropriate style automatically.

genre: Determines chain styles per track. Supported: dnb, liquid_dnb, house, trap, techno, dubstep, afrobeat, rock, jazz, pop, funk, reggae, synthwave, trance, disco unit_index: Target audio unit. num_tracks: Number of note tracks in the unit (default 4). Track 0 = drums, Track 1 = bass, Track 2+ = melodic/instrument. master_lufs: Mastering LUFS target (-14 Spotify, -10 loud, -16 Apple).

Chain assignment per track: Track 0 → add_drum_chain (genre-aware style) Track 1 → add_bass_chain (genre-aware style) Track 2+ → add_instrument_chain (genre-aware style) Output → add_mastering_chain

Returns summary of all chains applied.

Example:

Full mix for a 4-track house project

apply_full_mix("house", unit_index=0, num_tracks=4)

Loud techno master

apply_full_mix("techno", num_tracks=3, master_lufs=-10)

Apply genre-aware humanization to arrangement tracks — makes programmed MIDI feel alive.

After creating an arrangement, notes are perfectly quantized — robotic. This tool applies genre-appropriate humanization: jazz gets loose timing and wide velocity variation, electronic genres stay tight with minimal variation, funk gets behind-the-beat pocket feel.

Each genre has a different humanization recipe:

• Jazz: high timing variation (0.20), high velocity variation (0.20), swing 0.66 (classic jazz swing feel). Drums get the most humanization.

• Funk: behind-the-beat timing (positive bias), medium velocity variation, swing 0.0 (straight 16ths but with pocket feel).

• Rock: medium timing (0.10), medium velocity (0.12), no swing. Drums get slight push, bass stays tight.

• Reggae: laid-back timing (positive bias, behind beat), medium velocity, no swing. Bass stays tight (it's the lead), drums get loose.

• Pop: very subtle (0.05 timing, 0.08 velocity), no swing. Pop should sound polished, not loose.

• DnB/House/Techno/Trance/Synthwave/Dubstep/Trap: minimal humanization. Electronic genres should sound tight and consistent. Timing 0.03, velocity 0.05, no swing.

• Afrobeat: medium timing (0.12), medium velocity (0.15), no swing. Polyrhythms need some human feel but stay grounded.

• Disco: subtle timing (0.06), medium velocity (0.10), no swing. Disco should sound tight but not robotic — live drummer feel.

genre: One of: dnb, house, trap, techno, dubstep, afrobeat, rock, jazz, pop, funk, reggae, synthwave, trance, disco unit_index: AU index with the arrangement tracks. drum_track / bass_track / harmony_track / melody_track: Track indices. has_4th_track: True if arrangement has 4 tracks (False for 3-track genres).

Returns humanization parameters applied per track.

Example:

After: create_jazz_arrangement(...)

apply_genre_humanization("jazz", unit_index=0)

After: create_dnb_arrangement(...)

apply_genre_humanization("dnb", unit_index=0, has_4th_track=False)

Apply genre-specific mixing effects to tracks after creating an arrangement.

Closes the loop: create arrangement → apply genre mix → ready to render. One call replaces 10-20 manual add_effect + set_effect_parameter calls.

Each genre has a different effect chain recipe:

• Drums: compressor (genre-specific ratio/threshold) + EQ

• Bass: EQ (HPF + low boost) + saturation (genre-specific)

• Chords/Melody: reverb (genre-specific decay) + delay (if applicable)

• Extra track: genre-specific treatment

• Sidechain: drums→bass (if applicable to genre)

genre: One of: dnb, house, trap, techno, dubstep, afrobeat, rock, jazz, pop, funk, reggae unit_index: AU index with the arrangement tracks. num_tracks: Number of tracks to mix (3 or 4, must match arrangement). sidechain: Whether to add sidechain drums→bass (True for electronic genres, False for organic).

Returns effects added per track and parameter values.

Example:

After: create_dnb_arrangement(...)

apply_genre_mix("dnb", unit_index=0, num_tracks=3, sidechain=True)

After: create_jazz_arrangement(...)

apply_genre_mix("jazz", unit_index=0, num_tracks=4, sidechain=False)

Apply a mix preset to all audio units in one call — volume, pan, mute, solo.

Replaces 10-30 set_track_volume/set_track_panning/set_track_mute calls. Presets can be genre-specific or custom JSON.

preset: JSON object mapping unit indices to settings: {"0": {"volume_db": -3, "panning": 0.0, "mute": false}, "1": {"volume_db": -6, "panning": -0.3, "solo": false}, ...}

Alternatively, use a named preset: "lofi", "house", "balanced", "wide"

Returns applied settings per unit.

Example: preset='{"0":{"volume_db":-3,"panning":0},"1":{"volume_db":-6,"panning":-0.3}}' preset='lofi' (built-in: kicks +0, bass -3, synths -6, wide pans)

Apply a rhythmic pattern to existing notes — reposition onsets to match a target grid.

Takes a rhythm pattern (either a rhythm_string like "x.x.x..x" or an onset_grid like "1,0,1,0,1,0,0,1") and repositions existing notes onto the onset positions. This is the inverse of extract_rhythm — it lets you stamp a groove onto any note content.

How it works:

1. Reads existing notes and their pitches/velocities/durations

2. Computes the target onset positions from the pattern (cycling if pattern is shorter than the region)

3. Distributes notes across onset positions:

   • If fewer onsets than notes: extra notes are placed at the nearest onset

   • If more onsets than notes: notes are assigned round-robin to onsets

4. Optionally adjusts velocity (accent onsets) and duration (staccato/legato)

velocity_mode:

• "preserve": keep original velocities

• "accent": strong beats (0,4,8,12 in 16th) get +20% velocity, weak get -10%

• "flat": all notes get 0.8 velocity

• "pattern": use onset_velocities from extract_rhythm if provided in onset_grid

duration_mode:

• "preserve": keep original durations

• "staccato": each note lasts 50% of the grid step

• "legato": each note lasts until the next onset

unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = first region). rhythm_string: Compact pattern "x.x.x..x" (x=onset, .=rest). Used if onset_grid is empty. onset_grid: Comma-separated "1,0,1,0,1,0,0,1" or "1;0.5;0;0.8" (value=velocity). Takes priority over rhythm_string. grid: Grid resolution (16th/8th/32nd/quarter). velocity_mode: How to handle velocities (preserve/accent/flat/pattern). duration_mode: How to handle durations (preserve/staccato/legato).

Returns modification summary with repositioned note count.

Example:

Extract groove from drums, apply to bass

rhythm = extract_rhythm(0, 0, grid="16th")

... parse rhythm_string from result ...

apply_rhythm_pattern(0, 1, rhythm_string="x...x...x...x...", grid="16th")

Apply sidechain ducking via volume automation — the classic pumping/breathing effect.

Simulates sidechain compression by creating volume automation that ducks on every kick beat and recovers. This is the signature sound of house, techno, EDM, and modern pop. Works by creating automation events on the target track's volume parameter.

unit_index: AU index whose volume will be automated. track_index: Track index (-1 = all tracks on the AU). bars: Number of bars to fill with sidechain (1-16). start_beat: Starting beat position. depth: Ducking depth 0-1 (0.6 = volume drops to 40% on each kick, 0.8 = drops to 20%). attack: Attack time in beats (how fast volume drops, 0.01 = instant, 0.05 = smooth). release: Release time in beats (how fast volume recovers, 0.3 = classic, 0.5 = slow pump). kick_interval: Kick spacing in beats (1.0 = every beat, 2.0 = every 2 beats, 0.5 = 16th kicks).

Returns total automation events created and ducking pattern info.

Example: apply_sidechain(unit_index=0, bars=8, depth=0.7, release=0.25, kick_interval=1.0)

Apply swing feel to existing notes without changing velocity or duration.

Swing shifts every other grid position later, creating a triplet/shuffle feel. Unlike humanize_notes (which couples swing with random velocity/timing changes), this tool applies pure swing — deterministic, no randomness, reversible.

unit_index: AU index (-1 = all AUs). track_index: Note track index (-1 = all note tracks on the AU). swing_amount: Swing depth 0-1 (0 = straight, 0.5 = light swing, 1.0 = full triplet). 0.55-0.66 = classic hip-hop/lofi swing. grid: Grid to swing against — "16th" (default, shifts odd 16ths) or "8th" (shifts odd 8ths).

Returns per-track note counts shifted.

Example: apply_swing(unit_index=0, track_index=0, swing_amount=0.58, grid="16th")

Apply a velocity envelope across notes — ramp, arc, trough, or custom power curve.

Maps each note's position within its region to a velocity value via a mathematical curve. Unlike humanize_notes (random variation), this applies a deterministic envelope shape — useful for build-ups, fade-ins, crescendo rolls, and expressive phrasing.

unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = all regions on the track). curve_type: Curve shape:

• "ramp_up" — linear increase from start_velocity to end_velocity

• "ramp_down" — linear decrease from start_velocity to end_velocity

• "arc" — rises to end_velocity then falls back to start_velocity (peak in middle)

• "trough" — falls to start_velocity then rises to end_velocity (dip in middle)

• "power" — exponential curve controlled by 'power' param (>1 = fast rise, <1 = slow rise) start_velocity: Velocity at curve start 0-1 (default 0.3). end_velocity: Velocity at curve end 0-1 (default 1.0). power: Exponent for "power" curve type (default 1.0 = linear). 2.0 = sharp attack, 0.5 = slow swell.

Returns per-region note counts and total notes shaped.

Examples: apply_velocity_curve(curve_type="ramp_up", start_velocity=0.2, end_velocity=1.0) # build-up apply_velocity_curve(curve_type="arc", start_velocity=0.4, end_velocity=0.95) # expressive phrase apply_velocity_curve(curve_type="power", power=2.0, start_velocity=0.1, end_velocity=1.0) # sharp attack

Apply periodic velocity modulation — velocity LFO along note positions.

Oscillates note velocity cyclically based on each note's position, creating pumping, breathing, or wave-like dynamic motion. Unlike apply_velocity_curve (monotonic ramps), this creates REPEATING velocity patterns synced to beat positions.

Args: unit_index: Audio unit index track_index: Note track index rate: LFO cycles per beat (0.25=every 4 beats, 1.0=per beat, 2.0=twice per beat, 0.5=every 2 beats) depth: Modulation depth 0-1 (0=no change, 0.3=subtle breathing, 1.0=full swing from 0 to max) shape: LFO waveform — "sine" (smooth), "triangle" (linear), "saw" (ramp up), "square" (on/off), "random" (per-beat random) phase: Starting phase 0-1 (0=begin at peak, 0.25=begin at zero rising, 0.5=begin at trough, 0.75=begin at zero falling) center: Center velocity around which modulation oscillates (0-1). The LFO modulates ±depth*center around this value. region_index: Specific region (-1 = all regions)

Returns: JSON with notes_processed, modulation stats (min/max/avg velocity before and after), regions_processed, rate, depth, shape.

Apply a cyclic velocity pattern to existing notes in a region.

The producer's accent pattern tool. Instead of a linear ramp (crescendo), this applies a repeating velocity pattern across notes — the foundation of groove. Examples: strong-weak-medium-weak (backbeat emphasis), staggered accents for syncopation, or dynamic intensity layers.

unit_index: AU index. track_index: Track index. pattern: JSON array of velocity multipliers 0.0-1.0. Cycled across notes in order of position. Example: [1.0, 0.5, 0.7, 0.5] = strong-weak-medium-weak. region_index: Region index (-1 = first region). mode: "cycle" (repeat pattern from start, default) or "stretch" (distribute pattern evenly across all notes — good for 2-note patterns on 16 notes). base_velocity: Base velocity 0-1 that multipliers are applied to (default 0.8). Final velocity = base_velocity * pattern[i % len].

Returns notes modified, pattern applied, and velocity preview.

Examples: apply_velocity_pattern(unit_index=0, track_index=0, pattern="[1.0, 0.5, 0.7, 0.5]") -> 4-note accent cycle: strong-weak-medium-weak on every group of 4 notes apply_velocity_pattern(unit_index=0, track_index=0, pattern="[1.0, 0.3]", base_velocity=0.9) -> Alternating strong/weak at 0.9 and 0.27 apply_velocity_pattern(unit_index=1, track_index=0, pattern="[0.8, 0.4, 0.6, 0.4, 0.9, 0.4, 0.7, 0.4]", mode="stretch") -> 8-note pattern stretched across all notes in region

Augment or diminish note durations — the fourth classical transformation.

Multiplies note durations by a factor. Combined with transpose, reverse, and invert, this completes the set of four fundamental motivic transformations used by Bach, Beethoven, and every composition teacher since.

• factor > 1.0: augmentation (longer notes, slower feel). 2.0 = double duration.

• factor < 1.0: diminution (shorter notes, faster feel). 0.5 = half duration.

• factor = 1.0: no change (useful for testing).

Think Beethoven 5th: the opening G-G-G-Eb motif returns augmented (twice as slow) in the recapitulation. Or Bach fugues where the subject appears in diminution (twice as fast) in the finale.

factor: Duration multiplier (0.25-4.0). 2.0 = augmentation, 0.5 = diminution. unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = all regions on the track). mode: How to handle note positions — "scale" (default): multiply both duration AND position relative to region start. The entire phrase slows down or speeds up — notes stay in sequence. "stretch": multiply only duration, leave positions unchanged. Notes become longer/shorter but don't move — may overlap or leave gaps.

Returns count of notes augmented and notes skipped (duration too short/long).

Auto-adjust output volume to hit a target LUFS.

Iterative loop: render → measure LUFS → adjust Maximizer threshold → re-render. Converges within ±1 LUFS of target.

target_lufs: Target loudness (Spotify -14, YouTube -14, Apple -16). filename: Output filename (without .wav). sample_rate: Export sample rate (default 48000). max_iterations: Max refinement loops (default 3).

Returns final LUFS, threshold applied, iterations, and WAV path.

Create a smooth automation sweep (ramp) between two values over a beat range.

Generates multiple automation events with interpolated values, creating smooth parameter transitions (filter sweeps, volume fades, pitch drops, etc.) in one call. Automatically creates the automation track if it doesn't exist yet.

unit_index: AU index. parameter_name: Instrument parameter to automate (e.g. "cutoff", "volume", "resonance"). start_beat: Start position in beats. end_beat: End position in beats. start_value: Starting normalized value (0.0-1.0). end_value: Ending normalized value (0.0-1.0). steps: Number of interpolation points (default 16, more = smoother). curve: "linear" (even spacing), "exp" (exponential, good for filter sweeps), "log" (logarithmic).

Returns the number of events created and a preview of the first few points.

Example: Filter sweep from closed (0.1) to open (0.9) over 16 beats: automation_sweep(unit_index=0, parameter_name="cutoff", start_beat=0, end_beat=16, start_value=0.1, end_value=0.9, steps=32, curve="exp")

Balance velocities across multiple tracks — MIDI mix leveling.

Sets relative velocity levels across multiple note tracks so they sit correctly in the mix. Unlike scale_velocity (one track at a time), this operates on multiple tracks simultaneously and establishes the relative balance between them.

Presets:

• "mix_balanced" — all tracks equal (~0.75). Neutral starting point.

• "drums_forward" — drums loudest (0.95), bass (0.80), harmony (0.65), lead (0.70). Hip-hop, rock, electronic.

• "vocal_forward" — vocal/lead loudest (0.95), pads (0.60), bass (0.75), drums (0.80). Pop, ballad, singer-songwriter.

• "pads_quiet" — pads very quiet (0.50), arp (0.65), bass (0.80), drums (0.90), lead (0.85). Ambient, cinematic.

• "bass_heavy" — bass loudest (0.95), drums (0.85), lead (0.70), harmony (0.55). Reggae, dub, trap.

• "custom" — use target_velocities parameter (comma-separated 0-1 values, one per track in track_indices order).

The tool reads current average velocities, computes scale factors to reach targets, and applies them. Original relative dynamics within each track are preserved (multiply mode).

track_indices: Comma-separated track indices (e.g. "0,1,2,3"). preset: One of the presets above, or "custom". target_velocities: For custom mode — comma-separated target avg velocities (e.g. "0.9,0.7,0.6,0.8"). Must match track_indices count. region_index: Region (-1 = first, -2 = all regions).

Returns per-track velocity stats before/after.

Example:

Balance 4 tracks: drums, bass, pads, lead

balance_track_velocities(0, "0,1,2,3", preset="drums_forward")

Custom: drums=0.9, bass=0.7, pads=0.5, lead=0.8

balance_track_velocities(0, "0,1,2,3", preset="custom", target_velocities="0.9,0.7,0.5,0.8")

Run full diagnostic on multiple stems in one call — problems + phase + profile comparison.

Phantom's batch_diagnostic equivalent. For each stem runs:

1. detect_problems (clipping, DC offset, mud, harshness, sibilance, resonance)

2. analyze_phase (polarity, correlation, mono compat) — stereo files only

3. compare_to_profile (if genre specified)

Produces a prioritized triage report:

• dealbreaker: clipping, phase inversion, DC offset

• significant: mud, harshness, resonance

• moderate: sibilance risk, width issues

• minor: slight deviations from profile

filenames: JSON array or comma-separated list of WAV filenames. genre: Optional genre profile for comparison (pop, rock, lo-fi, etc.).

Returns per-stem results + global summary + prioritized fix list.

Example: batch_diagnostic('["vocals.wav","bass.wav","drums.wav","mix.wav"]', genre="rock")

→ {triage: [{stem: "vocals", severity: "significant", problems: [...]}]}

Capture realtime audio output from the DAW engine.

Records the live audio output for a specified duration. The engine must be running (call start_engine first). Useful for capturing live playback with effects, automation, and real-time processing.

duration_seconds: How long to record (float, e.g. 10.0). filename: Output WAV filename (without extension).

Returns file path and size, or error if engine not running.

Change the base time signature of the project.

This changes the initial signature (default 4/4). All existing signature change events are recalculated to preserve their approximate absolute positions.

nominator: Number of beats per bar (e.g. 4 for 4/4, 3 for 3/4, 6 for 6/8). denominator: Beat unit (1=whole, 2=half, 4=quarter, 8=eighth, 16=sixteenth).

Returns success or error.

Classify a drum pattern from MIDI notes in a region.

Analyzes drum note positions, pitches (GM drum map: 36=kick, 38=snare, 42=closed hat, 46=open hat, 50=high tom, 45=low tom, 49=crash, 51=ride), and velocities to classify the pattern as one of: four-on-the-floor, breakbeat, boom-bap, trap, shuffle, half-time, military/march, amen, unknown.

Essential for: understanding existing drum patterns, matching genre expectations, verifying generated patterns, and suggesting variations.

unit_index: AU index (-1 = all AUs). track_index: Note track index (-1 = all note tracks). region_index: Region index (-1 = all regions on track).

Returns pattern classification with confidence, features, and per-bar breakdown.

Clear all notes from a region while keeping the region on the timeline.

Removes every note event from the specified region(s) but preserves the region itself — its position, duration, and track placement stay intact. This is the "erase and rewrite" operation: the producer wants to clear a region to start fresh, without deleting and recreating the region container.

Different from delete_note_region (which removes the entire region from the timeline) and delete_note (which removes one note at a time).

unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = all note regions on the track).

Returns notes cleared and remaining region info.

Examples: clear_region_notes(unit_index=0, track_index=0, region_index=0) -> Erase all notes in region 0, region stays on timeline clear_region_notes(unit_index=0, track_index=0, region_index=-1) -> Erase all notes in ALL regions on track 0

Clone a clip (note or value) on the same track. Optionally consolidate (make event collection unique).

unit_index: AU index. track_index: Track index within the AU. clip_index: Clip index to clone. consolidate: If true, the clone gets its own independent event collection (not shared).

Returns success, or error.

Copy all effects from one audio unit to another, including parameter values.

Useful for applying the same vocal chain (EQ → compressor → reverb) to doubled vocal tracks.

src_unit: Source audio unit index. dst_unit: Destination audio unit index (effects appended to existing chain).

Returns list of cloned effects with their new indices.

Clone a track — full duplication of notes, regions, and structure.

Creates a new track within the same audio unit (or a new audio unit) with all notes from the source track copied over. Optionally transposed, velocity-scaled, and time-shifted.

Unlike copy_notes_to_track (which copies notes between existing tracks), clone_track creates the destination track from scratch with the correct track type (note/audio), then populates it with a region and all notes from the source.

Essential for:

• Doubling: same notes on two instruments for thicker sound

• Octave layering: transpose +12 for octave above

• Parallel harmony: transpose +7 for fifths, +3 for thirds

• Call-and-response: time_offset to shift the copy later

• Counterpoint layer: same rhythm, different transposition

Args: unit_index: Source audio unit index track_index: Source track index within the unit name: Optional name for the cloned track (default: same as source) transpose: Semitone transposition applied to cloned notes (-24 to +24, default 0 = same pitch) velocity_scale: Multiply note velocities by this factor (0.1-2.0, default 1.0 = same velocity) time_offset_beats: Shift all notes by this many beats (-16 to +16, default 0.0 = same position) new_unit: If true, create a new audio unit for the clone (requires same instrument type). If false (default), adds a new track to the source audio unit.

Remove empty tracks from an audio unit (or all AUs).

Calls ProjectApi.compactTracks() — removes tracks with no regions. Useful cleanup after deleting regions or editing.

unit_index: Audio unit index (-1 = all AUs).

Compare your mix against a professional genre reference profile.

Tells you exactly where your mix deviates from genre standards:

• LUFS: too loud/quiet for this genre?

• Spectrum: which frequency bands are off?

• Stereo width: appropriate for genre?

• Dynamics: too compressed or too wild?

• Spectral centroid: too dark or too bright?

Gives per-dimension deviation + specific recommendations.

filename: WAV file in exports dir, or absolute path. genre: One of: pop, rock, hip_hop, electronic, edm, metal, lo-fi, ambient, cinematic

Returns deviation analysis with severity-ranked suggestions.

Example: compare_to_profile("my_mix.wav", "lo-fi")

→ {lufs_deviation: +3.4, spectral_deviations: [...], suggestions: [...]}

A/B compare your mix against a reference track across all dimensions.

Shows exactly where your mix differs from a professional reference:

• LUFS difference (loudness gap)

• Spectral curve deviation per band

• Stereo width comparison

• Dynamic range comparison

• Spectral centroid (brightness) comparison

This is how you learn how pros mix your genre. Drop in a reference track you admire and see exactly what's different.

filename: Your mix WAV (exports dir or absolute path). reference: Reference track WAV (exports dir or absolute path).

Returns per-dimension comparison + actionable deltas.

Example: compare_to_reference("my_mix.wav", "pro_reference.wav")

→ {lufs_delta: +2.3, spectral_deltas: [...], suggestions: [...]}

Connect two modules in a Modular device (create a patch cable).

au_index: Audio unit index. effect_index: Effect index within the AU. source_module_index: Index of the source module. source_output_name: Name of the output connector (e.g. "Output", "Result"). target_module_index: Index of the target module. target_input_name: Name of the input connector (e.g. "Input", "X", "Y").

Returns success or error.

Connect one audio unit's output as sidechain source to a Compressor/Gate on another unit.

source_unit_index: Audio unit whose output triggers the sidechain (e.g. drums). target_unit_index: Audio unit with the Compressor/Gate effect (e.g. bass). effect_index: Effect position on the target unit (must have a sideChain field).

The target effect must be Compressor, Gate, Vocoder, or any effect with Pointers.SideChain.

Consolidate a clip's event collection — make it unique (not shared/mirrored).

If a clip shares its event collection with other clips (mirrored), this creates a new independent copy so edits don't affect other clips.

unit_index: AU index. track_index: Track index within the AU. clip_index: Clip index to consolidate.

Returns success, or error.

Consolidate a repeated note (playCount > 1) into individual separate notes.

If a note has playCount > 1, it represents N repeats controlled by playCurve. This expands it into N independent notes, each with playCount=1, positioned according to the curve. The original note is deleted.

unit_index: AU index. track_index: Note track index. region_index: Note region index. note_index: Note index within the region.

Returns the number of notes created, or error if note has playCount=1.

Consolidate a region's event collection — make it unique (not shared/mirrored).

If a region shares its event collection with other regions (mirrored), this creates a new independent copy so edits don't affect other regions.

unit_index: AU index. track_index: Track index within the AU. region_index: Region index to consolidate.

Returns success or error.

Constrain notes to a pitch range — clamp or octave-wrap out-of-range notes.

After AI generation, transcription, or aggressive transposition, notes can land outside the playable range of an instrument. This tool brings them back inside.

Two modes:

• "clamp" — notes below min_pitch are set to min_pitch, notes above max_pitch are set to max_pitch. Preserves the note but loses pitch information. Use when exact range matters (e.g. MIDI 0-127 safety).

• "octave_wrap" — notes are shifted by octaves (±12 semitones) until they fall within [min_pitch, max_pitch]. Preserves pitch class and musical relationship. Use for instrument range constraints (violin, guitar, vocal, flute). If a note can't fit even after wrapping (range < 12 semitones), it's clamped.

Common instrument ranges (MIDI note numbers):

• Guitar (standard tuning): E2(40) to E6(88)

• Bass guitar: E1(28) to G4(67)

• Violin: G3(55) to A7(105)

• Cello: C2(36) to C6(84)

• Flute: C4(60) to D7(98)

• Vocal soprano: C4(60) to A5(81)

• Vocal bass: E2(40) to E4(64)

unit_index: AU index (-1 = all AUs). track_index: Note track index (-1 = all note tracks on the AU). region_index: Region index (-1 = all regions on the track). min_pitch: Minimum allowed MIDI pitch (0-127, default 0 = no lower bound). max_pitch: Maximum allowed MIDI pitch (0-127, default 127 = no upper bound). mode: "clamp" (hard limit) or "octave_wrap" (shift by octaves to fit).

Returns per-track notes adjusted, clamped count, wrapped count.

Example:

Constrain to guitar range with octave wrapping

constrain_note_range(unit_index=0, track_index=2, min_pitch=40, max_pitch=88, mode="octave_wrap")

Safety clamp to MIDI range

constrain_note_range(mode="clamp", min_pitch=0, max_pitch=127)

Convert an exported WAV file to MP3 or FLAC using system ffmpeg.

filename: Source WAV filename (without .wav extension, in the export dir). format: 'mp3' or 'flac' (default 'mp3'). bitrate: MP3 bitrate for CBR mode (default '320k'). Ignored for FLAC. quality: MP3 VBR quality 0-9 (0=best, 9=worst). Use -1 for CBR (default).

Requires system ffmpeg (not browser WASM). Falls back gracefully if missing. Returns path to the converted file and size info.

Copy notes from one track/region to another track — MIDI layering and doubling.

Copies all notes from a source region to a destination track's first region. Optional transpose (semitones), time offset (beats), and velocity scaling.

Use cases:

• Layer drums: copy drum track to second track with different instrument

• Create harmony: copy melody +12 (octave) or +7 (fifth)

• Call-and-response: copy with time_offset to create echo

• Doubles: copy to same track position with slight transpose for thickening

source_unit_index: Source AU index. source_track_index: Source note track index. dest_track_index: Destination note track index. source_region_index: Source region (-1 = first region). dest_unit_index: Destination AU index (-1 = same as source). transpose: Semitone offset (-127 to 127, 0 = same pitch). time_offset: Beat offset for copied notes (0 = same position, 2 = two beats later). velocity_scale: Multiply velocity of copied notes (1.0 = same, 0.7 = quieter layer).

Returns count of notes copied.

Example:

Layer drums — copy track 0 to track 2

copy_notes_to_track(0, 0, 2)

Create octave harmony — copy melody +12

copy_notes_to_track(0, 3, 4, transpose=12, velocity_scale=0.7)

Echo effect — copy 2 beats later at half velocity

copy_notes_to_track(0, 0, 1, time_offset=2, velocity_scale=0.5)

Copy a Playfield (drum machine) sample to a new index slot.

Duplicates the sample with all its parameters (mute, solo, pitch, attack, release, sampleStart, sampleEnd, gate, exclude, polyphone) to a new slot.

unit_index: AU index containing the Playfield instrument. sample_index: Source sample slot index. target_index: Destination slot index.

Returns success or error.

Copy fade in/out settings from one audio region to another.

Copies fadeIn, fadeOut, fadeInSlope, fadeOutSlope from the source region's Fading object to the destination region's Fading object.

src_unit/src_track/src_region: Source region coordinates. dst_unit/dst_track/dst_region: Destination region coordinates.

Returns the copied fade values.

Copy a region to a different track (or same track at new position).

Works with note, audio, and automation regions. The copy includes all content — notes, audio content, or automation events.

src_unit/src_track/src_region: Source region coordinates. dst_unit/dst_track: Destination track coordinates. position: New position in PPQN (omit to use source position).

Returns new region position and duration.

Create an acid house arrangement — TB-303 squelch bassline.

Acid house is a subgenre of house music born in Chicago (1985-87) defined by the Roland TB-303 bass synthesizer with its distinctive squelchy, resonant filter sweeps. Key characteristics:

• TB-303 bassline: monophonic, sequenced 16th notes with filter cutoff sweeps (open↔closed), accent and glide (slide) between notes. The signature "squelch" sound.

• 909 drum machine: 4-on-floor kick, open hat on offbeats, clap on 2&4, ride cymbal

• 125 BPM, 4/4 time

• Minimal, hypnotic, repetitive structure with gradual evolution

• Often in minor key with chromatic bassline movement

Creates 3 tracks:

1. Drums (track_index): 909-style — kick on every beat, clap on 2&4, open hat on offbeats, closed hat on 16ths, ride on quarter notes

2. Bass (track_index+1): TB-303-style 16th note pattern with chromatic movement, octave jumps, and accent patterns. Notes have varied velocity to simulate filter envelope.

3. Lead (track_index+2): Sparse, hypnotic stab on beat 1 of every 4 bars, minor key pad-like sustained note

Default key: A minor (classic acid key).

Create an additive rhythm — unequal groupings within a bar.

The defining technique of Messiaen, Stravinsky, Bartok, Ligeti, and modern math rock / prog metal. Instead of dividing a bar into equal parts (eighth-eighth-eighth-eighth), the bar is divided into unequal groups (3+2+2 = 7 eighths, 2+3+2 = shifting accent, 5+3 = 8 eighths).

The resulting accent pattern creates a sense of irregular meter within a nominal time signature — the pulse "turns" inside the bar.

Examples: create_additive_rhythm("3+2+2", "eighth") -> 7 eighth notes grouped as 3-2-2, accents on notes 1, 4, 6 (Bartok "Bulgarian Rhythm", Math rock 7/8 feel) create_additive_rhythm("2+3+2", "eighth", repeats=4) -> shifting accent pattern, 4 bars create_additive_rhythm("5+3", "eighth", pitch="scale_up") -> 8 eighths in 5+3 grouping, ascending scale create_additive_rhythm("3+2+2", "sixteenth", repeats=2, decay=0.1) -> 7 sixteenths per bar, velocity decay within groups

Args: grouping: Plus-separated group sizes (e.g. "3+2+2", "5+3", "2+1+2"). Each number = count of notes in that group. Sum = total notes per bar. 2-6 groups, 2-16 notes total. unit: Note value — "eighth", "quarter", "sixteenth", "thirty_second". repeats: Number of bars (1-16). pitch: Pitch mode — "root" (same note), "scale_up" (ascending scale), "scale_down" (descending), "alternating" (up/down per note), "octave_bounce" (root->octave->root). scale: Scale for pitch modes (minor, major, dorian, phrygian, etc.). root: Root note (C, C#, D, ...). octave: Base octave (1-6). accent_mode: Where to place accents — "group_start" (first note of each group gets accent), "group_end" (last note), "every_note" (all same velocity). accent_velocity: Velocity for accented notes (0-1). normal_velocity: Velocity for non-accented notes (0-1). decay: Velocity decay within each group (0-0.3). Each subsequent note in a group gets slightly softer. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position.

Returns notes created, grouping structure, accent pattern, and bar layout.

Create a full afrobeat arrangement — polyrhythmic drums + bass + horns + guitar across 4 tracks.

Fela Kuti-style afrobeat with all elements locked in polyrhythmic interlock:

• Track 0: Drums — layered polyrhythm: kick pattern, shaker pattern, clave-like accents. The foundation is 12/8 feel in 4/4 time — triplets over straight beats, the African polyrhythmic heartbeat.

• Track 1: Bass — repetitive ostinato bassline, rooted in the key, driving and hypnotic. Afrobeat bass doesn't rest — it's the engine alongside the drums, locking with the kick.

• Track 2: Horns — brass section stabs and sustained chords. Call-and-response between horn hits and space. Minor key, soulful.

• Track 3: Guitar — rhythmic chord stabs on the off-beats, the "chanka" pattern that defines the groove. Two-note voicings, percussive and tight.

At 120 BPM (default), this creates the classic afrobeat feel — not too fast, not too slow, with room for polyrhythmic layering. The 4-track arrangement (first non-electronic genre) is the key difference: horns and guitar add organic texture that electronic arrangements don't have.

bpm: Tempo (100-130, default 120 = classic afrobeat). bars: Arrangement length (8-32, default 8). Afrobeat needs long forms. root: Root note (F is the classic afrobeat key — Fela's preference). octave: MIDI octave for bass (2 = C2=36, audible low end). unit_index: AU index with note tracks. drum_track / bass_track / horn_track / guitar_track: Track indices.

Returns notes created per track and total.

Example: create_afrobeat_arrangement(bpm=120, root="F", bars=8) create_afrobeat_arrangement(bpm=110, root="Ab", bars=16)

Create an ambient arrangement — 70 BPM atmospheric soundscape.

Ambient music (Brian Eno, Stars of the Lid, Aphex Twin Selected Ambient Works) focuses on atmosphere, texture, and sustained sound over rhythm and melody. Key characteristics:

• 60-80 BPM (or no clear pulse), 4/4 time

• Long sustained pad notes with slow evolution

• Sparse, minimal percussion (or none)

• Drifting melodic fragments, no clear phrase structure

• Reverb-drenched, wide stereo, cinematic

• Modal harmony (sustained chords, slow changes)

Creates 4 tracks:

1. Pad (track_index): Long sustained chord notes (8 bars each), mode-based (major/minor/dorian/lydian), very slow harmonic rhythm. Root, fifth, octave — open voicings.

2. Melody (track_index+1): Sparse, drifting melodic fragments — long notes (2-4 bars), wide intervals, lots of space. Starts after 8 bars.

3. Drums (track_index+2): Extremely sparse — single kick on bar 1 of every 8 bars, occasional shaker. Almost subliminal pulse.

4. Bass (track_index+3): Sustained sub-bass drone, root note only, changes with pad harmony. Very low octave.

Default key: C major (most common ambient key). Default 32 bars for proper ambient evolution length.

Create an appoggiatura — leaning grace note that resolves to the main note.

The appoggiatura is the fourth and final essential baroque ornament (trill, mordent, turn, appoggiatura). Unlike a mordent (quick flick), the appoggiatura is expressive: it plays a neighbor note FIRST (usually longer), then resolves into the main note. The approach note creates harmonic tension that the main note releases. Think Bach cello suites, Mozart operas, Chopin nocturnes.

An appoggiatura above approaches from higher (e.g. D → C). An appoggiatura below approaches from lower (e.g. B → C). The approach note typically takes 2/3 of the total duration, leaving 1/3 for the resolution — but this is adjustable.

main_pitch: The resolution note (default 60 = C4). This is where tension releases. approach_pitch: The grace note played first (default 62 = D4). Can be above or below main. duration_beats: Total length of both notes combined (0.5-8, default 1.0 = quarter). appoggiatura_ratio: Fraction of duration for the approach note (0.5-0.9, default 0.67 = 2/3). Higher = more tension (longer grace, shorter resolution). 0.5 = equal split. velocity: Base velocity 0-1 (default 0.85). Approach note is slightly accented. unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the appoggiatura begins.

Returns notes created, pitches used.

Create an Arabic/Middle Eastern percussion ensemble — darbuka, daf, and zills.

Middle Eastern percussion is built on the interplay between the darbuka (tabla, goblet drum) playing the core rhythm with dum (low) and tek/ka (high) strokes, the daf (frame drum) providing sustained resonance and rolls, and zills (sagat, finger cymbals) adding shimmering accents. The rhythms are cyclical with distinctive asymmetry — maqsum has a characteristic gap between dum strokes that creates tension.

The stroke vocabulary: DUM — Low, resonant center stroke on darbuka (bass register) TEK — High, ringing rim stroke (right hand, accented) KA — High, snapping rim stroke (left hand, lighter) SLAP — Sharp, accented stroke (mid register)

rhythms: "maqsum" — The most common Arabic rhythm: D-T- -T-D- -T-. 4/4, 8 beats. Dum on 1 and 4.5, tek on 2, 3, 5.5, 7. The "mother of all Arabic rhythms". Used in almost all Arabic pop, classical, and folk music. "baladi" — Urban Egyptian version of maqsum: D-D- -T-D- -T-. Dum on 1 and 1.5 (double dum), tek on 3, 5.5, 7. Heavier, more driving. The "baladi groove" of Cairo. "saidi" — Upper Egyptian rhythm: D-T- -T-D-D- -T-. 4/4. Dum on 1, 4.5, and 5 (double dum). Tek on 2, 3, 6.5, 7. From the Said region. Used in Saidi dance and music. "ayoub" — 2/4 cyclical rhythm: D- -T- -D-D-. 4 beats. Dum on 1, 3, 3.5. Tek on 2. Used in Sufi trance, zar ceremonies, and religious processions. "malfouf" — 2/4 fast rhythm: D- -T- -T-. 3 beats. Dum on 1, tek on 2, 2.5. Used in fast entrances, processions, and folk dances. "Running" feel. "chiftetelli" — 8/4 slow rhythm: D- -T- -T- -D- -T-. 8 beats. Dum on 1 and 5.5, tek on 2.5, 3.5, 7.5. Used in Turkish and Greek music, belly dance slow sections.

Args: bars: Pattern length in bars (2-16, even). rhythm: Rhythm name (maqsum, baladi, saidi, ayoub, malfouf, chiftetelli). velocity: Base velocity 0-1. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position. darbuka_pitch: Darbuka MIDI pitch (36 = C1). daf_pitch: Daf (frame drum) MIDI pitch (42 = F#1). zills_pitch: Zills (finger cymbals) MIDI pitch (50 = D2).

Returns notes created, instrument breakdown, stroke types, and rhythm info.

Create an arpeggiated chord progression — synthwave/trance arp engine.

Takes a chord progression string (same format as create_chord_pads: "Am-F-C-G") and generates arpeggiated notes cycling through chord tones. This is the synthwave arpeggiated bass, the trance supersaw arp, the house plucked chord stab — all from a simple progression string.

Unlike create_arpeggio (which takes a single chord), this cycles through a full progression, changing chord tones every bars_per_chord bars.

progression: Hyphen-separated chords (same as create_chord_pads). "Am-F-C-G" = i-VI-III-VII in A minor. "C-G-Am-F" = I-V-vi-IV in C major (pop).

pattern: Arpeggio pattern: "up" — root, third, fifth, root(oct) — classic synthwave "down" — oct root, fifth, third, root — descending "updown" — root, third, fifth, oct, fifth, third — full cycle "random" — random chord tones — dreamy, unpredictable "bass" — root only, 8th notes — driving bass arp (synthwave bass)

bars_per_chord: Bars per chord (default 4). octave: MIDI octave (3 = bass arp, 4 = mid arp, 5 = lead arp). velocity: Note velocity (0-1). step_duration: Note length in beats (0.25 = 16th, 0.5 = 8th, 0.125 = 32nd). track_index: Track for arp notes (typically melody track = 3).

Returns chords arpeggiated, total notes, pattern used.

Example:

Synthwave bass arp (16th notes, octave 2)

create_arpeggiated_progression("Am-F-C-G", pattern="bass", octave=2, step_duration=0.25, track_index=1)

Trance supersaw arp (16th up, octave 4)

create_arpeggiated_progression("Fm-Db-Ab-Eb", pattern="up", octave=4, step_duration=0.25, track_index=3)

Pop arp (8th updown, octave 5)

create_arpeggiated_progression("C-G-Am-F", pattern="updown", octave=5, step_duration=0.5, track_index=3)

Create an arpeggio from a chord name — one call instead of 8-32 create_note calls.

chord: Chord name in format RootType, e.g. "Cmin7", "F#maj", "Abmin7", "Ddim". Root: C, C#, D, D#, E, F, F#, G, G#, A, A#, B (or flats Db, Eb, Gb, Ab, Bb). Type: maj, min, dom7, maj7, min7, sus2, sus4, add9, dim, aug. pattern: Arpeggio direction/pattern:

• "up" — bottom to top, repeat

• "down" — top to bottom, repeat

• "updown" — up then down (includes top and bottom twice)

• "downup" — down then up

• "random" — random chord tones

• "chord" — play full chord on each step (block chords) rate: Note rate: "32" (32nd), "16" (16th), "8" (8th), "4" (quarter), "16t" (16th triplet). octave: MIDI octave for the chord root (4 = C4=60). steps: Number of arpeggio steps (default 16 = one bar of 16th notes). unit_index: AU index with a note track. track_index: Note track index within the AU. start_beat: Where the arpeggio starts (0 = bar 1). velocity: Note velocity 0-1 (default 0.65 for arpeggios).

Returns the total notes created and pitches used.

Create a musically varied section — not a repeat, a real variation.

Unlike create_genre_sections (which repeats the same loop at different velocities), this tool applies actual musical transformations to each track independently:

• Drums: density control (0.3 = sparse, 1.0 = full, 1.5 = busy with ghosts)

• Bass: octave shift (bass_octave_shift = +1/-1/-2)

• Melody: inversion, transposition, retrograde, or fragment

• Track inclusion: skip drums/bass/harmony/melody independently

This lets you build a song where each section has real musical variation, not just energy changes. The drop has full drums, the breakdown has inverted melody + no bass, the bridge has sparse drums + octave-up bass.

genre: Any of the 14 arrangement genres (dnb/house/trap/techno/dubstep/ synthwave/trance/disco/afrobeat/rock/jazz/pop/funk/reggae). section_name: Label for this section (e.g. "verse2", "bridge", "drop2"). bpm: Override tempo (None = genre default). root: Override key (None = genre default). bars: Section length in bars (4-32, default 8). start_beat: Where this section starts in the timeline. velocity: Base velocity 0-1. drum_density: 0.3 = sparse (half notes removed), 1.0 = normal, 1.5 = busy (extra ghost notes between hits). bass_octave_shift: 0 = normal, +1 = octave up, -1 = octave down, -2 = sub. melody_transform: "none", "invert", "transpose:5", "transpose:-7", "reverse", "fragment", "octave_up", "octave_down". include_drums/include_bass/include_harmony/include_melody: Set False to skip that track (e.g. breakdown = no drums, no bass).

Returns notes per track and transformations applied.

Example:

Breakdown section: sparse drums, no bass, inverted melody

create_arrangement_variation("dnb", section_name="breakdown", drum_density=0.3, include_bass=False, melody_transform="invert", velocity=0.6)

Bridge: octave-up bass, retrograde melody

create_arrangement_variation("house", section_name="bridge", bass_octave_shift=1, melody_transform="reverse", start_beat=64, bars=4)

Create a new audio bus (aux bus) with its own audio unit and track.

Follows the upstream AudioBusFactory.createAudioBus pattern: creates AudioUnitBox (Aux) + AudioBusBox + TrackBox, wires them together. Uses separate editing.modify() blocks — pointer refer() inside box constructor fails due to deferred pointer update resolution.

name: Bus label.

Returns the new bus index.

Create an audio clip in the session view (clip launcher).

Audio clips are the session-view counterpart to audio regions. They appear in the clip launcher and can be triggered independently.

sample_id: The ID returned by mcp_opendaw_load_audio. unit_index: Audio unit index (default 0). clip_index: Slot index in the clip launcher (0, 1, 2, ...). track_index: Track index within the audio unit (default 0). bpm: Source BPM of the sample (for warp marker calculation).

Returns clip UUID and index.

Create a new audio track on the primary audio unit.

Create a single automation event at a specific position on a value track.

Adds a point to the automation curve with the given interpolation type. If an event already exists at the same position, its value is updated.

unit_index: AU index. track_index: Value (automation) track index. position_beats: Position in beats (float). value: Normalized value 0.0-1.0. interpolation: "none" (step), "linear" (ramp), or "curve" (custom slope). curve_slope: Slope for curve interpolation (0.0-1.0, 0.5 = linear). Only used if interpolation="curve".

Returns the created/updated event info, or error.

Create a Balkan additive meter pattern — asymmetric time signatures with unequal beat groupings.

Balkan music uses "additive" meters: time signatures like 7/8, 9/8, 11/8, 13/8 where the measure is divided into unequal groups of 8th notes. Unlike Western "odd time" (which counts uniformly), Balkan music groups beats into patterns like 2+2+3 (7/8), 2+2+2+3 (9/8), 2+2+3+2+2 (11/8). Each group has a distinct accent pattern, creating the characteristic "limping" feel.

The tapan (large frame drum, similar to daire/def) plays the bass pattern: a low hit at the start of each group, high hits on the internal beats. The accent structure is the defining feature — the groups are not equal, so the listener perceives a lopsided, driving rhythm.

meters: "7_8" — 7/8: groups 2+2+3. The most common Balkan meter. Found in Macedonian, Bulgarian, Greek folk music. Accents on 1, 3, 5. "9_8" — 9/8: groups 2+2+2+3. Used in Bulgarian horo, Greek kalamatianos. Accents on 1, 3, 5, 7. Longer "limp" at the end. "11_16" — 11/16: groups 2+2+3+2+2. Bulgarian krivo horo. Very asymmetric. "13_8" — 13/8: groups 2+2+3+2+2+2. Bulgarian elenino horo. Longest common additive meter. "7_8_sand" — 7/8: groups 3+2+2 (reversed). Sandansko oro, Macedonian. Different accent placement, "backwards" feel. "9_8_ska" — 9/8: groups 2+3+2+2. Deviationska variant.

variations: "classic" — Traditional tapan pattern. Kick on group starts, snare on internal beats, hi-hat on all 8ths. "modern" — Modern Balkan fusion (Shantel, Balkan Beat Box). Kick patterns more syncopated, added ghost snares. "wedding" — Wedding band style. Denser hi-hat, more snare fills, tapan rolls at cycle end.

Args: meter: Meter name (7_8, 9_8, 11_16, 13_8, 7_8_sand, 9_8_ska). cycles: Number of measure cycles (1-32). variation: Pattern variation (classic, modern, wedding). velocity: Base velocity 0-1. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position. kick_pitch: Kick/tapan low MIDI pitch (36 = C1). snare_pitch: Snare/tapan high MIDI pitch (40 = E1). hh_pitch: Hi-hat MIDI pitch (42 = F#1). tapan_pitch: Tapan roll MIDI pitch (45 = A1).

Returns notes created, meter grouping, accent positions, and pattern info.

Create a bariolage — rapid alternation between a fixed pedal pitch and moving notes.

Bariolage is a Baroque string technique (Bach, Vivaldi, Handel) where a fixed note (typically an open string) rapidly alternates with moving notes that ascend, descend, or follow a melodic pattern. This creates a layered, cross-register texture — two streams of sound perceived simultaneously.

Unlike arpeggiator (cycles chord tones) or montuno (syncopated chord stabs), bariolage creates a two-voice illusion from a single voice: the pedal pitch acts as a drone/anchor while the moving notes create melodic interest above or below it.

Moving patterns: scale_asc — ascending scale notes scale_desc — descending scale notes scale_wave — alternating ascending/descending arpeggio — chord tones rotating chromatic — chromatic approach notes

Subdivisions: 8th, 16th, 32nd — determines speed of alternation

Args: root: Root note name (C, C#, D, ...). scale: Scale name (major, minor, dorian, mixolydian, harmonic_minor). bars: Number of bars (1-8). octave: Starting MIDI octave (2-6). pedal_pitch: MIDI pitch for the fixed pedal note. If -1, uses root at the specified octave (e.g., G4 = 67). moving_pattern: Pattern for moving notes (scale_asc, scale_desc, scale_wave, arpeggio, chromatic). subdivision: Note subdivision (8th, 16th, 32nd). velocity: Base velocity for moving notes 0-1. pedal_velocity: Velocity for pedal notes 0-1 (usually louder). accent_pedal: If True, pedal notes get accent (slightly louder). unit_index: AU index. track_index: Note track index. start_beat: Starting beat position.

Returns notes created, pedal/moving note counts, and pattern info.

Create a bass drop — descending pitch sweep into sustained sub bass.

Generates a pitched sweep downward (the "wub" or "fall") followed by a sustained low note. The quintessential dubstep/bass music drop. Also works for EDM build-and-drop, trap bass falls, and impact transitions.

The tool creates two phases:

1. Sweep phase: notes descend from start_pitch to end_pitch over sweep_beats

2. Hold phase: a single sustained note at end_pitch for hold_beats

start_pitch: Starting MIDI pitch for the sweep (default 48 = C3). end_pitch: Landing pitch for the sustained bass (default 24 = C1, sub bass). sweep_beats: Duration of the descending sweep in beats (0.5-8, default 2). hold_beats: Duration of the sustained bass after landing (0-16, default 4). sweep_curve: Pitch curve — "linear" (even), "exp" (fast start, slow landing), "log" (slow start, fast landing). unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the drop begins. velocity: Base velocity (0-1, default 1.0 = maximum impact).

Returns notes created, sweep/hold details.

Create a bass line from a chord progression string.

The harmonic trio: create_chord_pads (sustained harmony) + create_arpeggiated_progression (melodic movement) + THIS (bass foundation). All three take the same "Am-F-C-G" string.

pattern: Bass pattern: "root" — root notes on beat 1 + 3, quarter notes (universal) "root_fifth" — root on 1, fifth on 3 (rock, pop) "walking" — 4 quarter notes per bar: root → passing → chord tone → approach to next root (jazz) "pedal" — one sustained root per chord (techno, house sub-bass) "octave" — root + octave in 8th notes (disco, funk) "root_octave" — root on 1, octave up on 3 (pop, rock power)

bars_per_chord: Bars per chord (default 4). octave: MIDI octave for bass (2 = C2=36, typical bass range). velocity: Note velocity (0-1, default 0.9 = strong bass). track_index: Track for bass (typically bass track = 1).

Example:

Jazz walking bass from ii-V-I-vi

create_bass_from_progression("Dm7-G7-Cmaj7-Am7", pattern="walking", octave=2)

Rock root-fifth from I-IV-V

create_bass_from_progression("A-D-E", pattern="root_fifth", octave=2, velocity=0.95)

House pedal sub-bass

create_bass_from_progression("Fm-Fm-Db-Ab", pattern="pedal", octave=1, bars_per_chord=4)

Disco octave bass

create_bass_from_progression("C-Am-F-G", pattern="octave", octave=2, velocity=0.9)

Create a bassline from root note + rhythmic pattern — one call instead of 8-20 create_note calls.

Basslines use low octaves (default octave 2 = C2=36) and high velocity (default 0.9).

root: Root note name (C, C#, D, D#, E, F, F#, G, G#, A, A#, B or flats Db, Eb, Gb, Ab, Bb). pattern: Rhythmic pattern using scale degrees and special chars. Each step = one 16th note:

• Numbers 1-7 = scale degree (1 = root, 5 = fifth, etc.)

• 0 = rest

• '-' = sustain previous note (tie)

• '+' = octave up for next note

• '_' = octave down for next note

• Example: "1 - - - 5 - - - 1 - - - 4 - - -" = root-fifth-root-fourth bassline

• Example: "1 0 1 0 5 0 5 0 1 0 1 0 3 0 3 0" = syncopated bass unit_index: AU index with a note track. track_index: Note track index within the AU. start_beat: Where the bassline starts (0 = bar 1). octave: MIDI octave for the root (2 = C2=36, typical bass range). velocity: Note velocity 0-1 (default 0.9 for strong bass). scale: Scale type for degree mapping (default "minor"). Same scales as create_melody.

Returns the total notes created and pitches used.

Create binary form — two contrasting sections (A|B) with optional repeats.

Binary form is the simplest structural form in Western music: two self-contained sections, each typically repeated. The A section establishes the tonic, the B section departs and returns. Found in Baroque dance suites (Bach, Handel), folk tunes, early jazz, and many pop structures.

Modulation types (how B section relates to A):

• dominant: B section in the dominant key (V). Classical approach — Bach two-part inventions, Baroque dance movements.

• relative: B section in the relative minor/major. Romantic and folk approach — gentler contrast.

• subdominant: B section in the subdominant (IV). Church hymns, modal folk tunes.

• parallel: B section stays in same key but uses contrasting melodic material. Minimalist/folk approach.

• no_modulation: B section identical key, same harmonic center.

With repeat=True, each section is played twice (AABB structure), matching the traditional binary form with repeat marks.

A section: stepwise melody around tonic, I-V-I harmony. B section: contrasting melody in modulated key, wider intervals, returns to tonic at end.

Creates melody on track_index, bass on track_index+1.

Create a full blues arrangement — shuffle drums + walking bass + dominant 7th chords + blues scale lead.

Classic 12-bar blues — the foundation of American popular music:

• Track 0: Drums — shuffle/blues groove: kick on 1 and 3, snare on 2 and 4, shuffled hi-hats (triplet feel). The blues shuffle is the heartbeat — not straight 8ths, not full triplets, but the in-between "swing" that makes blues feel like blues.

• Track 1: Bass — walking bass: quarter notes outlining the chord changes. I-I-I-I | IV-IV-I-I | V-IV-I-V. Each beat walks to the next chord tone — the jazz/blues lineage.

• Track 2: Chords — dominant 7th voicings (I7, IV7, V7). The blues doesn't use triads — every chord is a 7th. Stab pattern on beats 1 and 3, with shuffle feel.

• Track 3: Lead — blues scale (root, b3, 4, b5, 5, b7) with blue notes. Bends, slides, long held notes. The "crying guitar" quality — pentatonic minor with the flat 5 blue note for tension.

At 120 BPM (default), this is the classic Chicago blues tempo. At 90 BPM, it's a slow blues (B.B. King). At 140, it's a fast shuffle (Stevie Ray Vaughan).

The 12-bar form: I-I-I-I-IV-IV-I-I-V-IV-I-V. This is the most important chord progression in popular music — the DNA of rock, jazz, soul, and R&B.

bpm: Tempo (70-160, default 120 = classic Chicago blues). bars: Arrangement length (must be multiple of 12 for full blues form. 12 = one chorus, 24 = two choruses, default 12). root: Root note (A is the most common blues key — guitar-friendly). octave: MIDI octave for bass (2 = A2=45, standard blues bass register). unit_index: AU index with note tracks. drum_track / bass_track / chord_track / lead_track: Track indices.

Returns notes created per track and total.

Example: create_blues_arrangement(bpm=120, root="A", bars=12) create_blues_arrangement(bpm=90, root="E", bars=24) # slow blues, 2 choruses

Create a boom-bap hip-hop drum pattern — the foundational beat of hip-hop.

Boom-bap: "boom" = kick drum, "bap" = snare. The pattern places kicks on beats 1 and 3, snares on beats 2 and 4 — the backbone of hip-hop from Run-DMC to Nas to Kendrick Lamar. Hi-hats fill the 8th or 16th notes between. The feel comes from swing/groove and kick placement variations.

boom_bap_type: "classic" — 90s boom-bap: kick on 1 and 3, snare on 2 and 4, hats on every 8th. The "Untitled" / Nas "Illmatic" feel. 2-bar cycle with kick variation on bar 2. "old_school" — 80s old school: simpler, kick strictly on 1 and 3, snare on 2 and 4, hats on quarter notes. Run-DMC / LL Cool J style. Less syncopation. "trap" — Trap: rolling hi-hats (16ths with occasional triplets), kick on 1 and "and of 2" and 3.5, snare on 4 only. Faster hats. Migos / Future style. "lofi" — Lo-fi hip-hop: laid-back, kick slightly behind beat (0.95 and 2.95), snare on 2 and 4, hats on 8ths with subtle swing. J Dilla / Nujabes feel. "drill" — UK drill: sliding bass kicks, snare on 3 only, chaotic hi-hat patterns with rolls. Headie One / Central Cee style. More aggressive kick patterns.

bars: Pattern length (2-16, 2 = one boom-bap cycle). kick_pitch: MIDI pitch for kick (36 = C1). snare_pitch: MIDI pitch for snare (38 = D1, acoustic snare). hat_pitch: MIDI pitch for hi-hats (42 = F#1, closed hat). velocity: Base velocity 0-1. Ghost hats -0.2, snares -0.05.

Returns notes created, boom-bap type, and stroke breakdown.

Example: create_boom_bap(boom_bap_type="classic", track_index=0) create_boom_bap(boom_bap_type="lofi", track_index=1, bars=4)

Create a bordun — continuously sustained drone chord as a textural layer.

A bordun (bourdon) is a continuously sounding tone or chord that provides a harmonic foundation beneath changing melody. Unlike pedal_point (which is a single repeated/anchored note), the bordun is a sustained textural layer — often an open fifth, octave, or drone chord. Found in Scottish bagpipes, Indian tanpura, hurdy-gurdy, ambient drone music, and folk.

root: Root note name (e.g. "C", "Ab", "F#"). octave: Octave for the bordun (1-6, default 3 = low register). intervals: Comma-separated semitone intervals from root (e.g. "0,7" = open fifth, "0,7,12" = octave+fifth, "0,3,7" = minor triad drone, "0,5" = open fourth). bars: Total length in bars (1-16, default 4). beats_per_bar: Time signature beats (3/4=3, 4/4=4, 6/8=6, default 4). velocity: Velocity of bordun notes (0-1, default 0.55 — softer than melody). retrigger_bars: If >0, re-triggers the bordun every N bars (e.g. 2 = retrigger every 2 bars). If 0, one continuous sustained note for entire duration. unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the bordun begins.

Returns notes created, pitches, total duration.

Create a classic drum break — the foundation of jungle, DnB, hip-hop, breakbeat.

Generates iconic drum break patterns from presets, with optional variation and swing. Each preset is a 1-bar pattern that can be repeated for multiple bars.

break_type: Classic break pattern preset.

• "amen" — Amen Break (The Winstons, 1969). The most sampled break in history. Kick on 1 and 3, snare on 2 and 4, with syncopated ghost.

• "think" — Think Break (Lyn Collins, 1972). Kick on 1, 1.75, 3.25 — distinctive off-beat kick pattern.

• "ashanti" — Ashanti Roosevelt break. Kick on 1, 2, 3.25 — funky displaced kicks.

• "funky_drummer" — Clyde Stubblefield break (James Brown). Straight kicks, dense 16th hi-hats.

• "when_the_levee" — When the Levee Breaks (Led Zeppelin). Heavy kick/snare, sparse hi-hat. The boom-bap template.

• "synthetic" — Electronic breakbeat. Off-beat hi-hats, four-on-the-floor kick. bars: Number of bars to generate (1-8, default 1). Each bar is a repeat with optional variation. variation: Per-bar variation mode.

• "none" — exact repeat

• "fill" — last bar gets a fill (denser snare/hihat)

• "humanize" — subtle timing/velocity variation per bar

• "drop" — last bar drops the kick (tension before drop) unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the break starts. swing: Swing amount (0.0-0.65, 0 = straight, 0.58 = classic hip-hop swing).

Returns notes created, break type, and bars.

Create a breakbeat pattern — the syncopated skeleton of jungle, DnB, big beat, and breakbeat hardcore.

Breakbeats are "broken" drum patterns where the snare and kick don't sit on clean quarter notes. Instead they syncopate, stutter, and displace — creating the forward-leaning momentum that powered hip-hop's early years (Amen break), then jungle/DnB (160-180 BPM chopped breaks), big beat (Fatboy Slim, Prodigy), and UK garage/2-step.

breakbeat_type: "amen" — The Amen break: G.C. Coleman's performance in The Winstons "Amen, Brother" (1969). The most sampled 6-second loop in history. Kick at 0, 2.66; snare at 1, 3; ghost snare at 2.66. Hats on 8ths. The DNA of jungle and DnB. "dnb" — Drum & bass: chopped Amen-style at DnB tempo. Kick on 0 and 2.5, snare on 1 and 3, rapid 16th hats, ghost snares on the "e" and "a". Rolling, driving. Andy C / Noisia style. "big_beat" — Big beat: mid-tempo (120-130) fat breaks. Kick on 0 and 2.66, snare on 1 and 3, with a kick+snare syncopation on beat 2. Big, swaggering. Fatboy Slim / Prodigy "Firestarter". "2_step" — UK garage 2-step: kick on 1 and 3, snare on 2 and 4, but the second kick is shifted to 2.66 and there's a ghost snare on 3.5. Swung 16ths. The "skipping" feel. MJ Cole / Disclosure style. "funky_drummer" — Clyde Stubblefield's break from James Brown "Funky Drummer" (1970). Kick at 0, 2, 2.66; snare at 1, 3; hats throughout with ghost notes. The most funk-sampled break. Public Enemy, NWA, LL Cool J all built on this.

bars: Pattern length (2-16, 2 = one breakbeat cycle). kick_pitch: MIDI pitch for kick (36 = C1). snare_pitch: MIDI pitch for snare (38 = D1). hat_pitch: MIDI pitch for hi-hats (42 = F#1). ghost_pitch: MIDI pitch for ghost snares (37 = F#1, side-stick). velocity: Base velocity 0-1. Snares -0.05, hats -0.15, ghosts -0.3.

Returns notes created, breakbeat type, and stroke breakdown.

Example: create_breakbeat(breakbeat_type="amen", track_index=0) create_breakbeat(breakbeat_type="dnb", track_index=1, bars=4)

Create a complete build-up — riser + snare roll in one call.

Combines two transition elements for a full build-up before a drop/chorus:

1. Pitch riser (ascending notes with velocity ramp)

2. Snare roll (increasing density + velocity crescendo)

style: Build-up character:

• "edm" — 1/4 snare → 1/8 → 1/16 → 32nd roll, exp riser C2→C6

• "trap" — 1/4 snare → triplets → 32nd roll, exp riser C1→C5

• "techno" — ride cymbal buildup + open hat crescendo, exp riser C2→C4

• "rock" — tom roll buildup, linear riser C2→C4

• "minimal" — just riser, no snare roll (subtle build)

unit_index: AU index (-1 = find first AU with note tracks). track_index: Note track index for riser. start_beat: Where the build-up begins. length_beats: Total build-up length (default 8 = 2 bars). velocity: Base velocity (0-1, ramped up during build).

Returns notes created for riser and snare roll.

Example:

8-beat EDM build-up before a drop

create_buildup(start_beat=0, length_beats=8, style="edm")

Then drop

create_impact(start_beat=8, impact_type="sub_boom")

Create a cadenza — an unmeasured virtuosic solo passage with rubato.

A cadenza is a solo passage where the performer has rhythmic freedom. Unlike all other tools that use quantized beat grids, cadenzas use irregular, speech-like rhythm — accelerando, rallentando, fermatas, and dramatic pauses. The notes follow a virtuosic contour: rapid runs, wide leaps, trills, and dramatic peaks.

Styles: classical — Mozart/Beethoven style: balanced phrases, cadential trills romantic — Liszt/Chopin style: dramatic octaves, cascading runs jazz — Coltrane/Parker style: bebop lines, chromatic turns modern — Ligeti/Berio style: extreme registers, clusters

The cadenza is built from segments, each with its own tempo character:

• Flourish: rapid ascending/descending run

• Leap: dramatic wide interval jump

• Trill: alternating two pitches rapidly

• Fermata: held note with pause after

• Cascade: descending arpeggio pattern

• Climb: gradual ascending with crescendo

Args: root: Root note name (C, C#, D, ...). scale: Scale name (major, minor, harmonic_minor, etc.). duration_beats: Approximate total duration in beats (4-64). octave: Starting MIDI octave (2-6). style: Cadenza style (classical, romantic, jazz, modern). virtuosic: If True, more rapid passages and wider leaps. breath_marks: Comma-separated beat positions for pauses/breaths. velocity: Base velocity 0-1 (cadenzas have wide dynamic range). unit_index: AU index. track_index: Note track index. start_beat: Starting beat position.

Returns notes created, segment breakdown, and cadenza statistics.

Create call-and-response — two phrases in musical dialogue.

Call-and-response is the most fundamental musical conversation: a leader phrase (call) followed by a response phrase. Root of blues, gospel, African music, jazz, work songs, and hip-hop.

Response types:

• echo: exact repeat of the call (African tradition, gospel)

• transpose: repeat transposed by response_interval semitones (blues, jazz — response at IV or V)

• variation: same pitches, varied rhythm (jazz, bebop)

• complementary: contrasting phrase using scale degrees (gospel, soul — response "answers" the call)

• fill: shorter response — last note only, or 2-note fill (blues turnaround, funk fills)

Call pattern: space-separated scale degrees (0=root, 2=2nd, etc.). Call rhythm: space-separated durations in beats. Response interval: for transpose type, semitones to shift (5 = perfect 4th up, 7 = perfect 5th up, -5 = 4th down). Pairs: number of call-response pairs. Gap beats: silence between call and response.

Creates call on track_index, response on track_index+1.

Create a call-and-response pattern — antecedent/consequent phrase structure.

The call (antecedent) poses a musical question, the response (consequent) answers it. This is the foundation of blues, jazz, hip-hop, electronic, and folk music. The pattern alternates: call → response → call → response, with the response starting after the call ends.

scale: Scale type (major, minor, blues, dorian, etc. — 14 types from music_theory). root: Root note name (C, C#, D, ... B). call_pattern: Scale degrees for the call phrase, space-separated (1-7, 0=rest, -=sustain). Example: "1 3 5 3" — rising and falling 4-note motif response_pattern: Scale degrees for the response phrase, space-separated. Example: "5 4 3 2" — descending answer repeats: Number of call+response pairs (1-8). 2 = call-response-call-response. octave: Starting octave (1-7, default 4). velocity: Note velocity 0-1. step_duration: Duration of each step in beats (0.25 = 16th, 0.125 = 8th triplet).

Returns total notes created and phrase structure.

Example: create_call_response(scale="blues", root="A", call_pattern="1 3 5 3", response_pattern="5 4 3 2", repeats=4)

Create a canon — strict melodic imitation with delayed voice entries.

The foundation of contrapuntal music: a single melody is repeated in multiple voices, each entering after a delay, optionally transposed. Think Pachelbel's Canon, "Row Row Row Your Boat", Bach's fugue subjects, or modern call-and-response layers in film scores. Unlike create_counterpoint (which generates a new line), a canon copies the SAME melody into each voice — just shifted in time and pitch.

melody: Comma-separated MIDI pitches of the lead voice (e.g. "60,62,64,67"). voices: Number of imitating voices (2-6, default 3). Voice 1 enters first. entry_delay_beats: Beats between each voice entry (1-16, default 4 = one bar in 4/4). transposition: Comma-separated semitone offsets per voice (e.g. "0,7,12" = unison, fifth, octave). Must have exactly voices values. "0,0,0" = all at same pitch (round/canon). velocity_decay: Velocity reduction per voice (0-0.3, default 0.15). Later voices are quieter, simulating natural ensemble hierarchy. direction: Voice entry order — "up" (low to high) or "down" (high to low). unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the first voice begins. velocity: Base velocity for the first voice (0-1, default 0.85).

Returns notes created, voice count, total length, transpositions used.

Create an Afro-Cuban cáscara pattern — the timbale shell rhythm that fills space around the clave.

Cáscara ("shell") is played on the sides of the timbale drums. It weaves between the clave and tumbao, filling the rhythmic gaps with a flowing, continuous feel. Together with clave and tumbao, it forms the three pillars of the Afro-Cuban rhythm section. The pattern uses two stroke heights: high (rim/edge, accented) and low (shell body, unaccented), creating a call-and-response within the pattern.

cascara_type: "son_3_2" — Son cáscara, 3-2 direction (forward clave). Bar 1: &2 high, 3 low, &3 high, &4 low Bar 2: &2 high, 3 low, &3 high, 4 low "son_2_3" — Son cáscara, 2-3 direction (reverse clave). Bar 1: &2 high, 3 low, &3 high, 4 low Bar 2: &2 high, 3 low, &3 high, &4 low "guaguanco" — Rumba guaguancó cáscara. Adds ghost strokes on beat 1 and &1 of each bar for a denser, more driving feel. "mambo" — Mambo cáscara. Adds syncopated accents on &4 of bar 2 and a fill on beat 4 of bar 2. Brighter, more showy.

bars: Pattern length (2 = one cáscara cycle, repeat for longer). high_pitch: MIDI pitch for high strokes (rim/edge of timbale, 76 = high wood block). low_pitch: MIDI pitch for low strokes (shell body, 60 = mid tom). velocity: Base velocity 0-1. High strokes +0.1, low strokes -0.05.

Returns notes created, cáscara type, direction, and stroke breakdown.

Example: create_cascara(cascara_type="son_3_2", track_index=0) create_cascara(cascara_type="guaguanco", track_index=1, bars=4)

Create a chaconne — repeating bass + chord progression + developing variations.

A chaconne is a set of variations over a repeating bass line and harmonic progression. Unlike ground bass (bass only) or passacaglia (bass + variations), a chaconne explicitly repeats both the bass AND the chord progression, building variations on top of this fixed harmonic framework.

Bass pattern: space-separated note names (e.g. "C2 G2 A2 E2"). Bass rhythm: space-separated durations in beats (e.g. "1 1 1 1"). Chord pattern: comma-separated chord names aligned with bass notes (e.g. "C,Em,Am,G"). Supports major, minor, dim, aug, maj7, m7, 7. Variation styles:

• baroque: descending stepwise lines with suspensions, ornaments accumulate

• romantic: wide intervals, expressive phrases, rubato-like timing

• jazz: syncopated, chromatic passing tones, swing-like rhythm

• minimalist: repeating cells with gradual phase shift

• contemporary: dissonant clusters, intervallic leaps, pointillistic

Creates bass on track_index, chord pads on track_index+1, variation on track_index+2.

Create a chop — slice source pitches into segments and rearrange them.

The quintessential hip-hop/EDM sampling technique: take a sequence of pitches, cut it into equal segments, then rearrange (reverse, stutter, shuffle, ping-pong). Think Dilla chops, Madlib sample flips, Virtual Riot bass chops, or glitch-hop stutter effects. Each segment becomes a self-contained musical cell.

pitches: Comma-separated MIDI pitches to use as source material (e.g. "60,62,64,67"). chop_mode: How to rearrange segments — "reverse" (play segments backwards), "stutter" (repeat each segment N times — glitch/stutter effect), "shuffle" (random segment order, seeded), "ping-pong" (forward then backward — ABBA pattern), "gate" (silence every other segment — chopped break feel). segment_beats: Duration of each segment in beats (0.25-4, default 0.5 = 8th note). stutter_count: For stutter mode, times to repeat each segment (2-8, default 2). octave_shift: Shift all pitches by N octaves (default 0). -1 = down an octave for bass chops. velocity_variation: Vary velocity between segments (0-0.5, default 0.2). Adds human feel. reverse_pitch_in_segment: If true, reverse pitch order within each segment (inner chop). unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the chop begins. velocity: Base velocity (0-1, default 0.9). seed: Random seed for reproducibility.

Returns notes created, segment count, mode used.

Create a 4-voice SATB chorale with voice-leading rules.

Generates soprano, alto, tenor, and bass voices from a chord progression with proper voice leading: common tones preserved, smooth voice movement (no unnecessary leaps), no parallel fifths or octaves between adjacent chords, and voices stay within their ranges (S: 60-81, A: 55-74, T: 48-67, B: 36-62). The soprano voice gets the melody line (chord roots or nearest chord tones). Classic Bach chorale style — foundational for vocal harmonies, string arrangements, synth pad layering.

chord_pattern: Comma-separated chord names (e.g. "C,Am,F,G"). Supports: maj, min, m7, maj7, dom7, sus2, sus4, dim, aug. beats_per_chord: Duration of each chord in beats (default 4 = 1 bar in 4/4). beats_per_bar: Time signature beats (3/4=3, 4/4=4, 6/8=6, default 4). key_root: Key root note for voice-leading context (e.g. "C", "F#", "Bb"). key_mode: Key mode — "major" or "minor" (affects voice assignment). soprano_velocity: Velocity of soprano voice (0-1, default 0.7). alto_velocity: Velocity of alto voice (0-1, default 0.6). tenor_velocity: Velocity of tenor voice (0-1, default 0.6). bass_velocity: Velocity of bass voice (0-1, default 0.65). note_duration: Note duration as fraction of chord length (0-1, default 0.9). voice_spread: Extra spacing between voices in semitones (0-12, default 0). unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the chorale begins.

Returns notes created, chord count, voice ranges, voice-leading info.

Create chord pads from a human-readable progression string.

Unlike create_chord_progression (which takes JSON arrays), this takes a simple hyphen-separated string like "Am-F-C-G" — much easier for agents and humans to write. Generates sustained chord pads with configurable octave, velocity, and bars per chord.

progression: Hyphen-separated chords. Each chord is root+type: "Am" = A minor, "F" = F major, "Cmaj7" = C major seventh, "G7" = G dominant 7, "Dm7" = D minor 7, "Esus4" = E suspended 4. Supported types: maj, min, dom7, maj7, min7, sus2, sus4, add9, dim, aug. Default "Am-F-C-G" = i-VI-III-VII in A minor (synthwave/trance). "C-Am-F-G" = I-vi-IV-V in C major (pop). "Dm7-G7-Cmaj7-Am7" = ii-V-I-vi in C (jazz).

bars_per_chord: How many bars each chord lasts (default 4 = one chord per 4-bar phrase). 2 = faster changes, 8 = slow pads.

octave: MIDI octave for chord voicing (3 = C3=48, typical pad range). velocity: Note velocity (0-1, default 0.65 = soft pad). unit_index: AU index with note tracks. track_index: Track for chord pads (typically harmony track = 2). start_beat: Where the progression starts. note_duration: Note length in beats (default 3.8 = almost full bar with small gap for articulation).

Returns chords created, pitches per chord, total notes.

Example:

i-VI-III-VII in A minor (synthwave pads)

create_chord_progression("Am-F-C-G", bars_per_chord=4, octave=3)

ii-V-I-vi in C (jazz comping under)

create_chord_progression("Dm7-G7-Cmaj7-Am7", bars_per_chord=2, octave=3)

I-V-vi-IV in C (pop progression)

create_chord_progression("C-G-Am-F", bars_per_chord=4, octave=4, track_index=2, velocity=0.6)

Create a chord progression from chord names — one call instead of 15-50 note creations.

chords: JSON array of chord specs. Each chord is [root_note_name, chord_type]. Root names: C, C#, D, D#, E, F, F#, G, G#, A, A#, B (or flats: Db, Eb, Gb, Ab, Bb) Chord types: maj, min, dom7, maj7, min7, sus2, sus4, add9, dim, aug

Example: '[["C","min"],["F","min"],["G","dom7"],["C","min"]]'

unit_index: AU index with a note track. track_index: Note track index within the AU. start_beat: Where the progression starts (0 = bar 1). chord_duration: Length of each chord in beats (4 = one bar at 4/4).

Returns the total notes created and chord voicings used.

Create an Afro-Cuban clave pattern — the 5-note rhythmic skeleton that defines the feel.

The clave is not a drum pattern — it's a timeline pattern that all other rhythms align to. Every Afro-Cuban rhythm has a clave direction (3-2 or 2-3) that determines where the downbeats fall relative to the clave strokes.

clave_type: "son_3_2" — Son clave, 3-side first (forward clave). Beats: 0, 0.5, 1, 2.5, 3 "son_2_3" — Son clave, 2-side first (reverse clave). Beats: 0, 1.5, 3, 3.5, 4 "rumba_3_2" — Rumba clave, 3-side first. Last stroke shifted to 3.5 (and 2.5→2.66) "rumba_2_3" — Rumba clave, 2-side first. "bossa_nova" — Bossa nova clave. Beats: 0, 2.5, 3, 4.5, 5 (over 2 bars) "6_8" — 6/8 Afro-Cuban clave. 5 strokes across 2 bars of 6/8.

bars: Pattern length in bars (2 for son/rumba, 2 for bossa, 2 for 6/8). pitch: MIDI pitch for clave strokes (76 = high wood block). velocity: Velocity 0-1. duration: Note duration in beats.

Returns notes created, clave type, and direction (3-2 or 2-3).

Example: create_clave(clave_type="son_3_2", track_index=0) create_clave(clave_type="bossa_nova", track_index=1)

Create a colotomic structure — interlocking gong layers marking cyclic time.

Gamelan music uses colotomic instruments (gongs of different sizes) to mark the cyclic structure of a piece. Each gong level has its own periodicity, creating an interlocking temporal grid. The largest gong (gong ageng) marks the end of a full cycle, while smaller gongs subdivide it into sections. The melodic instruments (saron, bonang) fill in between the gong strikes.

Unlike polyrhythm (simultaneous conflicting meters) or additive rhythm (unequal groupings), colotomic structure is hierarchical: each layer subdivides the cycle at a different level, creating a nested temporal hierarchy. This is the foundation of Indonesian gamelan, Javanese klenengan, and Balinese ritual music.

Structures: slendro — 8-beat gong cycle (gongan): gong at beat 8, kenong at 4, kempul at 2+6, kethuk at every odd beat. Slendro scale. pelog — 16-beat gong cycle: gong at 16, kenong at 8+12, kempul at 4+12, kethuk at every 2 beats. Pelog-inspired. lancaran — 8-beat with doubled kethuk (faster surface rhythm) ketawang — 16-beat with half-speed gong (longer cycle feel)

Tempo density: sparse — gong layers only, no melodic fill medium — gong layers + basic saron (elaboration) dense — gong layers + saron + bonang (full interlock)

Args: root: Root note name (C, C#, D, ...). scale: Scale name (pentatonic_minor, pentatonic_major, major, minor). Default pentatonic_minor for slendro-like feel. cycles: Number of gongan cycles (1-8). octave: Starting MIDI octave (2-5). structure: Structure type (slendro, pelog, lancaran, ketawang). tempo_density: Density level (sparse, medium, dense). velocity: Base velocity 0-1. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position.

Returns notes created, gong layer breakdown, and cycle info.

Create Cuban comparsa — carnival procession percussion.

Comparsa is the percussion ensemble that accompanies Cuban carnival street processions (conga line). Rooted in Afro-Cuban tradition, it is the ancestor of salsa and modern Latin pop. The driving energy comes from layered conga drums with interlocking patterns.

Instruments (GM percussion mapping):

• Conga low (54) — tumbadora, bass tone

• Conga high (63) — quinto, slap tone

• Conga open (64) — conga open tone

• Clave (75) — wooden claves, the timeline

• Cowbell (56) — cencerro, driving pulse

• Maracas (70) — shaker

• Guiro (73) — scraped gourd

Styles:

• habanera: Classic Havana carnival. Conga pattern with clave 3-2, cowbell steady 8ths, maracas on offbeats. The street procession feel. 90-110 BPM.

• santiago: Eastern Cuba, rumba-influenced. More syncopated conga patterns, guiro scrapes, claves 2-3. Looser feel.

• matanzas: Rumba columbia roots. Quinto improvisation feel, open conga tones, sparse cowbell. Afro-Cuban spiritual energy.

• conga_line: Street procession — marching feel. Steady bass conga on every beat, quinto syncopation, cowbell accent pattern. Designed for dancing in a line.

• comparsa_moderna: Modern carnival — faster, denser, 16th-note maracas, driving cowbell, layered congas. Salsa-influenced energy.

Creates notes on track_index using GM percussion.

Create comping — rhythmic chordal accompaniment.

The most common accompaniment style in modern music: play chords in a rhythmic pattern rather than sustained blocks. Jazz piano comping, funk guitar chops, reggae skanks, country boom-chick, Neo-soul chords. Unlike create_chord_progression (sustained blocks) or create_stab (house stabs), comping gives each chord a rhythmic identity — the chord follows the groove.

chords: JSON array of chord specs, same as create_chord_progression. Each chord is [root_note_name, chord_type]. Root names: C, C#, D, D#, E, F, F#, G, G#, A, A#, B (or flats: Db, Eb, Gb, Ab, Bb) Chord types: maj, min, dom7, maj7, min7, sus2, sus4, add9, dim, aug Example: '[["C","min7"],["F","min7"],["G","dom7"],["C","min7"]]' rhythm: Rhythmic pattern string. Each char = one step of note_spacing beats: 'x' = play chord, '-' = rest, '.' = ghost (quiet chord) Default "x-x-x-x-" = off-beat eighths (classic jazz comping) "x--x--x-" = syncopated funk "x...x..." = boom-chick (country) "x-x-x-x-x-x-x-x" = reggae skank (every off-beat 16th) unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Where comping starts. chord_octave: MIDI octave for chord root (4 = C4=60). velocity: Base velocity (0-1, default 0.7). note_spacing: Duration of each rhythm step in beats (0.25=16th, 0.5=8th, default 0.5). syncopation: Probability of pushing a note slightly off-grid (0-0.5, default 0). Adds human feel — 0.1 = subtle, 0.3 = pronounced.

Returns notes created, chords played, rhythm pattern used.

Create a counter-melody (second melodic line) from a chord progression.

A counter-melody is a secondary melodic line that plays alongside the primary melody. It provides harmonic depth and contrapuntal interest without competing for the listener's attention.

This completes the harmonic quintet: chord_pads + arpeggiated_progression + bass_from_progression + melody_from_progression + THIS (counter-melody). Place on track 4 (default) to avoid clashing with melody (track 3).

pattern: Contrapuntal pattern: "contrary" — moves opposite to chord root motion (if root goes up, counter goes down). Classic species-1 counterpoint feel. "oblique" — one note sustained across the chord, changes only when the harmony forces it. Minimalist, drone-like. "parallel_third" — parallels the chord tones a third above. Sweet, consonant, pop/folk counter-melody. "parallel_sixth" — parallels the chord tones a sixth above. Open, spacious, cinematic. More independent than parallel third. "call_response" — answers after the melody would play: rests on beats 1-2, plays on beats 3-4. Antiphonal, gospel/soul feel.

bars_per_chord: Bars per chord (default 4). octave: MIDI octave (default 4 = below typical melody at 5). velocity: Lower than melody (0-1, default 0.6 = supportive, not competing). track_index: Track for counter-melody (default 4, above melody track 3).

Example:

Counter-melody below the lead

create_counter_melody_from_progression("Am-F-C-G", pattern="contrary", octave=4, velocity=0.6)

Cinematic parallel sixths

create_counter_melody_from_progression("Dm-G-C-Am", pattern="parallel_sixth", octave=4, velocity=0.55)

Gospel call-and-response

create_counter_melody_from_progression("C-Am-Dm-G", pattern="call_response", octave=5, velocity=0.65)

Generate a counter-melody in contrary motion to existing notes.

Reads notes from a melody and creates a counterpoint that moves in the opposite direction: when the melody goes up, the counterpoint goes down, and vice versa. Each note is offset by a fixed interval from the melody's midpoint pitch, then mirrored.

unit_index: Source AU index. track_index: Source note track index. region_index: Source region index. interval: Base interval in semitones between melody and counterpoint (default 7 = fifth). The counterpoint is placed interval semitones below the melody's average pitch, then each note is mirrored around that center. new_unit_index: Target AU index (-1 = create new synth track). new_track_index: Target note track index on the target AU. velocity: Velocity for counterpoint notes (default 0.6, quieter than melody).

Returns source notes read and counterpoint notes created.

Create a full country arrangement — boom-chick guitar + root-five bass + major pentatonic fiddle lead.

Classic country/Americana — the foundation of American roots music:

• Track 0: Drums — straight 8th backbeat: kick on 1 and 3, snare on 2 and 4, steady 8th hi-hats. Country drums are straight, not shuffled like blues — the groove comes from the guitar, not the drums.

• Track 1: Bass — root-five pattern: root on beat 1, fifth on beat 3. The classic country bass — simple, steady, and unmistakable.

• Track 2: Chords — boom-chick guitar: alternating bass note (beat 1) + chord strum (beat 2), bass note (beat 3) + chord strum (beat 4). Triads, not 7ths — country harmony is cleaner than blues. The boom-chick is the Carter Family/Johnny Cash pattern.

• Track 3: Lead — major pentatonic (root, 2, 3, 5, 6) with occasional blue notes (b3, b7). Fiddle-style: long sustained notes, fast scale runs, and bends. The crying fiddle quality.

At 120 BPM (default), this is a classic country two-step tempo. At 90 BPM, it's a country ballad. At 140, it's a fast bluegrass breakdown feel.

The I-IV-V progression: I-I-IV-I-V-I-IV-I (8 bars). Simple, direct, and the backbone of country, folk, and Americana.

bpm: Tempo (80-160, default 120 = classic country two-step). bars: Arrangement length (must be multiple of 8, default 8). root: Root note (G is the most common country key — guitar/capo friendly). octave: MIDI octave for bass (2 = G2=43, standard country bass register). unit_index: AU index with note tracks. drum_track / bass_track / chord_track / lead_track: Track indices.

Returns notes created per track and total.

Example: create_country_arrangement(bpm=120, root="G", bars=8) create_country_arrangement(bpm=90, root="D", bars=16) # ballad, 2 verses

Apply a crescendo or decrescendo to existing notes in a region.

Gradually changes note velocities from start_velocity to end_velocity across all notes in the region. Useful for building tension or fading out.

unit_index: AU index. track_index: Track index. region_index: Region index (-1 = first region). start_velocity: Starting velocity 0-1 (low = quiet beginning). end_velocity: Ending velocity 0-1 (high = loud end). curve: "linear", "exp" (exponential, starts slow), "log" (logarithmic, starts fast).

Returns number of notes modified and velocity range applied.

Create a cross-rhythm — multiple voices with independent period lengths creating shifting alignment.

Unlike polyrhythm (which divides one bar into n and m equal parts), cross-rhythm gives each voice its own period length in beats. The voices cycle independently, creating continuously shifting alignment patterns that only realign after the LCM of all periods.

African cross-rhythms, Steve Reich, Talking Heads, minimalism.

voices: Comma-separated period lengths per voice. E.g., "5,7,3" creates 3 voices with period 5, 7, and 3 beats respectively. 2-6 voices supported. bars: Total length in bars (1-16). The pattern cycles until bars×4 beats is filled. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position. duration: Note duration in beats. base_velocity: Base velocity 0-1. Each voice gets slightly attenuated (voice 0 = full).

Returns total notes created, voice periods, and alignment interval (LCM).

Common cross-rhythms: "5,7" — 5-beat vs 7-beat (African, shifts every 35 beats) "3,4,5" — triple cross-rhythm (minimalism) "4,5,6" — dense shifting pattern "3,5,7" — prime cross-rhythm (longest alignment cycle = 105 beats)

Example: create_cross_rhythm(voices="5,7", bars=8, track_index=0)

Create a dembow rhythm — the foundational beat of reggaeton and Latin dancehall.

The dembow is a 3-3-2 syncopated pattern that drives virtually all reggaeton and Latin dancehall music. It derives from the "Dembow" riddim by Bobby Dixon (1990, Jamaica) and was popularized in Puerto Rico. The pattern creates a distinctive galloping feel through its uneven grouping of 3+3+2 within a 4/4 bar. Every reggaeton track from Daddy Yankee's "Gasolina" to Bad Bunny's "Tití Me Preguntó" is built on this rhythm.

dembow_type: "classic" — Classic reggaeton dembow. Kick on 1 and 3, snare on 3.5, 4.5, 5.5 (the 3-3-2 gallop). 1-bar cycle. "dancehall" — Dancehall variant. Sparser, kick on 1 and 3, snare on 3.5 and 4.5. Less gallop, more pulse. "trap_latino" — Latin trap variant. Kick on 1, 3.5, and 4.75 (syncopated), snare on 2.5 and 4.5. More modern, less rigid. "perreo" — Perreo (old-school reggaeton). Denser snare pattern with ghost hits on 2.75 and 6.75. Rougher, underground feel. "urbano" — Urbano latino (modern fusion). Kick on 1, 3, 4.75, snare on 3.5, 4.5, 5.5. Blends reggaeton with trap.

bars: Pattern length (1-16, 1 = one bar cycle). kick_pitch: MIDI pitch for kick (36 = C1, acoustic bass drum). snare_pitch: MIDI pitch for snare (40 = E1, electronic snare). velocity: Base velocity 0-1. Ghost hits -0.2, main hits +0.05.

Returns notes created, dembow type, and stroke breakdown.

Example: create_dembow(dembow_type="classic", track_index=0) create_dembow(dembow_type="trap_latino", track_index=1, bars=4)

Create a full disco arrangement — four-on-floor + octave bass + string sustains + wah guitar across 4 tracks.

Classic 70s disco with the signature groove — fundamentally different from house (its descendant):

• Track 0: Drums — four-on-floor with 16th OPEN hats (not closed 8ths like house). Kick on every quarter, clap on 2 & 4. The 16th-note open hi-hat pattern is the disco signature — busier and more open than house's closed 8th hats. The groove that launched dance music.

• Track 1: Bass — SYNCOPATED OCTAVE bass: the "good times" bass line. Root on beat 1, then syncopated octave jumps on the "and" of beats 2 and 4. Not off-beat 8ths like house, not arpeggiated like synthwave — it's a melodic bass line with octave leaps. The bass IS the hook in disco.

• Track 2: Strings — sustained chord pads with octave doubling. Full bar sustain, lush and smooth. The orchestral element that separates disco from house — house uses stabs, disco uses sustained strings. Minor or major triad depending on chord.

• Track 3: Guitar — wah-wah chops: 16th-note rhythmic scratching with accent pattern. Root + minor seventh voicing (funk-influenced). The "chukka-chukka" that drives the groove. Different from reggae skank (off-beat only) — disco guitar plays ALL 16ths with accents.

Uses I-vi-IV-V progression (G-Em-C-D in G major) — the classic disco four-chord loop. Different from house (minor vamp), pop (I-V-vi-IV), rock (I-IV-V). Disco's progression is major-key and optimistic — the "feel good" sound of the 70s.

At 120 BPM (default), this creates the classic disco groove — the tempo that defined the genre. The syncopated octave bass and 16th open hats are the fundamental differences from all 13 other arrangements: house has off-beat bass stabs with closed 8th hats, disco has melodic octave bass with 16th open hats.

bpm: Tempo (110-130, default 120 = classic disco). bars: Arrangement length (4-16, default 8). Must be multiple of 4. root: Root note (G is a classic disco key — G major). octave: MIDI octave for bass (2 = G2=43, standard disco bass register). unit_index: AU index with note tracks. drum_track / bass_track / string_track / guitar_track: Track indices.

Returns notes created per track and total.

Example: create_disco_arrangement(bpm=120, root="G", bars=8) create_disco_arrangement(bpm=115, root="C", bars=16)

Create a West African djembe/dunun ensemble — cyclical ostinato with call-and-response.

West African drumming (Mali, Guinea, Senegal) is built on layered cyclical patterns. Three bass drums (dununs) play interlocking ostinato patterns that define the rhythmic foundation. The kenkeni (highest) plays the fastest cycle, the sangban (middle) plays the core pulse, and the dundunba (lowest) plays the slow anchor. A bell (kenken) plays the timeline — the reference pattern all drummers orient to. Two djembes play lead and accompaniment parts: djembe 1 improvises calls and echauffements (heating-up sections), djembe 2 plays a fixed accompaniment (accompagnement) that interlocks with the dununs.

Unlike samba (parade ensemble) or songo (drum kit), West African drumming is cyclical: the accompaniment loops indefinitely while the lead djembe improvises on top. The structure is call-and-response: the lead plays a signal (appel) and the ensemble responds, then the groove continues.

styles (traditional rhythms): "danza" — Malian welcoming rhythm. Kenkeni steady 8ths, sangban pulse on 1+3, dundunba on 2+4. Bell timeline E(3,2,3). Djembe 2 accompagnement: slap-tone-slap-bass. "kuku" — Guinean celebration rhythm. Kenkeni offbeat pattern, sangban syncopated, dundunba sparse. Bell E(7,12). Djembe 2: rolling 16th tone-slaps. "djole" — Sierra Leonean rhythm (originally on sikko drums). Kenkeni 16ths, sangban 3-3-2, dundunba on 1. Bell E(3,2,3). Djembe 2: spaced bass-slap pattern. "doundounba" — The "dance of the strong men" (Guinea). Sangban drives with a dense 16th pattern, dundunba on downbeats, kenkeni sparse. Bell E(3,2,3). Aggressive djembe 2.

bars: Pattern length (4-16, even). style: Rhythm name (danza, kuku, djole, doundounba). velocity: Base velocity (0-1). kenkeni_pitch: Kenkeni (high dunun) MIDI pitch (35 = B0). sangban_pitch: Sangban (mid dunun) MIDI pitch (36 = C1). dundunba_pitch: Dundunba (low dunun) MIDI pitch (38 = D1). djembe1_pitch: Lead djembe MIDI pitch (42 = F#1). djembe2_pitch: Accompaniment djembe MIDI pitch (46 = A#1). bell_pitch: Bell (kenken) timeline MIDI pitch (50 = D2).

Args: bars: Pattern length in bars (4-16, even). style: Rhythm style (danza, kuku, djole, doundounba). velocity: Base velocity 0-1. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position. kenkeni_pitch: Kenkeni MIDI pitch. sangban_pitch: Sangban MIDI pitch. dundunba_pitch: Dundunba MIDI pitch. djembe1_pitch: Lead djembe MIDI pitch. djembe2_pitch: Accompaniment djembe MIDI pitch. bell_pitch: Bell timeline MIDI pitch.

Returns notes created, instrument breakdown, and rhythm info.

Create a full drum & bass arrangement — drums + bass + pad across 3 tracks in one call.

This is the first multi-track genre arrangement tool. Instead of creating individual patterns, it generates a complete DnB section with all elements locked together:

• Track 0: Drums — chopped Amen-style breakbeat with kick, snare, hats, ghost notes

• Track 1: Bass — Reese-style bassline with sustained notes and syncopated stabs

• Track 2: Pad — sustained minor chord pad that creates harmonic foundation

The arrangement is tempo-aware: at 174 BPM (default), the patterns are optimized for the classic 170-180 DnB feel. The bass and drums lock rhythmically — bass sustains when drums break, stabs when drums roll.

bpm: Tempo (160-185, default 174 = classic DnB). bars: Arrangement length (4-32, default 8 = typical section). root: Root note for bass and pad. octave: MIDI octave for bass (2 = C2=36). unit_index: AU index with note tracks. drum_track: Track index for drums. bass_track: Track index for bass. pad_track: Track index for pad. velocity: Base velocity 0-1.

Returns notes created per track and total.

Example: create_dnb_arrangement(bpm=174, root="A", bars=8) create_dnb_arrangement(bpm=170, root="F#", bars=16, drum_track=2, bass_track=3, pad_track=4)

Create a downtempo/trip-hop arrangement — 85 BPM Bristol sound.

Downtempo/trip-hop emerged from Bristol, UK (early 1990s) — a fusion of hip-hop breaks, dub bass, atmospheric samples, and melancholic vocals. Key characteristics:

• 80-90 BPM, laid-back, heavy groove

• Boom-bap drums with swing, vinyl crackle aesthetic

• Deep, melodic sub-bass with long notes

• Minor key, dark/jazzy harmony (m7, m9, half-diminished)

• Atmospheric pads, Rhodes piano, sparse melodies

• Sample-based, cinematic, nocturnal mood

Creates 5 tracks:

1. Drums (track_index): Boom-bap pattern — kick on 1 & 3, snare on 2 & 4, swung hats, ghost notes, occasional fills

2. Bass (track_index+1): Deep sub-bass with long sustained notes, melodic movement, octave drops

3. Chords (track_index+2): Minor 7th/9th Rhodes-style chords, sparse, on beat 1 of every 2 bars

4. Melody (track_index+3): Sparse, melancholic minor key melody with wide intervals and long rests

5. Atmosphere (track_index+4): Sustained pad notes, root and fifth, very low velocity, cinematic texture

Default key: D minor (classic trip-hop key — Portishead, Massive Attack).

Create a drum fill or transition pattern — one call replaces 10-30 note creations.

Generates rhythmic fills between song sections with increasing/decreasing density. Useful for transitions: verse→chorus, breakdown→drop, outro buildup.

fill_type: Type of fill:

• "build" — density increases toward end (leading into a drop/chorus)

• "break" — density decreases (winding down after a section)

• "roll" — sustained snare/tom roll with accents

• "crash" — crash + sparse hits for impact

• "tom" — descending tom pattern

bars: Length in bars (1-4). Each bar = 4 beats = 16 sixteenth steps. start_beat: Position in beats where the fill begins. density: Note density — "sparse", "medium", "dense".

unit_index: AU index with a note track (-1 = find first AU with note tracks).

Returns notes created per lane and total.

Create a drum beat from compact step-sequencer notation — one call replaces 10-20 note creations.

pattern: JSON object with drum lanes, each lane is a string where each char is a 16th-note step:

• 'x' = hit (velocity 0.9)

• 'o' = soft hit (velocity 0.5)

• '.' = rest

• 'X' = accent (velocity 1.0)

Lanes: kick, snare, hihat, clap, perc (each optional).

Example (4/4 house beat): '{"kick":"x...x...x...x...","snare":"....x.......x...","hihat":"....o...o...o..."}'

unit_index: AU index with a note track (-1 = find first AU with note tracks).

Returns the number of notes created per lane.

Create a genre-specific drum solo with rudimental vocabulary.

Generates a complete drum solo using vocabulary appropriate to the chosen style. Unlike create_drum_fill (short transition), this tool creates a full multi-bar solo with phrasing, build-ups, climax, and genre-specific rudimental patterns:

• rock: Thunderous 16th-note double kick patterns, crash accents, tom fills, snare ghost notes, building intensity. John Bonham, Neil Peart, Danny Carey.

• jazz: Brushes + sticks, comping patterns, ride bell, press rolls, polyrhythmic phrasing, trading 4s feel. Max Roach, Elvin Jones, Tony Williams.

• funk: Ghost-note heavy 16th-note grooves, hi-hat splashes, pocket fills, James Brown/Bootsy aesthetic. Clyde Stubblefield, Jabo Starks, Bernard Purdie.

• latin: Cascara, mambo bell, timbale fills, clave-based phrasing, 6/8 feel options. Tito Puente, Mongo Santamaria.

• marching: Rudimental solo — paradiddles, flams, drags, roll building, double-stroke open rolls. DCI, snare line vocabulary.

solo_type: rock | jazz | funk | latin | marching bars: Solo length (2-16, default 4) velocity: Base velocity 0-1 (drum solos are loud, default 0.9) seed: PRNG seed for reproducibility

Returns notes created and solo characteristics.

Example: create_drum_solo(solo_type="rock", bars=4) create_drum_solo(solo_type="jazz", bars=8) create_drum_solo(solo_type="marching", bars=4, seed=100)

Create a full dubstep arrangement — half-time drums + wobble bass + lead arp across 3 tracks.

Dubstep with all elements locked in half-time feel:

• Track 0: Drums — half-time at 140 BPM (feels like 70): kick on 1, snare on 3, with percussive fills and ghost notes. The signature dubstep swing.

• Track 1: Bass — wobble bass: sustained sub notes with rhythmic pitch shifts between root and octave/fifth, creating the "wub-wub" that defines the genre. Cutoff-sweep style pitch modulation via note offsets.

• Track 2: Lead — minor arpeggio that runs through the arrangement, atmospheric and dark, complementing the wobble bass.

At 140 BPM (default), half-time means the groove feels at 70 BPM — kick on beat 1, snare on beat 3 of each bar. This is the fundamental difference from all other electronic arrangements: the half-time feel creates the heavy, swinging groove.

bpm: Tempo (135-150, default 140 = classic dubstep). bars: Arrangement length (4-16, default 8). root: Root note (G is a classic dubstep key). octave: MIDI octave for wobble bass (1 = C1=24, sub-bass territory). unit_index: AU index with note tracks. drum_track / bass_track / lead_track: Track indices.

Returns notes created per track and total.

Example: create_dubstep_arrangement(bpm=140, root="G", bars=8) create_dubstep_arrangement(bpm=145, root="F", bars=16)

Create a full EDM arrangement — festival/mainstage 4-on-floor + supersaw + pluck + lead.

Electronic Dance Music — festival/mainstage sound:

• Track 0: Drums — 4-on-the-floor kick (every beat), claps on 2+4, open hats on offbeats, 16th closed hats for energy. Riser/snare buildup at end of 8-bar phrases.

• Track 1: Bass — offbeat bass (root on the "and" of each beat). Sub-bass frequency, driving, syncopated.

• Track 2: Supersaw synth — wide chord stabs on beats 1 and 3. Root position triads with spread voicings. The "wall of sound" — mainstage synth.

• Track 3: Lead synth — melody using scale degrees. Arpeggiated pattern with rhythmic repetition. The "hook".

F minor default — the most common EDM key (nice for both male and female vocals, sits well in club systems). 128 BPM (house/EDM standard). vi-IV-I-V progression (Fm-Db-Ab-Eb) — the "pop punk" progression that drives most festival anthems.

Create an electronic bassline pattern — genre-specific bass for dance music.

Electronic basslines are fundamentally different from melodic basslines: they're rhythmic engines that lock with the kick drum. Each genre has a characteristic bass technique that defines its sound.

bass_type: "house_offbeat" — House off-beat bass: sustained notes on the "&" of each beat (between kicks). The classic house bass that creates the "untz-untz-untz" feel. Frankie Knuckles / Detroit house. "techno_sub" — Techno sub-bass: one long sustained root per bar, minimal. Pure low-end energy. Berlin techno / Marcel Dettmann. "dnb_reese" — DnB Reese bass: sustained note on beat 1, then syncopated stabs on the "e" and "a" of beats 2-4. Dark, detuned. Noisia. "dubstep_wobble" — Dubstep wobble: quarters on 1+3, wub pattern on 2+4 with repeated 16ths and fifth movement. Skrillex / Excision. "acid_303" — Acid 303: fast 16ths alternating root/octave with fifth drops. TB-303 squelch. Phuture / Hardfloor. "garage_2step" — UK garage 2-step bass: notes on 1 and 2.66, ghost on 3.5. Bouncy, syncopated. MJ Cole / Disclosure.

bars: Pattern length (1-16). root: Root note name (C, C#, D, etc. or flats Db, Eb). octave: MIDI octave (2 = C2=36). velocity: Base velocity 0-1.

Returns notes created, bass type, and pitch info.

Example: create_electronic_bass(bass_type="house_offbeat", root="C", track_index=0) create_electronic_bass(bass_type="dnb_reese", root="A", track_index=1, bars=4)

Create a Euclidean rhythm — distributes k onsets across n steps as evenly as possible.

The Euclidean algorithm (BJK algorithm) generates most of the world's classic rhythms: E(3,8) = tresillo (Cuban, Arabic, 3-3-2) E(5,8) = cinquillo (Cuban) E(7,16) = samba, rumba E(7,12) = bembé (West African) E(2,5) = tresillo variant E(4,9) = Aksak (Balkan) E(3,7) = Persian/Arabic

onsets: Number of hits (k). 1-32. steps: Total number of steps (n). 2-64. Must be >= onsets. rotation: Rotate the pattern clockwise by N steps. 0 = no rotation. bars: Number of bars to repeat. Each step = one (4/steps)th of a bar. pitch: MIDI pitch for all hits. velocity: Velocity 0-1. Accents (first onset of each group) get +0.15. duration: Note duration in beats.

Returns notes created, pattern as binary string (1=hit, 0=rest), and Euclidean notation E(k,n).

Example: create_euclidean_rhythm(onsets=3, steps=8, track_index=0) # tresillo create_euclidean_rhythm(onsets=7, steps=16, pitch=38, track_index=1) # samba

Create a filter sweep on a Vaporisateur instrument's cutoff parameter with smart defaults.

The most common transition technique in EDM/techno/house. Sweeps the filter cutoff from closed to open (build-up) or open to closed (breakdown). Optionally boosts resonance during the sweep for that classic "talking filter" effect. Uses exponential curve by default (matches how human hearing perceives frequency changes).

unit_index: AU index with a Vaporisateur instrument. direction: "open" (low→high, build-up) or "close" (high→low, breakdown). start_beat: Start position in beats. duration_beats: Sweep length in beats (default 8 = 2 bars). start_cutoff: Starting cutoff value 0.0-1.0 (default: 0.05 for open, 0.85 for close). end_cutoff: Ending cutoff value 0.0-1.0 (default: 0.9 for open, 0.05 for close). resonance: Fixed resonance value 0.0-1.0 during sweep. Default: current value unchanged. resonance_boost: If True, automates resonance from current to +0.3 at sweep midpoint, then back down — classic filter sweep "whistle" effect. curve: "exp" (exponential, default — natural for filters), "linear", "log". steps: Number of automation points (default 32 = smooth).

Returns events created, sweep config, and a preview of the curve.

Examples: create_filter_sweep(unit_index=0, direction="open", duration_beats=16) → 16-bar filter open from 0.05 to 0.9, exp curve, resonance boost at midpoint create_filter_sweep(unit_index=2, direction="close", duration_beats=4, resonance_boost=False) → Quick 4-beat filter close, no resonance boost

Create a Flamenco compás — the cyclical rhythmic foundation of Flamenco.

Flamenco compás is the rhythmic cycle that defines each palo (form). Unlike Western meter (uniform bars), Flamenco uses a 12-beat cycle with accents on specific beats (typically 3, 6, 8, 10, 12). The accents create the characteristic Flamenco feel — a tension between the expected downbeat and where the accents actually fall.

The compás is marked by three layers:

1. PALMAS SECAS — Sharp, dry handclaps on accented beats. The "skeleton" of the compás. Loud, precise.

2. PALMAS SORDAS — Muffled handclaps on unaccented beats. The "flesh" — fills the gaps between secas. Softer, cupped hands.

3. CAJÓN — Peruvian box drum adapted to Flamenco. Plays the bass pulse, usually on beats 1 and the main accents. Resonant, deep.

4. GOLPE — Table tap / footwork accent. Sharp percussive hits for dramatic moments, often at the end of a compás cycle.

palos (forms): "bulerias" — 12 beats, accents on 12, 3, 6, 8, 10. Fast, festive. The most modern and popular palo. Starts on 12. "solea" — 12 beats, accents on 3, 6, 8, 10, 12. Slow, solemn. The "mother of Flamenco". Deep, expressive. "alegrias" — 12 beats, accents on 3, 6, 12 (lighter), 8, 10. Joyful. From Cádiz. Mid-fast tempo. "siguiriyas" — 12 beats, accents on 3, 6, 8, 11 (asymmetric grouping 3+2+3+2+2). Slow, tragic. The most jondo (deep) palo. "tangos" — 4 beats, accents on 1, 3. Simple 4/4 feel, the most accessible palo. Rhythmic, earthy. "rumba" — 4 beats, accents on 1, 2.5, 3 (syncopated). The most accessible Flamenco-pop form. Gypsy Kings style.

Args: palo: Flamenco form (bulerias, solea, alegrias, seguiriyas, tangos, rumba). cycles: Number of compás cycles (1-16). velocity: Base velocity 0-1. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position. palmas_secas_pitch: Palmas secas (sharp clap) MIDI pitch (39 = D#1). palmas_sordas_pitch: Palmas sordas (muffled clap) MIDI pitch (42 = F#1). cajon_pitch: Cajón (box drum) MIDI pitch (36 = C1). golpe_pitch: Golpe (tap) MIDI pitch (50 = D2).

Returns notes created, instrument breakdown, accent positions, and palo info.

Create a four-on-the-floor pattern — the foundational beat of house, techno, and disco.

Four-on-the-floor: kick drum on every quarter note (beats 1, 2, 3, 4). This is the pulse that defined dance music from disco (1970s) through Chicago house (1980s) to Berlin techno and beyond. The variation comes from what happens BETWEEN the kicks: off-beat hi-hats, claps on 2+4, percussion, and swing.

floor_type: "classic_house" — Chicago/Detroit house: kick on every quarter, open hat on off-beats (the "&" of each beat), clap on 2 and 4. The Frankie Knuckles / Roland TR-909 sound. 1-bar cycle. "deep_house" — Deep house: kick on quarters, shuffled hats, rimshot on 2/4, sparse percussion on the "e" and "a". Soulful swing. Larry Heard / Kerri Chandler style. "techno" — Detroit/Berlin techno: relentless kick on quarters, 16th hats, industrial clap on 2+4, metallic percussion on off-beats. Driving, minimal. Jeff Mills / Surgeson. "disco" — 70s disco: kick on quarters, open hat on off-beats, tambourine 16ths, conga fills. Giorgio Moroder / Donna Summer "I Feel Love" feel. "tech_house" — Tech house fusion: kick on quarters, swung hats, clap on 2/4, occasional vocal-style percussion stabs. Groovy but driving. Solardo / Fisher style.

bars: Pattern length (1-16, 1 = one bar cycle). kick_pitch: MIDI pitch for kick (36 = C1). hat_pitch: MIDI pitch for closed hi-hat (42 = F#1). open_hat_pitch: MIDI pitch for open hi-hat (46 = A#1). clap_pitch: MIDI pitch for clap (39 = D#1). perc_pitch: MIDI pitch for percussion (75 = high wood block / rim). velocity: Base velocity 0-1. Claps -0.05, hats -0.15, open hats -0.1, ghost -0.3.

Returns notes created, floor type, and stroke breakdown.

Example: create_four_on_floor(floor_type="classic_house", track_index=0) create_four_on_floor(floor_type="techno", track_index=1, bars=4)

Create a fugato — a fugal passage with subject entries and imitation.

A fugato is a fugal section (not a full fugue) that features subject entries in imitation: the subject is stated, then answered at a different pitch level, with optional countersubject and episodic material between entries. This is the building block of fugue writing — Bach, Handel, Shostakovich fugato passages.

Unlike create_voice_exchange (transforms existing notes between tracks), fugato generates the entire fugal texture from scratch:

• Subject: the main theme (custom or auto-generated)

• Answer: subject restated at answer_interval (real or tonal)

• Countersubject: a counter-melody against the answer

• Episode: connecting material between entries (sequenced motives)

Answer modes: real — exact transposition of the subject tonal — adjusted to stay within the key (5th scaled down)

Args: root: Root note name (C, C#, D, ...). scale: Scale name (major, minor, dorian, etc.). subject_notes: Custom subject as JSON array of [pitch_offset, duration_beats]. If empty, auto-generates a subject. pitch_offset is semitones from root. Example: [[0, 0.5], [2, 0.5], [5, 1.0], [4, 0.5], [2, 0.5], [0, 1.0]] bars: Total length in bars (4-16). octave: Starting MIDI octave (2-6). voices: Number of voices (2-4). answer_interval: Transposition interval for the answer in semitones. Default 7 = perfect fifth (standard fugue answer). answer_mode: Answer type (real or tonal). include_countersubject: If True, generates a countersubject. countersubject_interval: Starting interval of countersubject from answer pitch (semitones, can be negative). include_episode: If True, generates episodic material between entries. episode_bars: Length of episode sections in bars (1-4). velocity: Base velocity 0-1. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position.

Returns notes created, subject preview, voice entries, and fugato structure.

Create a fugue — polyphonic composition with subject, answer, and countersubject.

The most complex contrapuntal form. A subject (main theme) is stated in one voice, then imitated in others with a tonal or real answer. Optional countersubject provides contrasting counterpoint. Stretto mode overlaps voice entries for climactic density. Unlike create_canon (strict imitation), a fugue uses tonal answers (adjusted intervals) and independent countersubjects.

subject: Comma-separated MIDI pitches of the fugue subject (e.g. "60,62,64,65"). voices: Number of voices (2-5, default 3). More voices = denser counterpoint. entry_delay_beats: Beats between voice entries (2-8, default 4). answer_type: "tonal" (fifth up, adjusted) or "real" (exact transposition). countersubject: Comma-separated MIDI pitches of countersubject (optional). If empty, no countersubject. Must be same length as subject. key_root: Key root for tonal answer calculation (e.g. "C", "F#", "Bb"). key_mode: "major" or "minor" — affects tonal answer adjustment. note_duration: Note duration as fraction of beat (0-1, default 0.9 = legato). velocity: Base velocity for first voice (0-1, default 0.75). velocity_decay: Velocity reduction per voice (0-0.3, default 0.1). stretto: If true, later voices enter before previous finishes subject. unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the first voice begins.

Returns notes created, voice count, subject length, answer type, stretto status.

Create a complete genre track from zero to render-ready in one call.

Full pipeline: setup tracks → arrangement → harmonic layers (optional) → genre mix → mastering chain. One call replaces 5-10 individual tool calls with correct parameters.

Steps performed:

1. Set BPM to genre-appropriate default

2. Create a synth track + 4 note tracks

3. Create regions on all tracks

4. Call the genre arrangement (rhythm across all tracks)

5. If progression provided: add harmonic layers (arp + melody on top of genre rhythm; pads/bass skipped since genre already has them)

6. Apply genre-specific mix (compressor, EQ, saturation, reverb per track)

7. Apply sidechain (for electronic genres)

8. Add mastering chain (genre-appropriate LUFS target)

After this call, the project is ready for export_audio / render.

genre: One of: dnb, liquid_dnb, house, trap, techno, dubstep, afrobeat, rock, jazz, pop, funk, reggae, synthwave, trance, disco bpm: Override tempo (None = genre default). bars: Arrangement length (default 8, pop min 16). root: Override key (None = genre default). master_lufs: Mastering target (-14 Spotify, -10 loud, -16 Apple). progression: Chord progression string (e.g. "Am-F-C-G"). If non-empty, adds arp + melody harmonic layers on top of the genre rhythm. Pads and bass are skipped (genre arrangement already has them). Default "" = no harmonic layers (rhythm only). add_counter_melody: If True and progression is set, also adds a counter-melody layer (contrary motion). Default False. add_track_chains: If True, applies genre-appropriate processing chains to each track (drum chain on rhythm tracks, bass chain on bass, instrument chain on melodic). Default False.

Returns complete pipeline status: tracks created, notes per track, effects added, mastering chain, harmonic layers.

Example:

Full DnB track in one call

create_full_genre_pipeline("dnb")

Custom techno

create_full_genre_pipeline("techno", bpm=135, bars=16, master_lufs=-10)

House with harmonic layers

create_full_genre_pipeline("house", progression="Fm-Db-Ab-Eb")

Synthwave with full harmonic quintet

create_full_genre_pipeline("synthwave", progression="Am-F-C-G", add_counter_melody=True)

Create a full funk arrangement — funky drummer + slap bass + scratch guitar + horn stabs across 4 tracks.

James Brown / Parliament-Funkadelic style funk — vamp-based, not chord-progression-based:

• Track 0: Drums — "Funky Drummer" pattern (Clyde Stubblefield, most sampled break in history): syncopated kick with ghost notes, snare with strong ghost accents, hi-hat with 16th-note syncopation. The groove that built hip-hop.

• Track 1: Bass — slap bass: thumb (root, low) + pluck (octave/fifth, high) alternating, with dead notes (ghost) for percussive attack. The signature Larry Graham technique.

• Track 2: Guitar — "scratch guitar" / "chank": 16th-note muted strumming on a single chord, with accents on specific 16ths. The rhythmic glue that makes funk tick — Niles Rodgers style.

• Track 3: Horns — stabs: short, tight horn hits on the "and" of beats, responding to the vocal/instrumental lead. Brown-style section horn hits.

At 100 BPM (default), this creates the classic funk pocket — not too fast, deep in the groove. The vamp (one chord groove, not progression) is the fundamental difference from all other arrangements: pop/rock/jazz change chords, funk stays on one and makes it groove. 16th-note syncopation is the rhythmic DNA — every instrument plays 16ths with different accent patterns.

bpm: Tempo (90-115, default 100 = classic funk pocket). bars: Arrangement length (4-16, default 8). Funk vamps can go long. root: Root note (D is a classic funk key — D minor/D dominant). octave: MIDI octave for bass (2 = D2=38, standard funk bass register). unit_index: AU index with note tracks. drum_track / bass_track / guitar_track / horn_track: Track indices.

Returns notes created per track and total.

Example: create_funk_arrangement(bpm=100, root="D", bars=8) create_funk_arrangement(bpm=108, root="G", bars=16)

Create a full future bass arrangement — 4 tracks: drums + bass + chords + lead.

Future bass (Flume, San Holo, Illenium, ODESZA) blends electronic production with melodic/emotional sensibility. Key characteristics:

• 130-160 BPM, often major key (uplifting feel)

• Pitching snare rolls before drops (rising pitch + velocity crescendo)

• Big supersaw chords — wide, detuned, layered

• Sub-bass under chords, syncopated with kicks

• Vocal chop aesthetic — short rhythmic melodic fragments

• Sidechain pumping feel

• Bright, shimmering, nostalgic

Creates 4 tracks:

1. Drums (drum_track): Punchy kick on 1 and 3, snare on 2 and 4, 16th hats with rolls, and pitching snare roll at end of phrase (8 bars) — simulated by ascending pitch notes.

2. Bass (bass_track): Sub-bass following chord roots, syncopated gaps, octave drops. Sustained under chords.

3. Chords (chord_track): Big supersaw-style chords — major 7th / add9 voicings, wide voicings (root/third/seventh/ninth/octave), 2 bars per chord. I-V-vi-IV progression.

4. Lead (lead_track): Vocal-chop style melodic fragments — short rhythmic notes in major scale, catchy phrases, starts after 4 bars.

bpm: Tempo (120-170, default 150). bars: Arrangement length (4-32, default 8). root: Root note (default C = common future bass key). octave: MIDI octave for chords (3 = C3=48).

Example: create_future_bass_arrangement(bpm=150, root="C", bars=8) create_future_bass_arrangement(bpm=140, root="G", bars=16)

Create a UK garage arrangement — 130 BPM 2-step swing.

UK garage (UKG) is a British electronic genre evolving from US garage house with drum & bass influence. Key characteristics:

• 2-step drum pattern: kick on 1, snare on 2 & 4, skip beats

• Swing/shuffle feel (16th note swing)

• Chopped vocal stabs and chord stabs

• Deep bassline with melodic movement

• 130-138 BPM, 4/4 time

• Smooth, bumping, after-hours energy

Creates 4 tracks:

1. Drums (track_index): 2-step kick (beat 1, sometimes 3), snare on 2 & 4, swung hats, skip-beat ghost notes

2. Bass (track_index+1): Melodic bassline with octave jumps and syncopation, walking-ish movement

3. Chords (track_index+2): Stab chords on offbeats, major 7th and minor 9th voicings, Rhodes-style

4. Lead (track_index+3): Vocal-chop-style melodic stabs, short rhythmic phrases

Default key: G minor (common UKG key).

Create a multi-section electronic track from loop-based arrangements — intro → buildup → drop → breakdown → outro.

Transforms loop-based arrangements into song structure. Each section is a separate arrangement call with different start_beat and velocity, creating dynamic energy progression. For electronic genres only (dnb/house/techno/ trance/dubstep/synthwave/trap/disco).

Section energy progression:

• Intro (bars 0-N): drums only (kick + hat), no bass/melody. velocity * 0.5. Builds anticipation. Sparse and atmospheric.

• Buildup (bars N-2N): drums + bass, no harmony/melody. velocity * 0.7. Energy rising, groove established.

• Drop (bars 2N-3N): ALL tracks at full velocity. The climax — full arrangement with maximum energy. This is where the hook hits.

• Breakdown (bars 3N-4N): harmony + melody only, no drums/bass. velocity * 0.6. Pull back, breathe, create contrast before final drop.

• Outro (bars 4N-5N): drums + bass fading. velocity * 0.4. Wind down.

section_lengths: Comma-separated bar counts for each section. Default "4,8,8,8,4" = intro(4) + buildup(8) + drop(8) + breakdown(8) + outro(4) = 32 bars total. For a shorter track: "2,4,8,4,2" = 20 bars. For a longer track: "8,16,16,16,8" = 64 bars.

genre: Electronic genre only: dnb, house, techno, trance, dubstep, synthwave, trap, disco bpm: Override tempo (None = genre default). root: Override key (None = genre default). section_lengths: Comma-separated bar counts (5 sections, must sum to multiple of 4).

Returns sections created, notes per section, total notes, and energy profile.

Example:

32-bar DnB track with song structure

create_genre_sections("dnb", section_lengths="4,8,8,8,4")

64-bar trance epic

create_genre_sections("trance", section_lengths="8,16,16,16,8")

Create a genre-specific starting track with synth, beat, and basic mix — one call builds a full section.

genre: Musical genre preset:

• "house" — 4/4 kick, offbeat hat, stab bass, 128 BPM

• "techno" — driving kick, ride hat, acid bass, 130 BPM

• "lofi" — swing kick/snare, soft keys, 80 BPM

• "dnb" — breakbeat drums, sub bass, 174 BPM

• "trap" — 808 kick, hat rolls, melodic lead, 140 BPM

• "ambient" — pad chord, no drums, 70 BPM

• "coldwave" — driving kick, dark bass, 110 BPM

• "hiphop" — boom bap kick/snare, 90 BPM

bpm: Override tempo (default per genre).

Returns created AU indices, note counts, and suggested next steps.

Add ghost notes (quiet grace notes) to existing drum/MIDI patterns.

Ghost notes are very quiet notes placed between main hits, adding groove and complexity. Essential for funk, R&B, neo-soul, and hip-hop drumming. They fill spaces between snare/kick hits with subtle taps that make the beat feel alive.

Inserts new low-velocity notes at off-beat positions where no notes currently exist. Works on the first note track of the specified AU/track.

unit_index: AU index. track_index: Note track index (-1 = first note track). region_index: Region index (-1 = first region). density: Probability of adding a ghost note at each empty 16th position (0.2 = sparse, 0.5 = busy). velocity: Ghost note velocity 0-1 (0.25 = very quiet, 0.4 = audible). seed: Random seed for reproducibility.

Returns number of ghost notes added and positions.

Example: create_ghost_notes(unit_index=0, density=0.35, velocity=0.3, seed=99)

Create a glissando — smooth scale run between two pitches.

A continuous-sounding slide through intermediate pitches. Unlike riser/bass_drop (which are pitch sweeps), glissando plays every intermediate note at a fixed rate, creating a true scale run feel. Works chromatically (every semitone) or diatonically (scale tones only) or pentatonically.

start_pitch: Starting MIDI note (default 60 = C4). end_pitch: Ending MIDI note (default 72 = C5). Can be higher or lower. scale_type: "chromatic" (every semitone), "major" (diatonic major scale), "minor" (natural minor), "pentatonic_minor", "pentatonic_major", "whole_tone". duration_beats: Total duration in beats (0.5-16, default 2). rate: Note rate — "32nd", "16th", "8th", "32t", "16t". velocity: Base velocity 0-1 (default 0.8). velocity_curve: "flat" (constant), "ramp_up" (crescendo into landing), "ramp_down" (decrescendo), "arc" (peak in middle). unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the glissando begins.

Returns notes created, pitch list, scale type.

Create a full gospel arrangement — shuffle drums + walking bass + Hammond organ + choir.

Gospel music — the foundation of soul, R&B, and modern pop:

• Track 0: Drums — gospel shuffle. Kick on 1, snare on 2+4 with ghost notes, hi-hats with triplet shuffle feel. The "pocket" is deep — slightly behind the beat. Dynamics are expressive.

• Track 1: Bass — walking bass line through I-IV-V-I progression. Root → 3rd → 5th → approach note. Warm, supportive.

• Track 2: Hammond B3 organ — chord stabs with Leslie rotation feel. Triadic voicings, 2nd inversion common. The Hammond is the signature sound of gospel — drawbar harmonics.

• Track 3: Choir — sustained SATB voicings. Call-and-response with organ. Long notes, rich harmony, the "church" sound.

Ab major default — flat keys are traditional for gospel singers. I-IV-V-I progression (Ab-Db-Eb-Ab) with passing diminished approach. 6/8 or 4/4 at 70-85 BPM (slow groove).

Create a ground bass — a repeating ostinato bass line with optional melody.

The ground bass (basso ostinato) is one of the oldest composition techniques: a short bass pattern repeats throughout the piece while melodies above it change and develop. Used in baroque (Purcell's Dido's Lament, Bach's Crucifixus), chaconne/passacaglia tradition, jazz modal vamps, and film scoring (repeating tension ostinati).

Unlike passacaglia (which generates variations above the bass), ground_bass creates the pure repeating bass ostinato + a melody line that develops over the repetitions. The melody changes character per repetition cycle.

melody_styles: "baroque" — Stepwise descending lines over the ground. chromatic passing tones, suspensions on strong beats. Purcell/Bach style. Melody descends gradually across repetitions. "modal" — Modal jazz vamp style. Long sustained notes, sparse placement, emphasis on chord tones. Miles Davis / Kind of Blue aesthetic. Melody floats above the bass. "minimalist" — Steve Reich / Philip Glass style. Phase-shifted melodic fragments, repetitive cells, gradual transformation. Melody uses small intervals and repeating patterns. "film_tension" — Dark film scoring style. Minor 2nd and tritone intervals, dissonant suspensions, gradual crescendo. Melody builds tension across repetitions. "folk" — Strophic folk variation style. Pentatonic-leaning melody, simple rhythmic values, phrase repetition with slight variation. Celtic / English folk tradition.

Args: bass_pattern: Space-separated bass notes (e.g. "A2 E2 C2 G2"). Can use note names (A2, C3) or MIDI numbers (45, 52). bass_rhythm: Space-separated durations in beats for each bass note (e.g. "2 2 2 2" = 4 notes each lasting 2 beats = 8-beat cycle). repeats: Number of bass repetitions (2-32). melody_style: Melody character above the ground. unit_index: AU index. track_index: Note track index (bass goes here, melody on track_index+1). start_beat: Starting beat position. velocity: Base velocity 0-1.

Returns bass notes created, melody notes, cycle info, and style.

Create a hardstyle arrangement — 150 BPM festival hard dance.

Hardstyle is a Dutch electronic dance genre characterized by:

• Hard, distorted kick drum with a pitched tail (the signature sound)

• Reverse bass (off-beat bass that "reverses" the kick pattern)

• Screechy/sawtooth lead synth with wide unison

• 150 BPM, 4/4 time

• Aggressive, festival/headbanger energy

Creates 4 tracks:

1. Drums (track_index): Hard kick on every beat, snare on 2&4, closed hats on offbeats, open hat occasionally

2. Bass (track_index+1): Reverse bass pattern — bass on offbeats between kicks, creating the signature "boom-BM-boom-BM" feel

3. Lead (track_index+2): Screechy sawtooth lead playing a minor melody with wide intervals and octave jumps

4. Chords (track_index+3): Stab chords on beat 1 and 3, minor key

Default key: F minor (common hardstyle key).

Create all five harmonic layers from one progression string in one call.

Replaces 5 separate calls (chord_pads + arpeggiated_progression + bass_from_progression + melody_from_progression + counter_melody_from_progression) with a single call. All layers take the same "Am-F-C-G" progression and are placed on separate tracks: pads (track 2), arp (track 3), bass (track 1), melody (track 3 or 4), counter-melody (track 4 or 5).

By default arp and melody share track 3 (melody track). Set melody_pattern to "" to skip melody, arp_pattern to "" to skip arp, bass_pattern to "" to skip bass, pad_octave to -1 to skip pads, counter_melody_pattern to "" to skip counter-melody (default).

progression: Hyphen-separated chords (same format as the quartet tools). pad_octave: Octave for chord pads (default 3). arp_pattern: Arp pattern: up/down/updown/random/bass, or "" to skip. arp_octave: Octave for arp (default 4). arp_step: Arp step duration in beats (default 0.25 = 16th). bass_pattern: Bass pattern: root/root_fifth/walking/pedal/octave/root_octave. bass_octave: Octave for bass (default 2). melody_pattern: Melody pattern: chord_tones/sustained/syncopated/triadic/stepwise. melody_octave: Octave for melody (default 5). counter_melody_pattern: Counter-melody pattern: contrary/oblique/parallel_third/ parallel_sixth/call_response, or "" to skip (default ""). counter_melody_octave: Octave for counter-melody (default 4). bars_per_chord: Bars per chord (default 4). velocity: Base velocity for all layers (0-1).

Example:

Full synthwave harmonic arrangement in one call

create_harmonic_arrangement("Am-F-C-G", arp_pattern="up", bass_pattern="root", melody_pattern="chord_tones")

Jazz: walking bass + sustained pads, skip arp

create_harmonic_arrangement("Dm7-G7-Cmaj7-Am7", arp_pattern="", bass_pattern="walking", melody_pattern="sustained", bars_per_chord=2)

House: pedal sub-bass + pads, skip melody

create_harmonic_arrangement("Fm-Fm-Db-Ab", arp_pattern="bass", bass_pattern="pedal", bass_octave=1, melody_pattern="", pad_octave=3)

Full quintet with counter-melody

create_harmonic_arrangement("Am-F-C-G", arp_pattern="up", bass_pattern="root", melody_pattern="chord_tones", counter_melody_pattern="contrary")

Generate harmony parts from existing notes — thirds, fifths, sixths, octaves.

Reads notes from an existing region and creates harmonized copies at a fixed interval. Supports diatonic (scale-aware) and chromatic (fixed semitone) intervals. Output goes to a new or existing track.

unit_index: Source AU index. track_index: Source note track index. region_index: Source region index. interval: Harmony interval type:

• "thirds" — diatonic third above/below (3rd scale degree)

• "fifths" — diatonic fifth (5th scale degree)

• "sixths" — diatonic sixth (6th scale degree)

• "octave" — octave up/down (12 semitones)

• "fifth_chromatic" — perfect fifth (7 semitones, fixed)

• "fourth_chromatic" — perfect fourth (5 semitones, fixed)

• "third_major" — major third (4 semitones, fixed)

• "third_minor" — minor third (3 semitones, fixed) direction: "up" or "down" (harmony above or below the melody). new_unit_index: Target AU index (-1 = create new synth track for harmony). new_track_index: Target note track index on the target AU. velocity: Velocity for harmony notes (default 0.65, slightly quieter than melody).

Returns source notes read and harmony notes created.

Create a harmony line from an existing melody using diatonic intervals.

Reads notes from a source melody and creates a parallel harmony line at a specified diatonic interval. The harmony stays in key — each note is shifted by N scale steps (not semitones), producing consonant harmony automatically.

Harmony intervals (diatonic):

• third: +2 scale steps — the most common harmony (Lennon-McCartney, Everly Brothers, country duets). Sweet and consonant.

• sixth: +5 scale steps — wider, jazzier. Creates open, airy harmony.

• fifth: +4 scale steps — power harmony, medieval/organum sound.

• fourth: +3 scale steps — suspended, ambiguous. Gregorian/modal.

• octave: +7 scale steps (or -7) — doubling, not true harmony but useful for layering.

Essential for: vocal harmonies, string pads behind melody, guitar harmonies, counter-melody foundation, thickening lead lines.

source_unit/track/region: Location of the source melody. target_unit/track/region: Where to write the harmony. -1 = create new track/region automatically. interval: third, sixth, fifth, fourth, octave. root_note + scale: The key for diatonic interval calculation. The harmony notes are guaranteed to be in this scale. direction: "above" or "below" — place harmony above or below the melody. velocity_scale: Multiply source velocities by this (default 0.8 = harmony slightly quieter than melody).

Returns the created harmony notes.

Create a hemiola — 3:2 rhythmic displacement creating cross-rhythm illusion.

A hemiola superimposes a 3-note grouping over a 2-note grouping (or vice versa) within the same time span, creating the illusion of a different meter. The classic 3-against-2 pattern is fundamental to West African, Afro-Cuban, jazz, and minimalist music. Brahms, Bernstein, and Glass used it extensively.

The pattern string defines which beats get primary vs secondary emphasis: "3:2" — 3 primary notes in the time of 2 secondary (classic hemiola) "2:3" — 2 primary notes in the time of 3 secondary (inverse hemiola)

Creates notes on a single track: primary group uses primary_pitch, secondary group uses secondary_pitch. Both span the same total duration.

pattern: "3:2" (3 against 2) or "2:3" (2 against 3). bars: Total length in bars (1-4). Each bar = 4 beats. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position. primary_pitch: MIDI pitch for primary group (default 60 = C4). secondary_pitch: MIDI pitch for secondary group (default 64 = E4). primary_velocity: Velocity for primary notes 0-1. secondary_velocity: Velocity for secondary notes 0-1. duration: Note duration in beats.

Returns total notes created and hemiola ratio.

Example: create_hemiola(pattern="3:2", bars=2, primary_pitch=60, secondary_pitch=67)

Create a hocket — single melodic line split between voices/tracks.

Hocket (from Latin "hoquet" = hiccup) is a technique where a single melody is divided between two or more voices. Each voice plays only every other (or every Nth) note, creating an interlocking texture. Found in medieval polyphony (Notre Dame school), African mbira music, Balinese gamelan, and modern minimalist composition (Steve Reich).

melody: Comma-separated MIDI pitches forming the complete melodic line. voices: Number of voices to split between (2-4, default 2). split_mode: How notes are distributed: "alternate" — round-robin (note 0→voice 0, note 1→voice 1, ...) "pairs" — pairs of notes per voice (2 per voice, then switch) "phrase" — 4-note phrases per voice unit_index: AU index with note tracks (-1 = find AU with enough note tracks). track_index: Starting note track index (uses consecutive tracks for voices). start_beat: Position in beats where the hocket begins. note_duration: Duration of each note in beats (default 0.5 = eighth notes). velocity: Velocity of all notes (0-1, default 0.7).

Returns notes created, voice assignment, total duration.

Create a full house music arrangement — drums + bass + stabs across 3 tracks in one call.

House music arrangement with all elements locked together:

• Track 0: Drums — four-on-the-floor kick, open hats on off-beats, clap on 2+4

• Track 1: Bass — off-beat sustained bass between kicks

• Track 2: Stabs — short minor chord stabs on beats 1 and 3, with occasional off-beat stabs

At 124 BPM (default), this creates the classic Chicago/Detroit house feel. The bass and drums lock — bass hits exactly between kicks, creating the "untz-untz" groove. Stabs provide harmonic movement on top.

bpm: Tempo (115-135, default 124 = classic house). bars: Arrangement length (4-32, default 8). root: Root note for bass and stabs. octave: MIDI octave for bass (2 = C2=36). unit_index: AU index with note tracks. drum_track / bass_track / stab_track: Track indices.

Returns notes created per track and total.

Example: create_house_arrangement(bpm=124, root="C", bars=8) create_house_arrangement(bpm=128, root="F#", bars=16)

Create an impact — single hit transition element for drops and section changes.

Generates a single sustained note with type-specific pitch, duration, and velocity. Essential for EDM transitions: the "hit" that lands after a riser/build-up.

impact_type: Type of impact:

• "sub_boom" — deep sub bass hit (C1, long decay, dark)

• "impact_hit" — mid-range punch (C3, medium decay, aggressive)

• "downlifter" — descending pitch from high to low (glissando fall)

• "sub_drop" — lowest sub with long tail (B0, very long, cinematic)

• "punch" — short bright hit (C5, short decay, snappy)

unit_index: AU index (-1 = find first AU with note tracks). track_index: Note track index. start_beat: Position in beats where the impact lands. pitch: Base MIDI pitch (default 36 = C2, overridden by type). length_beats: Duration in beats (default 4 = one bar). velocity: Hit velocity (0-1, default 0.9 = loud).

Returns notes created and impact parameters.

Example:

Sub boom on the downbeat

create_impact(start_beat=0, impact_type="sub_boom")

Downlifter after riser

create_impact(start_beat=4, impact_type="downlifter", length_beats=2)

Create a new instrument audio unit with a Tape device and an audio track.

This is required for audio playback — the Tape device reads audio regions and outputs sound. The instrument AU is connected to the output AU's bus.

name: Display name for the instrument (default "Tape"). Returns the unit_index and track_index for use with place_audio_region.

Create an Irish traditional music accompaniment — bodhrán + feet for session tunes.

Irish traditional music (trad) is defined by its tune types, each with a characteristic meter and feel. The bodhrán (frame drum) and feet stomp provide the rhythmic foundation in a session. Unlike most percussion patterns, Irish accompaniment is minimal — the rhythm is carried by the melody's phrasing, and the bodhrán supports rather than drives.

tune types: "reel" — 4/4, straight 8th notes. The most common tune type. Bodhrán: downbeat + offbeat pattern. 4 beats per bar. 2 bars per phrase (AA pattern). Bright, driving. "jig" — 6/8, triplet feel. Groups of 3 eighth notes. Bodhrán: accent on beat 1 and 4 (the two downbeats of 6/8). 2 bars per phrase. Lilting, rolling feel. "hornpipe" — 4/4, dotted rhythm. 8ths are swung (long-short). Bodhrán: similar to reel but with swung feel. 2 bars per phrase. Bouncy, maritime feel. "slip_jig" — 9/8, triplet feel in 3 groups of 3. Rare, ethereal. Bodhrán: accent on 1, 4, 7. 2 bars per phrase. Dancing on air, Turlough O'Carolan style. "polka" — 2/4, fast and punchy. Common in Kerry/Sliabh Luachra. Bodhrán: strong 1 and 2. Simple, driving. 2 bars per phrase. Fast dance, march-like. "slide" — 12/8, similar to jig but faster and longer groups. Bodhrán: accent on 1, 4, 7, 10. 2 bars per phrase. Sliabh Luachra region. Fast, lilting.

Args: tune_type: Tune type (reel, jig, hornpipe, slip_jig, polka, slide). bars: Number of bars (4-32, even). velocity: Base velocity 0-1. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position. bodhran_pitch: Bodhrán (frame drum) MIDI pitch (36 = C1). feet_pitch: Feet stomp MIDI pitch (40 = E1). hh_pitch: Hi-hat/brush MIDI pitch (42 = F#1).

Returns notes created, tune type info, meter, and pattern breakdown.

Create an isorhythm — repeating rhythm (talea) × repeating pitch series (color).

Isorhythm separates rhythm and pitch into two independent cycles. The talea (rhythmic pattern) and color (pitch series) repeat independently, creating constantly shifting relationships as they go in and out of phase. When talea and color have different lengths, the pattern doesn't fully repeat until the least common multiple of both lengths.

Found in medieval motets (Machaut), and heavily influenced 20th-century composers — Messiaen, Boulez, Stockhausen. Distinct from ostinato, which repeats rhythm and pitch together as one unit.

talea: Comma-separated note durations in beats (the repeating rhythm). e.g. "1,1,0.5,0.5,1" = quarter, quarter, eighth, eighth, quarter. color: Comma-separated MIDI pitches (the repeating pitch series). e.g. "60,62,64,65" = C,D,E,F cycling independently of rhythm. repeats: Number of full talea cycles (1-16, default 3). velocity: Velocity of all notes (0-1, default 0.7). unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the isorhythm begins.

Returns notes created, talea/color lengths, phase cycle length, total duration.

Create a full jazz arrangement — swing drums + walking bass + comping piano + horn across 4 tracks.

Jazz with swing feel and ii-V-I harmony — fundamentally different from all other arrangements:

• Track 0: Drums — swing ride pattern (spang-a-lang), brush snare ghost notes, comping on bass drum. The signature jazz ride cymbal pattern with swung 8th notes — the triplet feel that defines jazz.

• Track 1: Bass — walking bass: quarter notes that walk through the chord changes using chord tones and approach notes. ii-V-I aware, creating smooth voice leading through the changes.

• Track 2: Piano — comping: syncopated chord stabs using shell voicings (root + third + seventh) and rootless voicings. Frequent rests — comping is about space as much as notes.

• Track 3: Horn — lead melody: a simple bluesy head over the changes, using blue notes (flatted thirds and fifths) and swing.

At 120 BPM (default), this creates a medium-up swing feel. The ii-V-I progression is the fundamental jazz chord change — every other genre uses different harmony. Swing 8ths (triplet feel) is the rhythmic signature that separates jazz from all straight-time genres.

bpm: Tempo (60-200, default 120 = medium swing). bars: Arrangement length (4-32, default 8). Jazz benefits from longer forms. root: Root note (F is a classic jazz key — great for horns). octave: MIDI octave for bass (2 = F2=41, standard jazz bass register). unit_index: AU index with note tracks. drum_track / bass_track / piano_track / horn_track: Track indices.

Returns notes created per track and total.

Example: create_jazz_arrangement(bpm=120, root="F", bars=8) create_jazz_arrangement(bpm=180, root="Bb", bars=12)

Create Indian Carnatic konokol (solkattu) — vocal percussion as MIDI.

Konokol (also spelled konnakkol) is the South Indian art of vocal percussion. Syllables represent rhythmic patterns: ta, ka, di, mi, thom, nam, ghu, dhi, khatam. Each syllable maps to a specific drum sound. This is the rhythmic foundation of all Carnatic music.

Styles (tala structures):

• adi_tala: 8-beat cycle (most common). Structure: 4+2+2. Syllables: ta-ka-dhi-mi ta-ka-dhi-mi ta-ka-ta-ka. The foundational tala of Carnatic music.

• roopaka_tala: 6-beat cycle (3/4). Structure: 3+3. Syllables: ta-ka-dhi ta-ka-dhi-mi. Used in lighter compositions, varnams.

• khanda_chapu: 5-beat cycle. Structure: 2+3. Syllables: ta-ka ta-ka-ta. Asymmetric, flowing feel. Common in kritis.

• mishra_chapu: 7-beat cycle. Structure: 3+2+2. Syllables: ta-ki-ta ta-ka ta-ka. Lyrical, song-like rhythm. Used in padams.

• triputa_tala: 7-beat cycle (3+2+2 variant). Syllables: ta-ka-dhi-mi ta-ka ta. Alternative 7-beat structure.

• jhampa_tala: 10-beat cycle. Structure: 4+2+4. Syllables: ta-ka-dhi-mi ta-ka ta-ka-dhi-mi. Used in javalis and tillanas.

GM percussion mapping (Indian fusion approach): 36 (kick) → thom, ghu (bass drum — low/open tones) 38 (snare) → nam, dhi (sharp, crisp) 42 (closed hat) → ta, ka (high, crisp) 43 (high floor tom) → mi (mid) 45 (low tom) → khatam (rolled)

Creates konokol notes on track_index. Includes syllable text in the result for reference.

Create a Korean traditional percussion ensemble — nongak (farmers' music).

Korean percussion (samul nori / nongak) uses four instruments representing weather elements:

1. JANGGU — Hourglass drum with two heads: chwe (left, low, deep) and kyeongbang (right, high, sharp). The most versatile Korean drum. Plays complex interlocking patterns with both hands simultaneously.

2. BUK — Barrel drum. Deep bass tone. Plays steady downbeats.

3. KKWAENGGWARI — Small hand gong. High, piercing metallic. The lead instrument — player (sangsoe) calls patterns and signals changes.

4. JING — Large gong. Deep, resonant, sustained. Plays sparse accents to mark phrase boundaries.

The four instruments represent: janggu = rain, buk = clouds, kkwaenggwari = thunder, jing = wind (lightning in some traditions).

styles: "nongak" — Farmers' music (rural tradition). Steady, driving. Janggu plays the basic nanajanggu pattern (alternating chwe/kyeong on 8th grid). Buk on downbeats. Kkwaenggwari on offbeats with accented calls. Jing on phrase starts. "samul_nori" — Modern stage version (1978, Kim Duk-soo). Faster, denser, more dramatic. Janggu plays 16th patterns with ghost notes. Kkwaenggwari has call-and-response. "binari" — Ritual/shaman opening piece. Slow, ceremonial. Long jing resonance. Sparse janggu. Kkwaenggwari calls. Builds from near silence. "utdari_pungnyu" — Court music style (upper register). Elegant, refined. Buk steady, janggu delicate 8ths, kkwaenggwari sparse. Jing on every 4 bars. "yeongnam_folk" — Yeongnam region folk style (Gyeongsang). Rough, energetic. Buk on 1+3, janggu syncopated, kkwaenggwari dense. Working-class feel.

Args: bars: Pattern length (4-32, even). style: Style name (nongak, samul_nori, binari, utdari_pungnyu, yeongnam_folk). velocity: Base velocity 0-1. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position. janggu_chwe_pitch: Janggu left head (low) MIDI pitch (35 = B0). janggu_kyong_pitch: Janggu right head (high) MIDI pitch (42 = F#1). buk_pitch: Buk (barrel drum) MIDI pitch (36 = C1). kkwaenggwari_pitch: Kkwaenggwari (small gong) MIDI pitch (54 = G#1). jing_pitch: Jing (large gong) MIDI pitch (48 = C2).

Returns notes created, instrument breakdown, and style info.

Create a full liquid drum & bass arrangement across 4 tracks.

Liquid DnB is the smooth, melodic cousin of DnB. Instead of Reese bass and Amen breakbeat fury, liquid uses:

• Track 0: Smooth breakbeat (gentler ghost notes, more flowing hats)

• Track 1: Melodic sub-bass (jazzy movement, not just root stabs)

• Track 2: Lush extended chords (maj7/min9, not plain triads)

• Track 3: Soulful jazz-influenced lead melody

Think LTJ Bukem, Calibre, High Contrast, Hospital Records.

bpm: Tempo (160-185, default 174). bars: Arrangement length (4-32, default 8). root: Root note (default F = classic liquid key). octave: Bass octave (2 = sub-bass range). velocity: Base velocity (default 0.75 = smoother than DnB's 0.85).

Example: create_liquid_dnb_arrangement(bpm=174, root="F", bars=8) create_liquid_dnb_arrangement(bpm=170, root="Am", bars=16, velocity=0.7)

Create a full lofi hip-hop arrangement — boom-bap drums + jazzy chords + mellow bass + sleepy melody.

Lofi hip-hop (Nujabes / J Dilla / chillhop) — warm, dusty, mellow:

• Track 0: Drums — boom-bap: kick on 1 and "and-a" of 2, snare on 2 and 4, laid-back 16th hi-hat with swing. No rush — behind the beat. Vinyl crackle character (lower velocity, humanized).

• Track 1: Bass — mellow root notes with occasional octave/fifth walks. Long, sustained, warm. No aggression.

• Track 2: Chords — jazzy 7th/9th voicings (maj7, min9, dom9) with soft attacks and gentle arpeggiation. The harmonic signature of lofi: extended chords, not triads.

• Track 3: Melody — sparse, sleepy pentatonic phrases. Long notes, space between phrases. The "nodding off" quality.

At 78 BPM (default), this creates the classic chillhop pocket — slow, warm, behind-the-beat. ii-V-I jazz-influenced harmony (Dm7-G7-Cmaj7 in F major) gives that nostalgic, bittersweet quality.

bpm: Tempo (70-90, default 78 = chillhop sweet spot). bars: Arrangement length (4-16, default 8). root: Root note (F is a classic lofi key — warm, midrange). octave: MIDI octave for bass (3 = F3=53, warm lofi bass). unit_index: AU index with note tracks. drum_track / bass_track / chord_track / melody_track: Track indices.

Returns notes created per track and total.

Example: create_lofi_arrangement(bpm=78, root="F", bars=8) create_lofi_arrangement(bpm=82, root="D", bars=16)

Create a melody using an L-system (Lindenmayer system) — a deterministic rewriting system.

L-systems generate self-similar, fractal patterns through recursive production rules. Each symbol in the expanded string maps to a scale step interval. The cumulative sum of intervals determines the melodic contour.

Unlike Markov chains (stochastic, memory-based) or random walk (zero-order), L-systems are fully deterministic — same axiom + rules + iterations always produce the same melody. This makes them ideal for:

• Self-similar melodic structures (fractal music)

• Deterministic generative composition

• Algorithmic music based on mathematical systems

Presets: fibonacci — Fibonacci word (A->AB, B->A), golden ratio self-similarity cantor — Cantor set (A->ABA, B->BBB), gaps and self-similar structure dragon — Dragon curve (A->A+B, B->A-B), jagged contour koch — Koch snowflake (A->A+A-A-A+A), angular melody sierpinski — Sierpinski triangle (A->BA, B->BA), binary pattern

Custom: provide axiom, rules (JSON), and symbol_map (JSON) to define your own L-system.

Args: root: Root note name (C, C#, D, ...). scale: Scale name (major, minor, dorian, phrygian, lydian, mixolydian, harmonic_minor, melodic_minor, pentatonic_major, pentatonic_minor, blues). bars: Number of bars (1-32). octave: Starting MIDI octave (1-6). preset: Preset name (fibonacci, cantor, dragon, koch, sierpinski). axiom: Custom axiom string (overrides preset). rules: Custom rules as JSON {"A": "AB", "B": "A"}. symbol_map: Custom symbol-to-interval map as JSON {"A": 1, "B": -1}. iterations: Number of rule applications (1-8). Higher = more complex. duration: Note duration in beats (0.0625-4.0). velocity: Base velocity 0-1. rest_symbol: Symbol that produces a rest (skip note, advance position). unit_index: AU index. track_index: Note track index. start_beat: Starting beat position.

Returns notes created, L-system string length, and fractal statistics.

Create a melody using a Markov chain over scale-degree intervals.

First-order (or higher) Markov chain: the next interval depends on the current (or previous N) interval(s) via a transition probability matrix. This produces melodies with stylistic memory — the interval patterns characteristic of a genre or composer emerge naturally.

Unlike random_walk (zero-order: each step independent of history), Markov chains capture interval-to-interval tendencies:

• A small ascending interval tends to be followed by another small one

• A large leap tends to be followed by a step back (regression to mean)

• Specific interval sequences define melodic "style"

The transition matrix can be:

• Default: built-in weights favoring smooth motion (steps > skips > leaps)

• Custom: user-provided interval weights as JSON

Args: root: Root note name (C, C#, D, ...). scale: Scale name (major, minor, dorian, phrygian, lydian, mixolydian, harmonic_minor, melodic_minor, pentatonic_major, pentatonic_minor, blues). bars: Number of bars (1-32). octave: Starting MIDI octave (1-6). order: Markov chain order (1 or 2). Order 1 = depends on current interval. Order 2 = depends on last 2 intervals. interval_weights: JSON string of custom transition weights. If empty, uses built-in weights. Format for order 1: {"-3": {"-3": 0.1, "-2": 0.2, "-1": 0.3, "0": 0.1, "1": 0.2, "2": 0.1}, "-2": {...}, ...} Keys are interval sizes (-7 to +7 scale steps). duration: Note duration in beats (0.0625-4.0). velocity: Base velocity 0-1. seed: PRNG seed for reproducibility. unit_index: AU index. track_index: Note track index. start_beat: Starting beat position.

Returns notes created, transition statistics, and seed.

Create a polyrhythm — N notes evenly spaced across M beats.

A polyrhythm places numerator notes evenly across denominator beats, creating cross-rhythms against the main pulse. 3:4 = triplet feel, 5:4 = quintuplet, 7:4 = septuplet, 3:2 = half-note triplets.

The notes ascend or descend through the specified scale, creating a melodic polyrhythm rather than just rhythmic hits. This is the foundation of jazz cross-rhythm, prog-rock metric modulation, African cross-pulse, and contemporary classical writing.

Args: unit_index: Audio unit index track_index: Note track index numerator: Number of notes to fit across denominator beats (2-9, default 3). This is the "against" number. denominator: Number of beats to span (2-8, default 4). This is the "base" pulse. bars: Number of times to repeat the polyrhythm cycle (1-8, default 1). pitches: Comma-separated MIDI pitches for custom note selection. If provided, overrides scale-direction generation. Notes cycle through this list. velocity: Base velocity (0-1, default 0.8) velocity_pattern: Velocity across the polyrhythm — "constant": same velocity "accent": accent first note of each cycle "fade": linear fade across all notes "wave": sine wave velocity pattern start_beat: Position in beats where polyrhythm starts (default 0.0) direction: Pitch direction when using scale generation — "up": ascending through scale "down": descending through scale "alternate": up then down per cycle scale: Scale for pitch generation ("major", "minor", "dorian", "phrygian", "lydian", "mixolydian", "locrian", "harmonic_minor", "melodic_minor", "pentatonic", "blues", "chromatic") root: Root note for scale (C, C#, D, ... B)

Create a melody from a scale and rhythmic pattern — one call instead of 10-30 create_note calls.

scale: Scale type (major, minor, harmonic_minor, melodic_minor, dorian, phrygian, lydian, mixolydian, locrian, pentatonic_major, pentatonic_minor, blues, chromatic). root: Root note name (C, C#, D, D#, E, F, F#, G, G#, A, A#, B or flats Db, Eb, Gb, Ab, Bb). pattern: Rhythmic pattern using scale degrees. Each step is one 16th note:

• Numbers 1-7 (or 1-5 for pentatonic, 1-6 for blues) = scale degree (1 = root)

• 0 = rest

• '-' = sustain previous note (tie)

• '+' = octave up for this note

• Example: "1-2-3-5-4-3-2-1" = ascending then descending scale fragment

• Example: "1 0 3 0 5 0 3 0" = arpeggio with rests unit_index: AU index with a note track. track_index: Note track index within the AU. start_beat: Where the melody starts (0 = bar 1). octave: MIDI octave for the root (4 = C4=60, the middle C). velocity: Note velocity 0-1 (default 0.75).

Returns the total notes created and pitches used.

Create a lead melody from a chord progression string.

Completes the harmonic quartet: create_chord_pads (sustained harmony) + create_arpeggiated_progression (arp movement) + create_bass_from_progression (bass foundation) + THIS (lead melody). All four take the same "Am-F-C-G" string.

The melody hits chord tones on strong beats (1, 3) and uses passing tones or neighbor tones on weak beats (2, 4) for melodic interest.

pattern: Melodic pattern: "chord_tones" — root/third/fifth on beats 1+3, passing tone on 2+4 "sustained" — one chord tone per bar, held for full bar (ballad) "syncopated" — 8th notes, chord tones on downbeats, passing on ups "triadic" — arpeggiated 8ths through chord tones (folk, country) "stepwise" — scale steps between chord tones (pop, classical)

bars_per_chord: Bars per chord (default 4). octave: MIDI octave for melody (5 = C5=72, typical lead range). velocity: Note velocity (0-1, default 0.75). track_index: Track for melody (typically melody track = 3).

Example:

Pop lead from I-V-vi-IV

create_melody_from_progression("C-G-Am-F", pattern="chord_tones", octave=5, track_index=3)

Ballad sustained melody

create_melody_from_progression("Am-F-C-G", pattern="sustained", octave=5, bars_per_chord=4)

Country triadic fiddle

create_melody_from_progression("D-G-A-D", pattern="triadic", octave=5, velocity=0.8)

Create a full metal arrangement — double kick drums + palm-muted riffs + power chords + shred lead.

Heavy metal — riff-based, not chord-progression-based:

• Track 0: Drums — double kick (16th notes on kick), snare on 2+4, crash on bar starts, ride during verses. Blast beat feel at high BPM. The double kick is the heartbeat of metal — relentless.

• Track 1: Bass — root-following bass, palm-muted style. Follows the riff root notes in steady 8ths. Thick, driving, sits under the guitars like a foundation.

• Track 2: Rhythm guitar — power chords (root+fifth) with palm-muted 8th note chugging. The classic metal riff approach: low E string pedal tone + power chord stabs. E minor phrygian dominant for that Middle Eastern/exotic metal feel.

• Track 3: Lead guitar — minor pentatonic + natural minor scale shredding. Fast alternate-picking runs, sweep arpeggios, tapped harmonics simulated via high-register notes. The "shred" quality.

At 160 BPM (default), this is thrash/speed metal territory. At 120 BPM, it's traditional heavy metal (Iron Maiden). At 200+, it's extreme/black metal.

The riff: low E pedal tone + power chord on the off-beat. Phrygian dominant (E-F#-G-A-B-C-D) gives the exotic metal sound (think Metallica, Slayer, Meshuggah). Not I-IV-V — metal is riff-driven, not chord-driven.

bpm: Tempo (100-220, default 160 = thrash metal). bars: Arrangement length (must be multiple of 4, default 8). root: Root note (E is the most common metal key — lowest guitar string). octave: MIDI octave for bass (2 = E2=40, standard metal bass register). unit_index: AU index with note tracks. drum_track / bass_track / chord_track / lead_track: Track indices.

Returns notes created per track and total.

Example: create_metal_arrangement(bpm=160, root="E", bars=8) create_metal_arrangement(bpm=120, root="D", bars=16) # traditional metal

Create a metric modulation — tempo change that preserves a note-value equivalence.

The defining technique of Elliott Carter, Aaron Copland, John Adams, and progressive rock (Dream Theater, Tool). Unlike a simple tempo change, metric modulation establishes a precise relationship: a specific note value in the new tempo has the same duration as a different note value in the old tempo. The listener perceives a new pulse while the rhythmic fabric remains continuous.

Formula: new_bpm = old_bpm × (new_note_value / old_note_value)

Supported note values:

• "whole", "half", "dotted_half", "quarter", "dotted_quarter"

• "quarter_triplet", "eighth", "dotted_eighth", "eighth_triplet"

• "sixteenth", "dotted_sixteenth", "thirty_second"

Alternatively, pass a ratio like "3:2" (new tempo = 3/2 of old) or "2:3" (new = 2/3 of old) to express the modulation as a simple proportion.

Examples: create_metric_modulation(32, "quarter", "dotted_eighth", old_bpm=120) → new_bpm = 120 × (3/16) / (1/4) = 90 BPM. A dotted eighth at 90 lasts the same as a quarter at 120. create_metric_modulation(16, ratio="3:2", old_bpm=100) → new_bpm = 150. Three notes in new tempo = two in old. create_metric_modulation(48, "eighth", "quarter", old_bpm=140) → new_bpm = 280. Quarter at new tempo = eighth at old (doubling).

Args: position_beats: Beat position where modulation occurs. old_note: Note value in the old tempo (default "quarter"). new_note: Note value in the new tempo that equals old_note's duration (default "dotted_eighth" — classic Carter modulation). old_bpm: Current BPM. If 0, reads from the project's tempo track. ratio: Direct ratio "N:M" — new_bpm = old_bpm × N/M. Overrides old_note/new_note if provided. add_time_signature: Optional new time signature as "N/D" (e.g. "3/4", "6/8"). If provided, also creates a time signature change event at the same position.

Returns old_bpm, new_bpm, ratio, equivalence, and events created.

Create MIDI echo — repeat notes with decaying velocity and optional pitch shift.

Takes existing notes from a region and creates echoing repeats. Each repeat is delayed by delay_beats, quieter by velocity_decay factor, and optionally shifted in pitch. This is a creative effect, not a simple copy — think guitar delay throws, synth echo fills, vocal repeat stutters.

feedback_mode:

• "linear" — each repeat is velocity_decay × previous (0.6 → 0.6, 0.36, 0.216)

• "exponential" — faster decay, squared each time

• "constant" — same velocity for all repeats (stutter feel)

• "reverse" — each repeat gets louder (build-up feel)

pitch_shift: semitones added per repeat (0 = no shift, +12 = octave up each repeat, -5 = perfect fourth down each repeat). Creates cascading echoes.

dest_track: -1 = same track (thickening), N = separate track (layered echo). Using a separate track lets you process the echo independently.

repeats: 1-8 echo repeats. Each repeat copies ALL notes from the source. delay_beats: time between each repeat (0.25 = 16th, 0.5 = 8th, 1.0 = quarter).

unit_index: AU index. track_index: Source note track. region_index: Source region (-1 = first). repeats: Number of echo repeats (1-8). delay_beats: Delay between repeats in beats. velocity_decay: Velocity multiplier per repeat (0-1, 0.6 = 60% each time). pitch_shift: Semitones added per repeat (0 = none). dest_track: Destination track (-1 = same, N = separate track). feedback_mode: linear / exponential / constant / reverse.

Returns echo summary with per-repeat velocity and pitch info.

Example:

Guitar-style echo: 3 repeats, 8th note delay, decaying

create_midi_echo(0, 0, repeats=3, delay_beats=0.5, velocity_decay=0.5)

Cascading octave echoes on separate track

create_midi_echo(0, 0, repeats=4, delay_beats=0.25, pitch_shift=12, dest_track=2)

Build a multi-section song with key modulation between sections — one call.

Each section has its own chord progression, length (bars), and energy (velocity multiplier). The tool automatically modulates between keys by using different progressions per section — no manual start_beat calculation needed.

sections: Comma-separated section specs. Each section format: name:progression:bars:energy

• name: section label (verse, chorus, bridge, outro, etc.)

• progression: chord progression string (e.g. "Am-F-C-G")

• bars: total bars for this section

• energy: velocity multiplier (0.0-1.0, relative to base velocity)

Default creates a 24-bar song: verse (Am-F-C-G, 8 bars, 0.7) → chorus (C-G-Am-F, 8 bars, 1.0) → bridge (F-C-Dm-G, 4 bars, 0.6) → outro (Am-F-C-G, 4 bars, 0.5)

The chorus modulates to C major (relative major of A minor), the bridge modulates to F (up a fourth), and the outro returns to Am.

arp_pattern/bass_pattern/melody_pattern/counter_melody_pattern: Same as create_harmonic_arrangement. Applied to all sections. Use "" to skip any layer.

drum_genre: If set (e.g. "house", "dnb", "synthwave"), creates a genre drum arrangement for the full song length BEFORE harmonic layers. When drum_genre is set, pads and bass are automatically skipped in harmonic sections (genre arrangement provides them). Default "" = no drums (harmony only). Valid: dnb, liquid_dnb, house, trap, techno, dubstep, afrobeat, rock, jazz, pop, funk, reggae, synthwave, trance, disco.

bpm: Tempo for drum arrangement (None = genre default). Only used when drum_genre is set.

Example:

Default 4-section modulated song (harmony only)

create_modulated_song()

With house drums

create_modulated_song(drum_genre="house", bpm=124)

With synthwave drums + counter-melody

create_modulated_song(drum_genre="synthwave", counter_melody_pattern="contrary")

Simple verse-chorus with DnB drums

create_modulated_song("verse:Em-G-D-C:8:0.7,chorus:G-D-Em-C:8:1.0", drum_genre="dnb")

Create a montuno — a repeating Latin/jazz piano ostinato pattern.

A montuno is a 2-bar (or 4-bar) repeating piano figure central to son, salsa, Latin jazz, and mambo. It consists of syncopated chord stabs and single-note passages that lock with the clave, creating a driving, danceable groove.

Unlike arpeggiators (which cycle through chord tones mechanically) or ostinato patterns (which repeat a fixed melodic cell), a montuno combines:

• Harmonic movement through a chord progression

• Syncopated rhythm locked to the clave

• Alternation between chord stabs and melodic passage notes

• Call-and-response phrasing within each bar

Pattern types: 2-3 — Classic 2-3 clave montuno (2-side in bar 1, 3-side in bar 2) 3-2 — Reverse clave (3-side first, 2-side second) guajira — Cuban guajira montuno (gentler, dotted rhythm feel) charanga — Charanga-style (more melodic, flowing passages)

Rhythm: 8th — Eighth-note based (standard salsa) 16th — Sixteenth-note based (faster, busier) quarter — Quarter-note based (simpler, mambo style)

Args: root: Root note name (C, C#, D, ...). scale: Scale name (major, minor, dorian, mixolydian, harmonic_minor). bars: Number of bars (2 or 4). Montunos are typically 2-bar cycles. octave: Starting MIDI octave (2-6). chord_prog: Comma-separated chord progression (e.g., "C,Am,Dm,G"). If empty, generates a I-vi-IV-V progression in the key. pattern: Pattern type (2-3, 3-2, guajira, charanga). rhythm: Rhythm subdivision (8th, 16th, quarter). velocity: Base velocity 0-1. accent_beats: Comma-separated beat numbers to accent (1-indexed). unit_index: AU index. track_index: Note track index. start_beat: Starting beat position.

Returns notes created, chord progression, and pattern info.

Create a mordent — main note → neighbor → back. A classical ornament.

The mordent is one of the four essential baroque ornaments (trill, mordent, turn, appoggiatura). It's a rapid single alternation: play the main note briefly, flick to a neighbor note, then return to the main note — all within the space of one note duration. Think Bach two-part inventions, Mozart sonatas.

An upper mordent flicks UP (main → upper neighbor → main). A lower mordent flicks DOWN (main → lower neighbor → main). The neighbor note is very short — just a flicker.

main_pitch: The primary MIDI note (default 60 = C4). direction: "upper" (main→higher→main) or "lower" (main→lower→main). interval: Semitones to the neighbor note (default 2 = whole step). Upper: 1 = half step (diatonic), 2 = whole step. Lower: -1, -2 mirror. duration_beats: Total length of the mordent in beats (0.25-4, default 0.5 = one 8th). velocity: Base velocity 0-1 (default 0.85). unit_index: AU index with note track (-1 = find first AU with note tracks). track_index: Note track index within the AU. start_beat: Position in beats where the mordent begins.

Returns notes created, pitches used.

Develop a motif into a through-composed melodic line that evolves.

Takes a short motif (2-8 notes) and builds a continuous melodic line that develops through compositional stages: statement, sequential repetition (up/down), fragmentation (shorter segments), inversion, octave displacement, and cadence. This is the Beethoven 5th approach — a 4-note seed grows into an entire melodic arc.

Unlike create_variations (separate regions, each a full transformation), create_motif_development writes ONE continuous line that flows through stages without stopping. Unlike create_sequence (pure transposition), this tool mixes multiple development techniques in sequence.

motif: Comma-separated scale degrees (1-7) or MIDI pitches. Scale degrees: 1=root, 2=2nd, 3=3rd, etc. 0=rest. MIDI pitches: 60,62,64,65 etc (when use_midi=true implicit if >7). Example: "1,1,1,2" or "60,60,60,62" scale: Scale type (major, minor, harmonic_minor, dorian, etc.). root: Root note name (C, D#, Bb, etc.). octave: MIDI octave for root (4 = C4=60). steps: Comma-separated development stages: "statement" — play motif as-is "sequence_up" — transpose up by a 4th (5 semitones) "sequence_down" — transpose down by a 4th "fragment" — play first half of motif "fragment_end" — play second half of motif "invert" — invert around root pitch "octave_up" — shift up one octave "octave_down" — shift down one octave "expand" — double note durations "compress" — halve note durations "cadence" — resolve to root (scale degree 1, longer duration) step_duration: Duration of each note in beats (0.25 = 16th). velocity: Base velocity 0-1. unit_index: AU index with a note track. track_index: Note track index within the AU. start_beat: Where the development starts.

Returns total notes, stage count, pitches used.

Extract a motif from existing notes and create a variation in a new region.

Closes the analysis→creation loop: extract_motifs finds repeating patterns, this tool takes a specific motif and transforms it using classical composition techniques. The motif is identified by start_note index and note_count within the source region.

Variation types:

• sequence: repeat the motif shifted up/down by N scale steps or semitones. Creates melodic sequences — the backbone of classical and jazz improvisation.

• inversion: flip the contour upside down. C→E→G (+4, +3) becomes C→A→F (-3, -2). The intervals are mirrored around the first note.

• retrograde: play the motif backwards. Last note first, first note last. The rhythm and pitches are reversed in time.

• augmentation: stretch all durations by a factor (2.0 = twice as slow). Creates grand, expansive statements from quick motifs.

• diminution: compress all durations by a factor (2.0 = twice as fast). Creates urgency and energy from slow motifs.

• fragmentation: take the first N notes of the motif and repeat them. Creates rhythmic ostinatos from melodic material.

Essential for: developing melodic material, building variations, creating thematic development, and extending motifs into new sections.

source_unit/track/region: Location of the source motif. start_note: Index of the first note of the motif within the source region (0-based, sorted by position). note_count: Number of notes in the motif (3-16). target_unit/track/region: Where to write the variation. -1 = create new track/region automatically. variation_type: sequence, inversion, retrograde, augmentation, diminution, fragmentation. sequence_shift: For sequence type — semitones to shift each repetition. augmentation_factor: For augmentation/diminution — duration multiplier. fragment_count: For fragmentation — how many notes to keep from the start.

Returns the created variation with note details.

Create timed mute/unmute automation events on an audio unit.

Essential for section dynamics: mute drums during breakdowns, unmute for drops, create structural silences. Each event is a (beat, mute_state) pair — mute at beat X, unmute at beat Y. Replaces multiple set_track_mute calls with one automation track that plays back predictably every time.

unit_index: AU index to automate mute on. events: JSON array of [beat, muted] pairs. beat = position in beats, muted = true (silence) or false (audible). Example: [[0, false], [16, true], [24, false]] = audible 0-16, muted 16-24, audible 24+

Returns events created, mute schedule, and track index.

Examples: create_mute_automation(unit_index=0, events='[[0,false],[16,true],[24,false]]') → Drums audible for 16 beats, muted for 8 (breakdown), back on at 24 create_mute_automation(unit_index=2, events='[[0,true],[8,false]]') → Bass silent for intro, kicks in at beat 8

Create a full neurofunk DnB arrangement — 4 tracks: drums + sub-bass + Reese + stabs.

Neurofunk (Noisia, Spor, Phace, Ed Rush & Optical) is the technically advanced evolution of drum & bass — darker, more complex, with signature sound design elements:

• 170-180 BPM, dark minor key (typically F or E minor)

• Complex chopped breakbeats with extra ghost notes, kicks, and rolls

• Reese bass: detuned saw layers with movement, the hallmark neurofunk sound

• Sub-bass underneath the Reese for low-end weight

• Dark minor chord stabs and sci-fi atmosphere

• Aggressive velocity, tight quantization with occasional swing

Creates 4 tracks:

1. Drums (drum_track): Complex amen break with extra kick placements, ghost notes, and snare rolls at phrase ends. 2-bar cycle.

2. Sub-bass (bass_track): Deep sustained sub following root note, syncopated gaps where drums fill. Octave 1 for sub weight.

3. Reese (reese_track): Detuned saw-style Reese bass with chromatic movement, pitch slides, and rhythmic stabs. The signature neuro sound.

4. Stabs (stabs_track): Dark minor chord stabs (root + b3 + b5 + b7) on beats 1 and 3, with occasional off-beat sci-fi stabs.

bpm: Tempo (160-185, default 174). bars: Arrangement length (4-32, default 8). root: Root note (default F = classic neurofunk key). octave: MIDI octave for Reese/bass (2 = C2=36).

Returns notes created per track and total.

Example: create_neurofunk_arrangement(bpm=174, root="F", bars=8) create_neurofunk_arrangement(bpm=180, root="E", bars=16)

Create a MIDI note on a note track.

pitch: MIDI note number (60 = C4, 69 = A4). start_beat: beat position. duration_beats: note length in beats. velocity: 0.0-1.0. unit_index: Audio unit index (-1 = search all AUs for note tracks). track_index: Note track index within the AU.

If no clip exists on the track yet, one is auto-created. Notes are added to the first clip on the track.

Create a note clip in the session view (clip launcher).

Note clips are the session-view counterpart to note regions. They contain a NoteEventCollection and can be triggered independently in the clip launcher.

unit_index: Audio unit index (-1 = search all AUs for note tracks). track_index: Note track index within the AU. clip_index: Slot index in the clip launcher (0, 1, 2, ...). name: Display name for the clip. hue: Color hue 0-360 (-1 = auto from track type).

Returns clip UUID and index.

Create multiple MIDI notes in a single call — batch creation for melodies, chords, arpeggios.

notes: JSON array of note objects, each with:

• pitch (int): MIDI note number (60 = C4, 69 = A4)

• start (float): beat position

• duration (float): note length in beats

• velocity (float, optional): 0.0-1.0, default 0.8

Example: '[{"pitch":60,"start":0,"duration":0.5},{"pitch":64,"start":0.5,"duration":0.5},{"pitch":67,"start":1,"duration":1}]'

All notes go into one region on the specified note track. If no region exists, one is created. Faster than calling create_note repeatedly — one round-trip, one editing.modify() block.

Create a new note/MIDI track on an audio unit.

unit_index: Audio unit index. Use -1 (default) for the primary audio unit, or specify an instrument AU index that contains a synth device (Vaporisateur, Nano, etc).

Create an ostinato — a repeating melodic/rhythmic pattern as a foundation layer.

Ostinatos are short patterns (2-8 notes) that repeat throughout a section, providing a rhythmic/harmonic anchor. Common in minimalism, electronic, and film music.

scale: Scale type (major, minor, dorian, phrygian, etc. — 14 types from music_theory). root: Root note name (C, C#, D, ... B). pattern: Scale degrees as space-separated numbers (1-7, 0=rest): "1 5 3 5" — repeating i-v-iii-v pattern "1 3 5 6 5 3" — longer melodic cell repeats: Number of times to repeat the pattern (1-16). octave: Starting octave (1-7, default 4). velocity: Note velocity 0-1.

Returns total notes created and pattern info.