Audio Nodes Tracker

Blender Add-on · Version 1.9.8 · Compatible with Blender 4.0 – 5.1

A fully integrated music production environment inside Blender, combining a step sequencer, a modular audio synthesiser, a non-destructive VSE effects rack, MIDI import/export (single and multi-file), SoundFont 2 playback, and a musical timeline marker system.

1. Overview and Architecture

Audio Nodes Tracker is composed of three independent subsystems sharing a common infrastructure layer:

┌──────────────────────────────────────────────────────────────┐
│                       Blender Add-on                         │
│                                                              │
│  ┌─────────────┐   ┌─────────────┐   ┌──────────────────┐   │
│  │   nodes/    │   │  tracker/   │   │  sample_editor/  │   │
│  │(synthesiser)│   │(sequencer + │   │  (VSE effects    │   │
│  │             │   │  export)    │   │   rack)          │   │
│  └─────────────┘   └─────────────┘   └──────────────────┘   │
│                                                              │
│          ┌────────────────────────────────┐                  │
│          │       Infrastructure Layer     │                  │
│          │  audio_device   event_bus      │                  │
│          │  cache          session        │                  │
│          │  topology       mixdown        │                  │
│          └────────────────────────────────┘                  │
└──────────────────────────────────────────────────────────────┘

nodes/ — Blender node classes. Each node implements get_sound(), returning a lazy aud.Sound audio graph. No audio is decoded until playback or export begins.

tracker/ — The step sequencer: data model, real-time playback handler, CRUD operators, UI panels, MIDI import/export (single and multi-file), and all export paths.

sample_editor/ — Non-destructive effects rack for audio strips in the VSE.

Per-Track Graph Architecture (v1.8.0) — Each AudioTrack owns a dedicated AudioNodeTree identified by a unique node_tree_name. The synthesiser graph responds only to the pattern and track it is linked to. Send/Receive bus nodes allow audio to flow between graphs, with cycle detection handled by the topology engine.

2. Audio Node Tree — Synthesiser

2.1 Opening the Editor

Open a Node Editor in Blender.
In the tree-type dropdown (top-left), select Audio Node Tree.
Create a new node tree with the New button.
Add nodes with Shift+A → Ivano Audio Nodes section.
Link the node tree to a track via the Mixer panel (see §3.3).

Each node tree acts as a single synthesis patch for one track. Multiple node trees run simultaneously, one per track.

2.2 Audio Sockets

All nodes communicate through AudioNodeSocket, shown in teal. Always connect audio outputs to audio inputs.

[Oscillator] ──(teal)──► [Filter] ──(teal)──► [Output Speaker]

2.3 Source Nodes

All oscillators share a common base that automatically handles mute/solo logic, MIDI note-to-frequency conversion, velocity, duration, and ring/amplitude modulation sockets.

The node identifies its own track from the name of the node tree it lives in — no manual Pattern ID or Track ID required.

Socket	Description
Ring Mod	Input — ring-modulates (multiplies) the generated signal
Amplitude Mod	Input — amplitude-modulates (tremolo) the generated signal
Audio Out	Output

Common properties on all oscillators:

Property	Description
Frequency	Fallback frequency when the tracker provides no note (Hz)
Amplitude	Base amplitude multiplier

Sine Oscillator

Pure sine wave. Ideal for bass, soft pads, and FM synthesis.

Square Oscillator

Square wave rich in odd harmonics. Bright, digital character.

Triangle Oscillator

Implemented via additive synthesis (fundamental + 3rd, 5th, 7th harmonics with alternating sign). Warm tone, halfway between sine and square.

Sawtooth Oscillator

Sawtooth wave — the richest in harmonics. Great for leads and synthetic strings.

Noise Oscillator

Buffered white noise (2-second looped buffer with seamless crossfade at the loop boundary). Used for percussion, FX, and textures.

LFO (Low-Frequency Oscillator)

Generates a low-frequency control signal. Does not produce directly audible audio on its own.

Property	Description
Waveform	Sine / Square / Triangle / Sawtooth
Frequency (Hz)	Modulation speed (0.01 – 100 Hz)
Amplitude	LFO signal strength
Rate Mod	Input socket — modulates the LFO's own frequency

Connect to an oscillator's Ring Mod input for vibrato, or Amplitude Mod for tremolo.

3xOsc

Three sine oscillators summed and normalised, tunable in semitone offsets.

Property	Description
Tune 2 (Semi)	Semitone offset for oscillator 2 (default: +7 = perfect fifth)
Tune 3 (Semi)	Semitone offset for oscillator 3 (default: +12 = one octave)
Vol 1 / 2 / 3	Individual volume for each oscillator

If all volumes are zero, the node outputs silence cleanly without normalisation artefacts.

Kicker

Synthetic kick drum / sub-bass with a configurable decay envelope. Manages its own envelope internally — do not add a second Envelope node after it.

Property	Description
Decay (s)	Decay duration, clamped to the step duration

Sample Player

Loads an external audio file and plays it pitch-shifted according to the tracker note. C4 = pitch × 1.0 (no transposition).

Property	Description
File	Path to the audio file (WAV, MP3, OGG, FLAC, …)

File existence is cached to avoid repeated disk checks during playback.

SF2 Player

Plays samples from a SoundFont 2 (.sf2) file. Full pure-Python SF2 parser — no external dependencies.

Property	Description
SF2 File	Path to the .sf2 file
Preset (node)	Default preset (bank:patch) for all steps that have no per-step override

Per-step instrument selection — each step in the Note Editor can override the node's preset via the SF2 Instrument selector. In polyphonic steps each voice can have its own preset. The fallback cascade is: voice preset → step preset → node preset.

SF2 key range support (v1.9.5): the parser now reads keyRange and sampleID generators from the igen chunk and uses wPresetBagNdx from the phdr record to resolve the correct bag range per preset. Sample selection now respects key ranges and picks the zone with the root MIDI note closest to the requested pitch, instead of scanning the entire sample pool.

2.4 Filter and Effect Nodes

All filter nodes have at least one Audio In input and one Audio Out output.

Note on modulation sockets labelled "Ring Mod" — these sockets apply sound.modulate() (ring/AM multiplication) to the already-processed signal. They do not control the filter's frequency parameter at audio rate.

Volume

Simple volume multiplier.

Property	Range	Description
Volume	0 – ∞	1.0 = unchanged, >1 = amplification

Lowpass

Low-pass filter.

Property	Description
Frequency	Cutoff frequency (Hz)
Q Factor	Filter resonance
Ring Mod	Modulates the filtered signal

Highpass

High-pass filter. Same properties as Lowpass.

Bandpass

Passes a band of frequencies around the centre frequency.

Property	Description
Center Freq	Centre frequency (Hz)
Band Width	Bandwidth (Hz)
Ring Mod	Modulates the output

Notch Filter

Cuts a narrow band of frequencies. Half-bandwidth is clamped to 40% of the centre frequency.

Property	Description
Cut Frequency	Frequency to remove (Hz)
Q Factor	Higher = narrower cut

3-Band EQ

Three-band equaliser (Low / Mid / High) with adjustable crossover frequencies. The three bands are summed and normalised so that unity gain on all three produces unity output.

Property	Description
Low Cutoff (Hz)	Low-to-mid crossover
High Cutoff (Hz)	Mid-to-high crossover
Low / Mid / High Gain	Per-band gain (0 = muted, 1 = unity, 3 = boost)

Freq Splitter (Parametric)

Splits the input into three independent output signals (Low Out, Mid Out, High Out), each with its own filter type, frequency, Q, and gain.

Property	Description
Low / Mid / High Filter Type	LP / HP / BP / Notch per band
Low / Mid / High Freq	Cutoff / centre frequency per band (Hz)
Low / Mid / High Q	Q factor per band
Low / Mid / High Gain	Gain multiplier per band

Socket routing fix (v1.9.5): downstream nodes connected to Mid Out or High Out now correctly receive their respective band.

Compressor

Gain-into-limiter compressor using IIR soft-clipping.

Property	Range	Description
Threshold	0.1 – 1.0	Compression threshold
Ratio	1 – 20	Compression ratio
Makeup Gain	1 – 5	Post-compression gain

Envelope

ADSR-style envelope follower. Shapes the amplitude envelope of the input signal.

Property	Description
Attack	Attack time (seconds)
Release	Release time (seconds)
Threshold	Activation threshold
A/R Threshold	Attack/release detection threshold (min 0.001)

Distortion

Soft clipper via IIR filter. Drive progressively increases saturation without volume instability.

Property	Range	Description
Drive	1.0 – 10.0	Distortion intensity

Bitcrusher

Lo-fi effect via simulated quantisation and HF rolloff.

Property	Range	Description
Quality %	1 – 100	100 = clean, 1 = maximum crushing

Reverb

Simulated reverberation via 8 parallel delay taps with progressive high-frequency decay.

Property	Range	Description
Room Size	0.1 – 3.0	Room size multiplier
Mix (Wet/Dry)	0 – 1	Wet/dry balance

Delay

Simple audio delay.

Property	Description
Time	Delay time in seconds (hard cap: 300 s)

Ping Pong Delay

Stereo delay with feedback, normalised to prevent amplitude build-up.

Property	Range	Description
Delay Time	0.01 – 30 s	Delay time
Feedback	0.0 – 0.9	Feedback amount

Chorus

Ensemble effect using two independently-delayed copies of the signal.

Property	Description
Mix	Dry/wet balance
Delay 1 (ms)	First chorus tap delay
Delay 2 (ms)	Second chorus tap delay

Flanger

Three comb filters at multiples of the base delay time.

Property	Description
Delay (ms)	Base delay in milliseconds
Mix	Dry/wet balance

Pitch Shift

Pitch transposition via speed multiplier.

Property	Range	Description
Pitch Factor	0.1 – 10	1.0 = unchanged, 2.0 = one octave up

WahWah

Bandpass filter with variable resonance. Resonance minimum is 1.01 to guarantee a non-zero bandwidth.

Property	Description
Frequency (Hz)	Bandpass centre frequency
Resonance	Bandwidth control (higher = narrower)

Waveshaper

Hard distortion with progressive saturation.

Property	Range	Description
Shape Amount	0.0 – 1.0	0 = no effect, 1 = maximum saturation

Accumulator

Integrates the signal over time. Safe only with zero-mean signals such as LFOs. Displays a warning in the UI when connected to a non-LFO source.

Property	Description
Additive	If enabled, uses additive accumulation mode

Fader

Timed fade in or fade out.

Property	Description
Start	Fade start point (seconds)
Length	Fade duration (seconds)
Invert	If enabled, performs a fade out instead of a fade in

Normalize

Brings the signal to a target loudness level. Operates in two phases: an offline analysis pass (triggered by the Analyse button) and a real-time application pass.

Property	Description
Mode	Peak / RMS / LUFS (approx EBU R128)
Target (dBFS)	Target level (default: -1.0 dBFS for Peak)
Headroom (dB)	Safety margin below the target
Auto Gain	Gain calculated by the analysis (read-only)
Manual Gain	Fallback gain used when no analysis has been run

Analysis limit (v1.9.5): analysis is capped at 30 seconds to avoid blocking the Blender main thread on long files.

Noise Gate

Silences the signal when its amplitude drops below the threshold.

Property	Description
Threshold (dBFS)	Gate open threshold
Floor (dBFS)	Signal level when gate is closed (-96 = full silence)
Attack (s)	Gate opening speed
Hold (s)	Minimum open time after threshold crossing
Release (s)	Gate closing speed after hold expires
Knee (dB)	Width of the soft-transition zone around the threshold
Lookahead (s)	Delays the target signal so the gate opens before the sound arrives (max 50 ms)
Mix (Wet)	Dry/wet balance

Performance (v1.9.5): the gate control buffer is now cached in memory per parameter combination, eliminating per-frame disk I/O.

Auto-Sidechain (Ducker)

Simulates sidechaining via ring modulation with an LFO.

Property	Description
LFO Freq (Hz)	Ducking frequency (120 BPM quarter notes ≈ 2 Hz)

This is not a true audio-routed sidechain. For key-signal-driven ducking use the Peak Controller node.

Peak Controller

Reads the envelope of a sidechain trigger signal and uses it to reduce the volume of the main signal.

Socket	Description
Sidechain In	The trigger signal (e.g. kick drum)
Audio In	The signal to duck (e.g. bass, pad)
Audio Out	Output with ducking applied

Property	Description
Threshold	Amplitude threshold above which ducking activates
Ratio (Depth)	Ducking depth (0 = no effect, 1 = full mute at peak)
Attack (s)	Envelope attack speed
Hold (s)	Minimum open time after threshold crossing
Release (s)	Envelope release speed
Mix (Wet)	Dry/wet balance
Invert (Gate)	Inverts the effect — volume rises when the trigger is loud

Performance (v1.9.5): the ducking control buffer is cached in memory identically to the Noise Gate.

2.5 Routing Nodes

Audio Mixer

Sums two audio signals with variable balance.

Property	Description
Mix Factor	0.0 = input 1 only · 1.0 = input 2 only

Modulator (Ring Mod)

Ring modulation: multiplies the carrier by the modulator sample by sample. When the modulator is not connected, acts as a passthrough.

Sockets: Carrier In, Modulator In, Audio Out.

2.6 Bus Nodes — Send & Receive

Bus nodes allow audio to flow between separate node trees (graphs). The topology engine (tracker/topology.py) analyses Send/Receive dependencies and ensures graphs are evaluated in the correct order (Kahn's topological sort). Circular dependencies are detected and reported as a warning.

Send

Writes the signal to a named shared bus and passes it through to the output.

Property	Description
Bus	Name of the bus to write to
Send Level	Volume of the sent signal (does not affect the pass-through)

Receive

Reads from a named shared bus. Optionally mixes with a local input signal.

Property	Description
Bus	Name of the bus to read from
Return Level	Volume of the received signal

Bus routing (v1.9.4–v1.9.5): renaming a bus now immediately invalidates the topology cache. Both real-time playback and WAV/MP4 export evaluate tracks in topological order.

2.7 Output Node

Output Speaker is the mandatory terminal node. Every node tree must end with one.

Single input: Audio In
No configurable properties

2.8 Chain Examples

Basic synthesiser

[Sine Oscillator]
      │
      ▼
[Lowpass]  Frequency: 800 Hz  Q: 0.7
      │
      ▼
[Volume]  Volume: 0.8
      │
      ▼
[Output Speaker]

Lead with LFO vibrato

[LFO]  Freq: 5 Hz  Amp: 0.02
  └──(Ring Mod)──► [Sine Oscillator]
                         │
                         ▼
                   [Distortion]  Drive: 3.0
                         │
                         ▼
                   [Output Speaker]

Sidechain ducking across two graphs

Graph A — Kick Drum:

[Kicker] ──► [Send]  Bus: "Kick"  ──► [Output Speaker]

Graph B — Bass Pad:

[3xOsc] ──► [Peak Controller]
               ▲  Sidechain In
            [Receive]  Bus: "Kick"
                   │
                   ▼
            [Output Speaker]

3. Tracker — Step Sequencer

The tracker is accessible in the sidebar of Blender's Spreadsheet editor. Press N inside the Spreadsheet, then go to the Audio Tracker tab.

3.1 Master Control

The top-level panel with global controls.

Tempo (BPM)

The BPM field controls the global project tempo. One beat equals four steps, so:

step_duration_sec = 60 / BPM / 4
frames_per_step   = step_duration_sec × FPS

Changing BPM automatically recalculates step.duration on every step of every pattern. The BPM field is locked during animation playback to prevent mid-playback desync. A read-only info row below always shows the derived step duration (ms) and frames-per-step.

Playback Mode

Mode	Description
Arrangement (VSE)	Reads TEXT/COLOR strips on the VSE that carry an `audio_pattern_idx` property. Plays the full arrangement in sequence.
Track Edit (Solo)	Loops the active pattern indefinitely. Ideal for real-time composition.

Buttons

Button	Function
Create Spreadsheet Grid	Creates/updates the `Tracker_Viewer` mesh to display step data in the Spreadsheet editor
Import JSON	Loads patterns and automations from a JSON file
Export JSON	Saves patterns and automations to a JSON file
Import MIDI	Imports a single Standard MIDI File (.mid) as a new pattern
Import Multiple MIDI…	Imports multiple .mid files — each file becomes a separate pattern
Export Active Pattern…	Exports the active pattern as a Standard MIDI File
Export Multiple Patterns…	Opens a dialog to select which patterns to export; each becomes a separate .mid file
Export VSE WAV (Full Mix)	Full bake of the VSE arrangement to a stereo 44.1 kHz WAV file
Export Video MP4 (Full Mix)	Audio bake + video render to MP4 with AAC audio

MIDI Import Options

When importing a MIDI file, the following options appear in the file browser side panel:

Option	Description
Quantisation	Rhythmic resolution: 1/4, 1/8, 1/16 (default), 1/32
BPM override	Override the BPM from the file (0 = auto-detect)
Max Steps	Maximum number of steps per pattern (default 256)
Create graphs	Automatically create an empty AudioNodeTree for each imported track
Append to active	Add tracks to the active pattern instead of creating a new one (single-file import only)

Multi-File MIDI Import (v1.9.8)

When using Import Multiple MIDI…, the same quantisation, BPM override, max steps, and create-graphs settings apply to every selected file. Each file always creates a new pattern (append mode is not available for batch imports).

MIDI Export Options (single pattern)

Option	Description
BPM	BPM for step-to-tick conversion (0 = auto from scene FPS)
Step Resolution	Duration of each step as a musical note value
sf2_preset → Program Change	Write step SF2 presets as MIDI Program Change events
Skip empty tracks	Omit tracks with no notes

Multi-Pattern MIDI Export (v1.9.8)

Export Multiple Patterns… opens a dialog showing all patterns with checkboxes. Select the patterns to export, pick an output directory, and click OK. Each selected pattern is written as {index:02d}_{pattern_name}.mid (e.g. 01_Intro.mid, 02_Verse.mid). A summary report is shown in the Info panel.

3.2 Patterns & Tracks

Pattern Management

The pattern list shows all patterns in the scene. Use + and − to add or remove, and the Duplicate button to clone.

Once a pattern is selected:

Field	Description
Steps Length	Number of steps in the pattern (1 – n). Step duration is derived from the global BPM.
Insert Pattern to VSE	Inserts a COLOR strip into the VSE at the current frame with the correct length.

Track Management

Each pattern contains one or more tracks (instruments).

Field	Description
Instrument	Track name
Volume	Track volume (0.0 – 2.0)
Pan	Stereo panning, equal-power law (-1 = hard left, 0 = centre, +1 = hard right)
SOLO	Silences all other tracks
MUTE	Silences this track

3.3 Mixer

The Mixer panel displays one strip per track in the active pattern, providing a DAW-style channel view.

Per-Track Strip

Control	Description
Track Name	Displayed at the top. The active track is highlighted in red.
S (Solo)	Solo this track
M (Mute)	Mute this track
Vol (slider)	Track volume fader (0.0 – 2.0)
Pan (slider)	Stereo panning (-1.0 = hard left, 0 = centre, +1.0 = hard right)
Graph indicator	✓ if a valid AudioNodeTree is assigned, ✗ if the name is set but the graph does not exist
Choose (button)	Opens a popup listing all AudioNodeTrees. Graphs already assigned to other tracks are marked ⚠.
+ (button)	Quick-create: generates a new AudioNodeTree with an Output Speaker node and assigns it to the track

3.4 Note Editor

The heart of the tracker. Displays and allows editing of notes for the currently focused step.

VU Meter

MASTER VU: [████████──]

Displays the master level as the sum of (amplitude × track_volume) for all active, non-muted tracks in the current step. This is a compositional indicator, not a rendered audio measurement.

Step Navigation

[ ◀ ]  [ Step Focus: 7 ]  [ ▶ ]

Navigate between steps. The selected step is highlighted in the Spreadsheet Grid.

Current Step — Monophonic

Field	Description
Master Vel	Step master amplitude (0.0 – 1.0), applied to all voices
Dur	Step duration in seconds (derived from BPM, shown read-only)
Note	Chromatic note (C, C#, D … B) or `---` (rest / silence)
Oct	Octave (0 – 8). Octave 4 = middle C (261.63 Hz)
Vel	Individual voice velocity (0.0 – 1.0)

Note preview: whenever a note or octave is changed, a short sine preview (0.25 s) is played automatically, provided animation playback is not running.

SF2 Instrument Selector

When the active track's graph contains an SF2 Player node, a SF2 Instrument section appears showing the current preset for the step. Click Choose to open a popup with all presets. Click ↩ Inherit from node to remove the per-step override.

3.5 Keyboard Note Input

Click Enter Note Mode to activate FastTracker II–style keyboard entry. The panel turns red with the ● NOTE INPUT indicator. Click Exit or press Esc to leave at any time.

Key Mapping

Lower row (current octave):
  Z  S  X  D  C  V  G  B  H  N  J  M
  C  C# D  D# E  F  F# G  G# A  A# B

Upper row (octave + 1):
  Q  2  W  3  E  R  5  T  6  Y  7  U
  C  C# D  D# E  F  F# G  G# A  A# B

Special Keys

Key	Action
← →	Move the step cursor left / right (wraps on pattern length) — does not modify notes
↑ ↓	Move the track cursor up / down (wraps on track count) — does not modify notes
Space	Insert a rest (`---`) and advance to the next step
Del / Backspace	Clear the current step and move back
F1	Octave down
F2	Octave up
Esc	Exit note input mode

Navigation (v1.9.6): arrow keys move the step and track cursor without modifying notes, enabling fast cursor positioning.

3.6 Polyphony

Each step can contain multiple simultaneous notes (chords). In polyphonic mode each note is called a voice.

Enabling Polyphony

In the Note Editor, click Make Polyphonic on any monophonic step. The existing note becomes the first voice.

Managing Voices

Control	Description
Radio button	Select the active voice (highlighted in red)
Note / Oct / Vel	Per-voice note, octave and velocity
SF2 Instrument	Per-voice SF2 preset override
+	Add a new voice
−	Remove the last voice
Convert to mono	Collapse back to monophonic, keeping the first non-rest voice

Polyphony in the Synthesiser

Each oscillator node handles polyphony automatically. All voices are generated and mixed, then normalised by dividing by the number of active voices (equal-power mix). The step-level amplitude acts as a master gain.

3.7 Automations

Automations expose time-varying float values to Blender's driver system as spline curves.

Creating an Automation

Click + in the Automations panel to add a new curve.
Set the Driver variable name (e.g. FilterCutoff).
Set the Duration (s).
Click Insert to VSE to place the strip at the current frame.

Editing the Curve

Control points have t (normalised time 0–1), value, and interpolation mode. Interpolation modes: Bezier, Linear, Constant.

Using an Automation in a Driver

# Value updated every frame (global variable):
auto_FilterCutoff

# Function form (reads any specific frame):
tracker_auto("FilterCutoff", frame)

3.8 Cue Points

Cue points are standard Blender timeline markers managed through a dedicated interface.

Adding a Cue Point

Click + Cue to open the add dialog:

Field	Description
Section	Predefined musical section names or "Custom"
Name	Custom name (shown only when Section = Custom)
Color	Marker color: White, Red, Orange, Yellow, Green, Cyan, Blue, Purple, Pink

Exporting Cue Points

Click Export JSON to save all markers:

{
    "cue_points": [
        {
            "name": "Chorus",
            "frame": 192,
            "time_sec": 8.0,
            "time_str": "00:08.00",
            "color": [0.2, 1.0, 0.3]
        }
    ]
}

Importing Cue Points

Option	Description
Duplicates: Skip	Skip markers that already exist at the same frame with the same name (default)
Duplicates: Replace	Remove all existing markers before importing
Duplicates: Add All	Add all markers without checking for duplicates
Use stored frame numbers	Place markers at the exact frame numbers in the file

3.9 Spreadsheet Grid Viewer

The Tracker_Viewer mesh exposes the active track's step data as vertex attributes, visible in the Spreadsheet editor.

Available Attributes

Attribute	Type	Description
Step	INT	Step index (0-based)
Note	INT	Note index (0–11, −1 = rest)
Octave	INT	Octave
Velocity	FLOAT	Step amplitude
Duration	FLOAT	Duration in seconds
Playing	BOOLEAN	`True` for the currently active step
Poly	BOOLEAN	`True` if the step is polyphonic

3.10 Playback Modes

PATTERN mode

Loops the selected pattern indefinitely
Step timing derived from BPM and scene FPS
Updates the step cursor in the Note Editor in real time

VSE mode

Follows COLOR strips in the VSE arrangement
Every strip with an audio_pattern_idx property activates the corresponding pattern during its frame range
Works without the Spreadsheet editor open

Topological playback order (v1.9.5): in both playback modes, tracks are evaluated in topological dependency order (Send graphs before Receive graphs).

4. Sample FX — VSE Effects Rack

The Sample FX panel is a non-destructive, ordered effects chain for audio strips in the Video Sequence Editor.

4.1 Opening the Panel

Open the Video Sequence Editor (VSE).
Select an audio strip (type SOUND).
Press N to open the sidebar.
Go to the Sample FX tab.

4.2 Strip Controls

Control	Description
Mute	Silences the strip
Solo	Silences all other audio strips

Isolate Entire Strip

When enabled, effects are applied only to a sub-range of the strip:

Field	Description
Start / End	Start and end frames of the processing zone
Use VSE Strip Bounds	Copies the bounds from the strip automatically

4.3 Effects Chain

Effects are applied in order from top to bottom. Order matters — a Compressor before a Reverb sounds different from a Reverb before a Compressor.

4.4 Complete Effects Reference

All effects listed in §2.4 are available in the VSE rack with equivalent parameters. Additionally:

Reverse

Reverses the audio signal in time. No parameters.

Invert Phase

Multiplies the signal by −1 (180° phase flip). No parameters.

Silence

Zeros the signal. Useful for controlled muting in a chain. No parameters.

Freq Splitter (Parametric) — VSE variant

Unlike the node version, the VSE variant cannot output multiple signals. Use the Output Band selector to choose which band (Low / Mid / High / Mix) passes downstream.

Peak Controller (Sidechain) — VSE variant

Parameter	Description
Sidechain Channel	VSE channel number of the trigger strip (must be a SOUND strip)
Threshold	Amplitude threshold
Depth	Ducking depth (0 = no effect, 1 = full mute)
Attack / Hold / Release	Envelope timings
Mix (Wet)	Dry/wet balance
Invert (Gate)	Inverts the effect

Normalize — VSE variant

Offline two-pass normalisation. Analysis runs at bake/export time, not during preview. Analysis is capped at 30 seconds (v1.9.5).

Noise Gate — VSE variant

Same parameters as the node version (see §2.4).

4.5 Preview, Bake and Export

Preview FX

Plays the strip with all effects applied in real time. Click ▶ to start, ⏸ to stop.

Apply and Insert

Renders the modified strip to a new WAV file (original_name_FX.wav) in the same folder as the source, then inserts the baked file as a new strip and mutes the original.

Output format: 44.1 kHz, stereo, PCM 16-bit.

Export Final Video

Bakes all strips with active effects → _FX_BAKED.wav files
Inserts the baked files into the VSE
Configures the FFMPEG renderer (H.264 video + AAC 192 kbps)
Starts the MP4 render in the background

Output: Full_Mix.mp4 in the same folder as the .blend file.

5. Export Pipeline

WAV Export

Button: Master Control → Export VSE WAV (Full Mix)

Scans VSE strips with audio_pattern_idx
For each strip, iterates at BPM-derived resolution (1 step = frames_per_step frames)
Per step: calls get_sound() on all linked AudioOutputNodes
Delays each sound to the correct strip-local timeline position and sums
Applies equal-power stereo panning per track
Writes the WAV file (44.1 kHz, stereo, 16-bit PCM)

Timing fix (v1.9.5): step delay is now calculated relative to the strip start rather than the absolute scene frame. BPM-aware timing (v1.9.7): the step stride is derived from tracker_bpm and the scene FPS instead of being hardcoded to 4 frames.

MP4 Export

Button: Master Control → Export Video MP4 (Full Mix)

Bakes audio to a temporary WAV
Mutes original tracker strips in the VSE
Inserts the baked WAV into the VSE (channel 32, frame 0)
Configures FFMPEG: H.264 + AAC 192 kbps
Starts the render in the background

Automatic Pre-Render Bake

Every time Ctrl+F12 is pressed (render animation), the auto_bake_before_render handler automatically bakes the tracker. No manual export is required.

JSON Export / Import

Serialises all patterns (name, length, tracks, steps, SF2 presets, polyphonic voices, pan, node_tree_name) and automations. Import appends to the existing scene without overwriting.

Index safety (v1.9.5): after importing JSON, active_pattern_idx and active_track_idx are reset to 0 immediately after clearing the pattern list, preventing out-of-bounds access during concurrent redraws.

MIDI Export — File Naming (v1.9.8)

Multi-pattern MIDI export uses the naming scheme {index:02d}_{safe_pattern_name}.mid. Characters unsafe in file names are replaced by underscores.

6. Drivers and Automations

Global Variables in Driver Expressions

Variable	Type	Description
`auto_AutoName`	float	Current value of the `AutoName` automation (updated every frame)
`tracker_auto("Name", frame)`	float	Reads the automation value at a specific frame

Example: Animated Filter Cutoff

Create an automation FilterCutoff with duration 4 s
Add two control points: t=0 value=200, t=1 value=3000, interpolation Bezier
Click Insert to VSE
In a Lowpass node, right-click Frequency → Add Driver
In the driver expression type: auto_FilterCutoff
Start playback: the cutoff frequency follows the automation curve in real time

Driver Troubleshooting

If drivers do not update after loading a file, the update_drivers_on_load handler reinitialises variables automatically. If needed, run manually in Scripting:

import bpy
bpy.app.driver_namespace["tracker_auto"] = lambda name, frame: 0.0

7. Technical Notes and Limitations

Step Resolution and BPM

Step duration is derived from the global BPM setting: step_duration = 60 / BPM / 4. Changing BPM recalculates all step durations immediately. The old hardcoded value of 4 frames per step has been replaced by a float frames_per_step in both playback and export engines (v1.9.7).

Audaspace Constraints

aud.Sound.limit(a, b) truncates time, not amplitude. There is no native amplitude clipper — distortion effects use an IIR filter as a workaround.
Real-time pitch modulation (varispeed / scrubbing) is not available in Python-accessible Audaspace. Pitch can only be set as a static float.
Real-time normalisation requires two passes over the audio data; it cannot be performed during live playback. The Normalize node uses a pre-calculated gain instead.

Polyphony

Each oscillator node is monophonic per step in its base form. Polyphony is handled at the step level: multiple voices are generated as separate aud.Sound objects and mixed before post-processing.

No VST / VSTi Support

Audaspace has no API for loading or hosting VST plugins. VST support would require a native C/C++ host and a real-time bridge to Python — outside the scope of a Blender add-on.

SoundFont Support

SF2 files are parsed in pure Python using the standard struct module — no external libraries required. Supported features: multi-preset files, key ranges (v1.9.5), loop points, root-key pitch correction, correct wPresetBagNdx resolution (v1.9.5). Not supported: envelope generators from SF2 igen, velocity splits, modulation LFOs from SF2 modulators.

MIDI Import / Export

MIDI import supports Format 0 (single track, split by channel) and Format 1 (multi-track). Format 2 is rejected. Note quantisation is applied at import time. MIDI export generates Format 1 files with a dedicated tempo track.

MIDI export fixes (v1.9.4): delta times are serialised exclusively by the track builder; note-off priority sorting covers all 16 MIDI channels; meta-event helpers no longer embed a leading delta byte (v1.9.8), fixing step position errors in exported files.

Blender Compatibility

The add-on supports Blender 4.0 – 5.1. VSE collection access uses:

seq_col = getattr(vse, "sequences", getattr(vse, "strips", None))

to handle the API rename between versions.

Headless / No-Audio Environments

The audio device is lazy-loaded. If Blender runs in an environment without audio hardware (Docker, SSH, render farm), the failure is logged once and all audio functions return None gracefully without crashing Blender.

Context fallback (v1.9.5): _resolve_scene() now falls back to bpy.data.scenes[0] when bpy.context.scene is unavailable (headless environments, async handlers).

8. Changelog

v1.9.8

FEAT tracker/export.py: new OT_ExportMultipleMIDI operator. Opens a dialog showing all patterns with checkboxes and a directory picker. Each selected pattern is exported as a separate .mid file named {index:02d}_{safe_name}.mid. Convenience operators OT_MidiExportSelectAll / OT_MidiExportDeselectAll added. AudioPatternExportItem property group added as a temporary Scene.midi_export_items collection.
FEAT tracker/export_midi_operator.py: new OT_ImportMIDIMultiple operator. Uses the standard Blender multi-file selection API (files + directory). Each selected .mid file is imported as a separate pattern. Options (quantisation, BPM override, max steps, create trees) are shared across all files.
FIX tracker/midi_export.py (fix-meta-delta): _evt_track_name(), _evt_end_of_track(), _evt_tempo() and _evt_time_signature() no longer embed a leading \x00 delta byte in their return value. Previously each helper prepended a delta, and _build_track_chunk() added another, producing a spurious extra \x00 before every meta-event that caused all subsequent events to be misread by MIDI parsers.
FEAT tracker/operators.py: register() now includes OT_ImportMIDIMultiple.
FEAT tracker/ui.py: added Import Multiple MIDI… and Export Multiple Patterns… buttons to the Master Control panel.
FEAT tracker/export.py: export_json() now serialises scene.tracker_bpm; import_json() restores it and recalculates step durations via _recalc_all_step_durations().

v1.9.7

FEAT tracker/properties.py: added Scene.tracker_bpm (FloatProperty, default 120.0, range 20–300). Changing BPM recalculates step.duration on every step of every pattern via _on_bpm_changed(). Helper functions bpm_to_step_duration(bpm) and bpm_to_frames_per_step(bpm, fps) exported for use in playback and mixdown.
FEAT tracker/playback.py: replaced hardcoded 4-frame step stride with _get_frames_per_step(scene). New _get_step_idx() helper computes the step index using float division.
FEAT tracker/mixdown.py: replaced hardcoded 4-frame stride with bpm_to_frames_per_step(). New _iter_frames() iterator yields one frame per step with float-accurate positioning.
FEAT tracker/ui.py: BPM field added to the Master Control section. Disabled during animation playback. Read-only info row shows step duration (ms) and frames/step.

v1.9.6

FEAT tracker/ui.py: note input mode now supports arrow-key navigation. ← → move the step cursor, ↑ ↓ move the track cursor, both wrapping correctly. Navigation does not modify existing notes.
FEAT tracker/properties.py: added Scene.tracker_note_input_active BoolProperty.
FIX tracker/operators.py (fix-vse-new-effect): OT_AddPatternToVSE uses the length parameter instead of frame_end.
RESTORE tracker/ui.py: re-added "Insert Pattern to VSE" button in TRACKER_PT_Main.

v1.9.5

FIX nodes/io/base.py (fix-base-context): _resolve_scene() now falls back to bpy.data.scenes[0] when bpy.context.scene is unavailable, fixing silent failures in headless and async-handler environments.
FIX tracker/topology.py (fix-topo-sentinel): _resolve_pattern_cache_key() now returns the string sentinel "__unresolved__" instead of -1 for patterns not found in the scene.
FIX tracker/mixdown.py (fix-mixdown-time): step delay is now relative to the strip start frame, not the absolute scene frame.
FIX nodes/filters/normalize.py (fix-normalize-ui): OT_AnalyzeNormalize now reports the analysis duration cap and the actual seconds analysed in the Info panel.
FIX nodes/filters/noise_gate.py (fix-ng-tempfile-cache): gate control buffer cached in memory per parameter combination; temporary WAV written only once per unique parameter set.
FIX nodes/filters/peak_controller.py (fix-pk-tempfile-cache): identical in-memory cache applied to the ducking control buffer.
FIX nodes/__init__.py (fix-cache-invalidation): unregister() now calls invalidate_gate_ctrl_cache() and invalidate_duck_ctrl_cache().
FIX nodes/io/sf2.py (fix-sf2-keyrange): SF2 parser reads key ranges; sample selection respects keyRangeLo/keyRangeHi.
FIX nodes/io/sf2.py (fix-sf2-pbag): _parse_phdr() extracts wPresetBagNdx; _build_preset_zones() uses the correct bag range.
FIX utils.py (fix-freqsplitter-socket): connected_node_sound() detects AudioFreqSplitterNode upstream and calls _get_band_sound(output_idx) with the correct socket index. Previously Mid Out and High Out always returned the Low band.
FIX sample_editor/operators.py (fix-normalize-vse): _apply_normalize() limits the signal to 30 s before analysis.
FIX tracker/playback.py (fix-playback-topo): both _handle_pattern_playback() and _handle_vse_playback() now evaluate tracks in topological order.
FIX tracker/export.py (fix-import-json-idx): import_json() resets active_pattern_idx and active_track_idx to 0 immediately after clearing the pattern list.

v1.9.4

FIX nodes/filters/noise_gate.py: gate control buffer materialised as a numpy buffer with .copy().
FIX nodes/filters/normalize.py: LUFS IIR filter corrected; scipy vectorisation; dead branch removed; analysis capped at 30 s.
FIX nodes/filters/peak_controller.py: control signal materialised as numpy buffer; inversion in numpy; fallback corrected; hold parameter added.
FIX nodes/io/file.py (fix-file-cache): _path_cache key changed to (tree_name, node_name).
FIX nodes/io/receive.py, nodes/io/send.py (fix-bus-cache): renaming a bus now immediately calls invalidate_topology_cache().
FIX nodes/io/sf2.py: _last_abs_path is a class attribute; .copy() added after np.frombuffer().
FIX nodes/__init__.py: OT_SF2SelectPreset registered; register_sf2_load_post called; cache invalidation on unregister extended.
FIX tracker/export_midi_operator.py (fix3): append_to_existing no longer resets pat.length to 1.
FIX tracker/midi_export.py: VLQ serialisation corrected; delta encoding moved exclusively to the track builder; note-off priority sort fixed to cover all 16 MIDI channels.
FIX tracker/mixdown.py: separate L/R pan accumulators; exception type logged in stereo fallback; .resample() removed.
FIX tracker/operators.py (fix-track-bounds): bounds check on active_track_idx added in all operators.
FIX tracker/spline.py (fix-sort): sort_points() uses orig_idx for deterministic restore with duplicate t values.
FIX tracker/topology.py: cache key includes node and bus signatures; as_pointer() for stable identity; _topology_cache is a dict indexed by pattern key.
FIX tracker/ui.py: bounds checks on active_pattern_idx, active_track_idx, and active_auto_idx before array access.
FIX sample_editor/operators.py: Noise Gate and Peak Controller VSE variants use the shared buffer builders; each effect branch wrapped in try/except.
FIX sample_editor/properties.py: pk_hold property added to AudioModifier.

v1.9.3

Added Noise Gate node and corresponding VSE effect.

v1.9.2

Added Normalize node; LUFS analysis (approx. EBU R128).

v1.9.1

Added Peak Controller (Sidechain) node.

v1.9.0

Added Freq Splitter (Parametric) node with three independent output sockets.
Added connected_node_sound_multi() utility for multi-output nodes.

v1.8.0

Per-Track Graph Architecture: each AudioTrack owns a dedicated AudioNodeTree identified by node_tree_name.
Added Send and Receive bus nodes.
Added topology engine (Kahn's sort) for correct cross-graph evaluation order.
Added AudioTrack.pan (equal-power stereo panning).
Removed pattern_index / track_index node properties (replaced by tree-name resolution).

Documentation for Audio Nodes Tracker v1.9.8 — Blender 4.0 – 5.1

Name		Name	Last commit message	Last commit date
Latest commit History 121 Commits
generators		generators
nodes		nodes
sample_editor		sample_editor
tracker		tracker
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
audio_device.py		audio_device.py
audio_node_tree.py		audio_node_tree.py
logger.py		logger.py
mypy.ini		mypy.ini
pyproject.toml		pyproject.toml
ruff.toml		ruff.toml
sockets.py		sockets.py
utils.py		utils.py

Folders and files

Latest commit

History

Repository files navigation