The production handbook

A detailed working handbook for sound design, rhythm, harmony, arrangement, mixing and checking a finished Volta piece.

Use this handbook when developing a larger piece or a detailed production brief. It connects musical intentions to instruments, patterns, routing and arrangement, then explains how to check the result. Begin with From loop to finished track for a shorter walkthrough, or The sound recipe book for a sound you can play immediately.

The numeric settings below are starting points for experimentation, not rules for a genre or promises about a particular artist’s sound. Keep the musical intention clear, make one change at a time, and listen to the result in context. The Language reference owns exact syntax and command names.

A production brief can be shared with a collaborator or an assistant. Include the musical goals, the Volta version, and any samples, libraries or presets the piece depends on. The later research and handoff sections describe that workflow in detail; they are optional when you are making music on your own.

Contents#

1. The research and implementation contract
2. The production model
3. Units, time, and modulation
4. Rhythm and groove
5. Pitch, harmony, and voicing
6. The synthesis palette
7. Sound design recipes
8. Samples, slicing, and resampling
9. Effects and routing
10. Arrangement and automation
11. A complete editable song
12. Libraries and advanced production
13. Capability boundaries
14. Implementation and verification
15. Genre guide and song brief template
16. Prompt for the research agent

1. The research and implementation contract#

Begin by turning an influence into a set of musical decisions: its rhythm, register, sound palette, structure and production tradeoffs. Then express those decisions as instruments, patterns, arrangement and mixer settings. Whether you work alone, with a collaborator or with an assistant, render and assess the actual song before judging the result.

A useful guide connects four things:

Do not stop at adjectives such as “warm,” “lush,” “heavy,” or “psychedelic.” Translate them into source spectra, pitch relationships, envelopes, modulation periods, rhythmic placement, register, processing order, and arrangement events. Give a useful initial value and an audition range where possible. Preserve uncertainty when several different techniques could explain the sound.

Keep three kinds of evidence distinct:

• Documented practice: cite the original source, date, and relevant passage or timestamp. Artist interviews, demonstrations, and technical documentation can establish a technique; a genre label alone cannot.
• Listening inference: name the reference recording and timestamp, describe the audible observation, and label the inferred production method as an inference. Do not claim to have heard material you have not accessed.
• Proposed Volta recipe: a way to achieve the musical target using the current engine. It need not duplicate the reference producer's equipment.

Separate identity-defining traits from common conventions and optional experiments. A genre guide should support several distinct songs, including sparse and dense variants, rather than prescribe one template with a new tempo. Use reference tracks to study production and form; specify original motifs, rhythms, and sound combinations for the composition handoff.

Authority when sources disagree#

Use the current compiler/engine and focused reproductions first, then the current reference surface. Exact parameter names, defaults, units, and accepted receivers live in compiler/src/params/, compiler/src/builtins.rs, and compiler/assets/docs-data.json. Compilation establishes validity; rendering and listening establish the behavior needed by a production recipe.

docs/spec.md, design proposals, and docs/notes/ are context, not a list of current limitations. Some older implementation sections still describe deleted TypeScript synthesis code. Desktop and browser now use the same Rust DSP engine; host facilities and asset loading still need checking on the intended target. The old browser divergence ledger is explicitly retired in native reference sound.

Do not repeat old claims that Volta lacks OTT, vocal processing, auto-pan, shimmer, send automation, track reuse, or composable pattern timing. These have implemented surfaces. Do not infer that every accepted feature works through every export host, either; see capability boundaries.

2. The production model#

Volta is a typed, pattern-first music language. A .volta file describes the performance; a compiler turns it into an audio graph and event schedule.

The ellipses in this table are placeholders. Every fenced volta example in this handbook is a complete, independent program; none needs an implicit preamble or an external sample bank. Save one block per file to audition it.

Writing conventions that prevent common mistakes#

• Bindings are name = expression; comments start with --. Put each top-level declaration at the beginning of its own line. There are no ordinary statement semicolons or JavaScript object colons inside value records.
• Calls use spaces: saw (freq pitch). A pipeline puts its subject on the left: notes |> transpose 12. Inside a transform slot, omit the subject: notes |> every 4 (transpose 12). Prefer pipes to ambiguous direct argument orders. Subject-first calls defines the overload rules.
• Use !"..." for explicit patterns. Plain string literals also work in known pattern slots, including play "saw" "c3 e3 g3". A sample name such as sample "piano" is a string identifying an asset, not a pitch pattern.
• Optional parameters can be named in a trailing record: reverb 0.5 { wet = 0.2 }. Names belong to each builtin's schema; do not transfer a plugin's parameter names to a Volta effect.
• Imports resolve modules, not preset brand names. Canonical importable sources and songs live in examples/songs/; browser copies under runtime/public/songs/ and runtime/public/lib/ are generated.
• Parenthesize a pipe chain before combining it: (saw … |> lpf …) * ampEnv, (a |> f) + (b |> g). Unparenthesized, the operator binds to the chain's last argument, and the error can point at the start of the chain instead.
• Pattern bindings must be declared before use; track and detector names tolerate forward references, a pattern name does not.
• Without a song, declared playback tracks can all sound together. Reusing dryT as wetT = dryT |> reverb 0.3 creates another playback track. Select the intended one in a scene to avoid accidentally doubling the part.

Classic patches and explicit graphs#

A classic patch with source automatically routes:

source → optional cutoff/resonance filter → × ampEnv → × gain

Omitted cutoff means no automatic filter. Omitted ampEnv means no automatic amplitude envelope. A helper envelope named filtEnv affects sound only when it feeds an audible field, such as cutoff.

An out patch owns the whole graph. Merely declaring ampEnv, gain, or cutoff does not apply them to out. Multiply the envelope and gain into the output explicitly:

timingVersion = 2
tempo = 120bpm
pluck = patch {
  ampEnv = adsr 3ms 150ms 0 60ms,
  filtEnv = adsr 1ms 110ms 0 30ms,
  gain = vel * 0.4,
  out = (saw (freq pitch)
    |> lpf (350Hz + filtEnv * 3200Hz) 2
    |> drive 0.15) * ampEnv * gain
}
main = play pluck !"c3 ~ eb3 g3" |> reverb 0.3 0.15

pitch, vel, and noteTrig are note-context inputs. freq pitch converts the played note to Hz. A custom patch must read vel to respond to velocity; the classic patch wiring does not insert velocity sensitivity on its own. trackParam "name" default reads a per-note custom parameter.

voices caps concurrent notes for a synth. Allow for chord size and release overlap; the same synth used by several tracks can share that capacity. voices = 1 is monophonic. Positive glide defaults to one voice; an explicit larger voices count enables polyphonic glide. See voice topology, polyphony, and glide.

3. Units, time, and modulation#

Use musical units deliberately#

At constant tempo, seconds per beat = 60 / BPM; beats per bar = numerator × 4 / denominator; seconds per bar is their product. At 120 BPM in 4/4, a bar is 2 seconds:

An LFO's cycle argument is its period: lfoSine (8c) takes eight bars per oscillation; lfoSine (1/8c) makes eight oscillations per bar. lfoSine @ 1/8c means the same thing. A bare fraction 1/8 is 0.125; in a rate slot it is 0.125 Hz, and in a seconds slot it is 0.125 seconds. Keep the c when you mean musical time. Under another meter, a fraction of a bar is a different note division. Tempo and linear time cover tempo and meter maps; do not assume every effect's baked delay follows a tempo ramp live.

New compositions use composable timing by default#

No timing declaration is needed. fast and slow survive pattern arrangement, stacking, and merges. Explicit timingVersion = 2 is still accepted. An older song can select timingVersion = 1 to retain legacy folds that discard a child's rate; review the musical change before migrating it.

• p |> fast 2: double the rate, halve the period and event durations.
• p |> slow 2: halve the rate and retain the complete longer phrase.
• arrange [[4, p], [2, q]]: play p over four cycles, then q over two; each cell starts its pattern at zero and repeats it to fill the cell.
• seq [p, q]: fit the complete periods into two equal slots of one cycle. This is explicit rescaling. It is not the same as two bars of music.
• stack [p, q] and par [p, q]: overlay their materialized schedules over a common period. Long, relatively prime periods can expand the event count.

Pattern arrangement and song arrangement share vocabulary but have different contents: notes in one, scenes in the other. See patterns.

State the scope of every control#

adsr attack decay sustain release uses durations for attack/decay/release and a level for sustain. Decay is the fall after attack; release begins at note-off. Short event gates can release a sound before a long attack develops. Give a pad enough note duration, and audition fast plucks against their actual grid. Envelope time controls latch at note-on; moving a knob need not reshape a note already sounding.

LFOs generally produce bipolar values, −1 to 1. lfoSine (2c) |> scale [200Hz, 2400Hz] produces a frequency control; |> scale [0, 1] produces a unipolar control. Keep physical units through the expression. cutoff = 300Hz + brightness * 3000Hz expresses an intentional frequency range.

Macros usually travel 0–1: brightness = macro 0.4. The optional modulation argument, as in motion = macro 0.5 (lfoSine (8c) * 0.2), sums onto the base and clamps to its range. A global macro modulation graph cannot depend on a particular note's pitch or vel. Scene automation drives the macro's base. Some insert controls map normalized macro travel to their own physical range; check the parameter schema before assuming direct Hz/dB arithmetic in every insert slot.

A top-level control binding such as x = smooth 10ms (stepSeq [...]) can be named from a patch field (cutoff = 300Hz + x * 3000Hz) or a track lane; the patch re-lowers it in its own context. An explicit type (x : Signal Control Normalized = ...) documents intent but is not required.

Not every slot accepts every signal. For example, note lanes for speed, pitch, velocity, and push are stepped; simple LFO gain/pan lanes can run continuously; granular controls may read at grain spawn. signal and stepSeq bridge patterns to control signals. Use smooth/withSlew where abrupt gates need soft edges. See pattern controls, unified time, and macro modulation.

For more involved motion, expressive modulation describes persistent control graphs, explicit shared identity with @shared, clock relationships, and note/event reset and gate behavior. Choose whether related parts share one moving state or have independent instances. A source that runs continuously can still feed a destination that reads only at note or grain onset; specify both the control's clock and the destination's read cadence.

4. Rhythm and groove#

A one-cycle literal divides a bar equally among its top-level items. Four items are quarters in 4/4; eight are eighths; sixteen are sixteenths. Whitespace groups are for readability, not extra beats.

Commas overlay; spaces sequence. Brackets with spaces subdivide; angle brackets alternate by cycle. A numeric 0 is an event, not a rest. Boolean masks use t and ~; !"0 1" opens both slots in a structural position.

Specify groove as relationships: which layer owns the pulse, where the backbeat falls, which subdivisions are late, and which hits are ghosts or accents. “Add humanization” is not a groove specification.

push is directed microtiming in signed milliseconds, positive late and negative early. Its lane is sampled at each event's onset on the lane's own cycle. swing is a rhythmic timing control; humanize adds deterministic jitter. Do not equate a Volta swing value with a DAW's displayed percentage without checking the resulting onsets. grooveOf "sample" 16 can extract a push lane from an actual recorded break when the asset is present.

timingVersion = 2
tempo = 120bpm
kick = patch { source = kick909 0.4 0.3 0.45, gain = vel * 0.6 }
snare = patch { source = snare808 0.5 0.45, gain = vel * 0.35 }
hat = patch { source = hat606 0.12 0.55, gain = vel * 0.22 }
kickT = play kick !"c2 c2 c2 c2"
snareT = play snare !"~ c3 ~ c3" |> push !"0 9 0 6"
hatT = play hat (!"c5=0.8 c5=0.4 c5=0.65 c5=0.45 c5=0.8 c5=0.4 c5=0.65 c5=0.5"
  |> lastOf 4 (ply 2)) |> push !"0 6 0 8 0 6 0 10"

Audition the unprocessed rhythm before adding layers. A fill should have a defined job and frequency: every fourth bar, the last beat before a drop, or a single section ending. Increasing every layer's density at once obscures the groove. A rest or removed kick can create more tension than another riser.

Variation is deliberate and reproducible#

degradeBy, sometimesBy, shuffle, scramble, someCyclesBy, mini-notation ? and [a | b], and runtime choices supply different kinds of variation. Every draw is fresh each cycle: degradeBy punches different holes every bar. randomCycles = N (1–64) repeats the draws every N cycles; randomCycles = 1 keeps the same holes every cycle, for a groove that must not wander. wchoose is a fixed weighted rotation (each pattern for round(weight) cycles, in order); chooseBy and whenSig select precompiled alternatives at cycle boundaries while audio runs.

The module has a deterministic default seed (0x5EED); there is no general top-level seed = ... composition control to invent. Declaration identity and performance coordinates also affect seeded choices. Refactoring or renaming randomized material can change it, so retain the source used for an accepted render. Use explicit fills when a particular event must happen at a particular boundary. See track reuse and patterns.

5. Pitch, harmony, and voicing#

key = "c minor" establishes an ambient key for scale degrees and roman-numeral chords; it does not automatically correct every explicit note. Name register and octave as well as pitch class. A bass note, chord inversion, and melody can share a harmony while doing different musical jobs.

• !"i VI iv VII": roman-numeral harmony under the declared key.
• !"^0 ^2 ^4": scale degrees, starting at zero.
• !"c3:min ab2:maj eb3:maj bb2:maj": explicit chord roots and qualities.
• chord "c3" "maj7", voiceLead, arp "up", transpose, and inScale (tonality "c dorian"): chord construction, voice motion, arpeggiation, register changes, and scale constraints.
• voiceLines: persistent voice identities, including solved voicings where supported; useful for independently gliding chord voices.

Define a harmonic timeline shared by bass and chords. Check roots, chord tones, inversion, and change boundaries together. Do not generate the bass's “fifth” by adding seven semitones regardless of chord quality; diminished and other altered chords need their actual tones. A two-bar chord against a four-bar bass progression is a different composition, not a harmless coding variation.

This example makes each harmony last two bars, for an eight-bar progression. The bass adopts a quarter-note grid; the chord adopts two stabs per bar:

timingVersion = 2
tempo = 120bpm
key = "c minor"
sub = patch {
  source = sine (freq pitch), ampEnv = adsr 3ms 100ms 0.7 30ms,
  gain = vel * 0.45, voices = 1
}
keys = patch {
  source = triangle (freq pitch), ampEnv = adsr 4ms 160ms 0.2 90ms,
  gain = vel * 0.2, voices = 8
}
roots = !"<c2 ab1 eb2 bb1>" |> slow 2
chords = !"<c3:min ab2:maj eb3:maj bb2:maj>" |> slow 2
bassT = play sub (roots |> struct !"t t t t")
keysT = play keys (chords |> struct !"t ~ t ~") |> reverb 0.3 0.15

A melody needs a recognizable motif, contour, rhythmic identity, register, and planned variation. Record which notes are chord tones, passing tones, or tensions. A constant stream of arpeggios is not a substitute for this decision.

Tuning can be 12-TET (default), edo N, just ~Root, adaptive, or a custom tuningOf cents table. tuned adjusts supported partial banks to a declared lattice; spectralTune retunes spectral peaks in audio. These are available for a musical reason, not obligatory demonstrations of features. See harmony, counterpoint, tuning, and spectral tuning.

6. The synthesis palette#

The producer should select a mechanism for the required sound, not request every synthesis method in every song.

Filters have different jobs and parameter meanings#

lpf, hpf, and bpf take an audio source, cutoff, and Q. A patch's automatic cutoff filter is convenient; use an explicit source chain for a particular character: svf/svfMorph, ladder, diode, korg35, or zFilter. formant creates vowel-like resonances; comb makes a delay-related resonant series. Do not treat all “resonance” controls as interchangeable: zFilter's Q-like slot controls poles, and zero is bypass; ladder, diode and korg35 read resonance as a normalized 0–1 amount and refuse a Q-tagged value (svf/svfMorph read a real Q). Filter overdrive can affect both tone and level. Check the filter and effect references before translating a hardware setting numerically.

Layering is an arrangement and gain decision#

Give each layer a job: sub fundamental, bass harmonics, transient click, chord body, upper shimmer, noise air, or stereo decoration. State register, bandwidth, level, phase relationship, and envelope for each. High-pass a decorative layer when its low end competes with the bass, but do not high-pass everything by habit. Distortion and unison can generate additional low-frequency energy.

Oscillator unison count is different from note polyphony. A six-note chord with seven oscillators per voice is already 42 oscillators before release overlap and effects. Unison spread is total detune in cents: 18Cents spans approximately −9 to +9 cents. Check width and phase in mono; more detune can weaken pitch focus or cause a moving low end.

7. Sound design recipes#

These are implementation starting points. Adapt the envelope to the note duration and tempo, balance at the mixer, and compare processed/unprocessed versions at similar loudness.

Pitched sub and long bass tails#

A centered sine gives a clean fundamental. Explicit note-on phase makes repeated attacks consistent: without one, each voice's oscillator starts at a seeded draw keyed on the track, cycle and event (engine/src/voice/eval_osc.rs), so the render is deterministic but every hit's transient lands at a different point of the waveform. Write |> phase 0 on the sine, and set the saw or pulse layer's phase before it is filtered. Short release and monophony help avoid overlapping low notes; lengthen the gate/envelope deliberately for an 808-style pitched bass. A note-pitched sine and the knob-tuned kick808 model are different instruments.

timingVersion = 2
tempo = 120bpm
sub = patch {
  source = sine (freq pitch) |> phase 0,
  ampEnv = adsr 3ms 160ms 0.75 35ms,
  gain = vel * 0.5,
  voices = 1
}
main = play sub !"c2 ~ c2 g1 ab1 ~ bb1 c2"

Add a quieter harmonic layer if translation to small speakers matters. Keep its level independently controllable; heavy distortion on the only sub voice can trade away fundamental stability. Tune kick and sub by listening to their combined decay, not just by matching nominal note labels.

Acid and resonant mono lines#

Use a saw/pulse, a resonant diode or other chosen filter, a fast filter envelope, accents, and intentional slides. A trailing _ slides out of that step into the following note and suppresses that incoming amp retrigger. glideMode = "legato" otherwise limits glide to overlapping notes.

timingVersion = 2
tempo = 126bpm
brightness = macro 0.3
acid = patch {
  source = saw (freq pitch)
    |> diode (180Hz + brightness * 1800Hz + filtEnv * vel * 2600Hz) 0.6 0.2
    |> drive 0.3,
  filtEnv = adsr 1ms 100ms 0 35ms,
  ampEnv = adsr 2ms 120ms 0.25 35ms,
  gain = vel * 0.6,
  glide = 55ms,
  glideMode = "legato"
}
main = play acid !"c2_=0.95 g2 c2=0.6 eb2 c2_=0.85 bb1 ~ c2"

Put the resonant filter before any further distortion stage when the target is resonance peaks clipping into a growl; the reverse order clips first and the peaks never bloom. The accent control source adds an accent-sweep behavior for appropriate mono patches; plain velocity can also open the filter and increase level. Describe which notes accent and which notes slide separately.

Reese, supersaw, pads, and chord stabs#

Detuned oscillators make a moving spectrum. For a reese, use a low register, moderate count, carefully chosen filtering/nonlinearity, and a separate stable sub when needed. For a pad, use a higher register, longer gates, slower attack and filter motion. For stabs, shorten the amplitude/filter envelopes and leave rhythmic gaps. jp8000 is a distinct seven-oscillator model with normalized detune/mix controls; do not feed it the cents values used by unison.

timingVersion = 2
tempo = 120bpm
openness = macro 0.35
pad = patch {
  source = saw (freq pitch) |> unison 5 18Cents 0.75 0.65 1Cents,
  ampEnv = adsr 250ms 400ms 0.65 700ms,
  cutoff = 700Hz + openness * 3000Hz,
  resonance = 1.2,
  gain = vel * 0.2,
  voices = 12
}
main = play pad (!"<c3:min ab2:maj eb3:maj bb2:maj>" |> slow 2)
  |> reverb 0.65 0.2 |> monoBelow 160Hz

FM bass, bells, and digital plucks#

fm expresses linear frequency deviation in Hz; a dimensionless modulation index from a synthesis text is not automatically the same knob. If a reference gives index β for sinusoidal FM, peak deviation is β times modulator frequency. Integer frequency ratios favor a harmonic relationship; other ratios can make metallic spectra. An index envelope can decay faster than the amplitude so a bright attack settles into a simpler body.

timingVersion = 2
tempo = 120bpm
bell = patch {
  indexEnv = adsr 1ms 180ms 0 80ms,
  source = sine (freq pitch + fm (sine (freq pitch * 2)) (indexEnv * 700Hz)),
  ampEnv = adsr 2ms 500ms 0 300ms,
  gain = vel * 0.3,
  voices = 8
}
main = play bell !"c4 ~ eb4 g4" |> pingpong (3/16c) 0.25 0.3

For PM, use phaseMod on a compatible carrier: a wavetable, fmOp, or plain sine promoted to an operator. PM depth is in cycles; fmOp self-feedback uses its own depth convention. Saw/pulse oscillators do not expose the same PM port. ringMod multiplies two signals; freqShift shifts all partials by equal Hz; pitchShift shifts them by a pitch ratio. These make different sounds. See FM.

Wavetable motion#

Stock tables are basicShapes, harmonics, pwm, formant, drawbar, fold, and crush. A table can also be made from harmonic frames or a sample. Specify scan range and speed, and whether it resets with a note or follows transport. A full-range scan is not always more useful than a small movement around a strong frame.

timingVersion = 2
tempo = 120bpm
table = wavetableOf [[1, 0, 0.2], [1, 0.5, 0.3, 0.2, 0.1]]
voice = patch {
  source = wavetable table (freq pitch) (lfoSine (4c) |> scale [0.1, 0.85]),
  ampEnv = adsr 15ms 200ms 0.5 150ms,
  cutoff = 3500Hz,
  gain = vel * 0.3
}
main = play voice !"c3 ~ eb3 g3"

Drums and percussion#

The circuit-drum arguments are mostly normalized 0–1 knobs, latched per hit, not seconds or MIDI notes. They have internal decay behavior and need not be wrapped in an ADSR that cuts off their body. Their tuning generally ignores the pattern's pitch; mesh is the pitch-tracked membrane exception.

For reference, kick808 tune spans a settled 30–90 Hz and its decay control maps approximately 80 ms–1.2 s T60; kick909 spans 40–110 Hz and approximately 60–720 ms T60. These are model ranges, not genre prescriptions or ADSR durations. Measure the resulting hit. hat606 can read trackParam "open" 0.12, with a hit such as c5(open=0.7) setting the decay for that trigger. See drum synthesis.

For designed percussion, combine a pitched body and a short filtered-noise transient, with separate envelopes. A tonal body oscillator takes the same |> phase 0 as a sub, for the same reason: leave its phase unset and each hit starts on a different part of the waveform. Keep the seeded variation where it serves the sound — pads and unison stacks. Describe the transient's level and duration instead of simply calling for a “harder” drum. Adding two kick layers can cancel or smear the body; audition their sum and the polarity/phase choice.

Physical, additive, and evolving textures#

modal takes a table of [frequency ratio, decay, amplitude] modes and an optional exciter. string supplies a plucked waveguide; bowed a driven bowed model; body hangs a modal resonator on another source. These can provide electronic percussion, bells, plucks, and unusual pads without samples. sympathetic adds pitch-selective resonances on a track/bus.

additive takes harmonic amplitudes; additiveAt takes explicit partial ratios and optional phases for inharmonic spectra. sawSpectrum, squareSpectrum, triangleSpectrum, pulseSpectrum, formantSpectrum, and gaussSpectrum construct spectra. Assign evolving amplitudes or drift to a few meaningful partials instead of adding arbitrary oscillators.

A continuous Shepard bank (octave-spaced lanes under a Gaussian loudness window) hides each lane's octave wrap only when the wrap happens in the window's quiet extremes. Stagger the lanes so they wrap at different moments; resetting every lane by an octave at the same instant leaves an audible seam even when the averaged magnitude spectrum is unchanged. In a signal graph the Gaussian is written exp2 (-1.442695 * x * x), which equals exp(-x²).

For drones, define several time scales: envelope/phrase motion, slow spectral motion, faster texture, and occasional events. wander, drift, lorenz, henon, orbit, and simulation sources can animate timbre. A random modulator needs a bounded range and a musical destination; random motion alone does not create form. Physical modeling, additive, partials, and simulation sources give the detailed surfaces.

8. Samples, slicing, and resampling#

An asset is part of the instrument#

A sample recipe must name the actual asset or describe a recording/synthesis task to create it. Record filename/bank name, source and permitted use, root pitch, BPM if rhythmic, duration, channels, useful regions, and any required variants or zones. A filename or a sample-like token compiling successfully does not prove the bank exists; missing assets can render silence.

sound !"bd ~ sn ~" uses named banks directly. sample "name" inside a patch allows custom filtering, envelopes, gain, and sampling verbs. A plain sample plays at its native pitch/rate until a modifier or lane changes it: sample "piano" |> pitched ~C3 tells the sampler which recorded pitch should map to C3. Do not assume C4 for every file. A sound pitch lane has its own pitchRoot control.

The same word can operate at different levels: sample "break" |> chop 16 configures a source whose events choose slices; chopping a sample pattern creates successive region events. rev reverses event order; reverse reverses audio. Specify both when the desired result needs both.

Current slicing caveat: the native source-slice branch does not apply speed as plain sample playback does. This was reproduced in the dated guide production audit and is visible in engine/src/voice/eval_sampler.rs. Do not promise a sliced speed sweep. For a fixed pitch treatment, use explicit pitched notes/root mapping, preprocess the source before slicing, or prove the exact combination with a short render. Pitch and slice selection are separate decisions; chopAt or sliceAt can select a region independently of pitched note events.

Synthesizing a sample without an external asset#

sampleOf duration (\t -> expression) builds a static mono buffer from a pure function of time in seconds. It is a load-time bake, not a live macro-controlled instrument, and its duration is capped at 30 seconds.

timingVersion = 2
tempo = 120bpm
tone = sampleOf 1s (\t -> sin (t * 6.283185307 * 220.0) * exp (0.0 - t * 4.0))
voice = patch {
  source = sample tone |> pitched ~A3,
  ampEnv = adsr 2ms 0ms 1 25ms,
  gain = vel * 0.45
}
main = play voice !"a3 c4 e4 g4"

Granular texture and playable grains#

sample handle |> granular creates overlapping grains from a buffer; grains "name" ~Root provides note-pitched grains. granularize operates on a track, either using a named buffer or the track's own audio. Grain controls have specific meanings:

• grainSize: each grain's duration. Shorter can become buzzy or transient; longer can smear attacks or preserve more source identity.
• grainRate: grains per second on average. Rate × duration in seconds is a useful approximate overlap count, not a fixed loudness law.
• grainPos: normalized position in the source. Give it a scan path or intentionally hold an expressive region.
• grainPitch: playback ratio, not semitones. grainPitchQuant snaps ratios to a specified semitone set at spawn.
• grainSpray: position scatter as a duration; grainPan: stereo scatter; grainWindow: the window shape, such as "hann" or "gauss".

Grain controls are generally sampled at spawn, so a movement changes new grains while existing grains finish. Do not choose a scan region by percentage alone: verify it contains audible material. More grains cost CPU and change level/texture. See granular synthesis.

Printing, mangling, and printing again#

print = bounceOf 2c (play voice pattern |> effects) renders a track expression at load time into a named sample handle. sample print plays the result. Dependencies bake in order; one print can sample an earlier print. bouncesOf builds a generation chain. Use this for committed distortion, re-chopping, granular transformations, and treating a phrase as one instrument.

timingVersion = 2
tempo = 120bpm
original = patch {
  source = saw (freq pitch) |> drive 0.25,
  ampEnv = adsr 3ms 100ms 0.3 45ms,
  cutoff = 1800Hz, gain = vel * 0.4
}
print = bounceOf 2c (play original !"c3 eb3 g3 bb3" |> reverb 0.3 0.15)
chopper = patch {
  source = sample print |> chop 8,
  ampEnv = adsr 2ms 0ms 1 20ms, gain = vel
}
cloud = patch {
  source = sample print |> granular
    |> grainSize 100ms |> grainRate 24Hz
    |> grainPos (lfoSine (4c) |> scale [0.1, 0.85])
    |> grainSpray 30ms |> grainPan 0.5,
  ampEnv = adsr 180ms 100ms 0.8 350ms, gain = vel * 0.4
}
chopsT = play chopper !"0 3 ~ 7 2 ~ 5 1"
cloudT = play cloud (!"c3" |> slow 2) |> reverb 0.6 0.2
demo = song {
  scenes = { chops = [chopsT], texture = [cloudT] },
  arrange = arrange [[4, chops], [4, texture]] |> once
}

Important print semantics:

• bounceOf is a top-level declaration. Its track target is a play/sound expression and pipe chain; do not assume a bare track binding is accepted.
• The length is grid-exact with no added release tail. Choose a window that contains the intended phrase, or plan the cut/loop deliberately.
• Macros bake at their declared initial values. Moving a live knob does not continuously reprint a sample. Record a performance if its gestures are the material you need to preserve.
• A track print preserves authored level while compensating for device and voice headroom that replay would otherwise apply again. Additional vel, envelopes, filters, and mixer attenuation in the new sampler still compound. Check each generation's level before blaming the bake.
• tap inside an isolated track bounce reads silence because the other track is absent. A master print has access to the mix.
• bounceOf Nc master prints the simultaneous mix, excluding tracks that play that print to avoid self-inclusion. It does not walk the song arrangement. Use arranged offline export to capture the actual form.

For collage built from a complete finite score, complete-song sources provides songSource: a prepared child performance retaining its own arrangement, tempo/meter, automation and mixer. It differs from printing a simultaneous master mix. Check its preparation, source-control and asset/host limits before promising an interactive or portable result.

Recordings can be assembled with comp [take ...] |> fades ...; autosample can capture playable sample banks from hardware or supported hosted instruments. Multisample zones, velocity layers, and variants require the correct manifest and loader; a single repitched recording is not automatically a full sampled instrument. See sampler, slice, warp, stretch, bounce, sample synthesis, tracking, multisample, and autosample.

9. Effects and routing#

Place processing at the right level#

Per-voice effects process each note separately and follow that voice's lifetime. Put drive, fold, voice chorus, or a character filter inside a patch when the effect is part of the instrument.

A voice-level name (drive, chorus, phaser, tremolo, glitchShift, zFilter, vca, …) is refused on a track, not silently relocated. Conversely gain, pan, and velocity are track pipes carrying per-event lanes, never pattern pipes; a static placement belongs in the mixer strip.

An eligible ordinary audio function can instead become a persistent track, bus or master insert through audioFx. This makes reusable processing graphs possible without pretending a direct voice-effect call accepts a track. Such an insert has no note-local pitch or velocity. See audio functions and causal routing for audioFx, inline detectors, staged tapLive sources and insertPoint boundaries.

Track inserts process the summed track, with shared state and overlapping tails. Apply them after play/sound. Some names dispatch by receiver: delay on a track is a track delay; voice eq is a fixed three-band tone control while track eq takes a parametric band list. Explicit names such as delayTrack and eqTrack are useful when clarity matters.

Aux buses process signals sent from one or more strips and return to the master. A group is a VCA; it is not an audio subgroup. Track sends currently tap before track inserts: sends are post-strip/pre-insert and presends are pre-strip. A reverb send will not automatically receive the track's later insert distortion. Design the voice/routing/print accordingly.

voices → strip → track inserts → master
             └→ post-strip send → aux effects → master
       └──────→ pre-strip send  → aux effects → master

For a conventional shared reverb, explicitly choose a fully wet return (reverb amount 1) and set space from send levels. Defaults often include a dry component, which can double the dry signal when used as a return. Effect mix laws differ: some are crossfades, others add wet audio. Do not assume that every mix = 0.5 means the same balance.

Choose effects by audible purpose#

Useful distinctions for briefs:

• compress/optical/fet are simplified amount-driven processors, not a universal compressor with every threshold/ratio/knee control exposed. Specify the audible compression behavior, then choose the available tool.
• mbcomp is downward multiband compression. ott combines upward and downward compression; its depth scales gain travel rather than being an ordinary wet/dry blend.
• reverb amount affects decay and, when omitted, its derived wet value. Specify wet explicitly when separating size from level.
• galactic's replace runs toward a shorter tail as it increases; zero freezes and stops admitting new input. It is not a conventional “more reverb” knob.
• shimmer places pitch shift inside reverb feedback. A dry octave doubling before reverb is a different topology.
• width is mid/side scaling and cannot manufacture side information from a perfectly mono signal. decorrelate and tripleSpread can create an image; haas can introduce mono combing. Low-end mono does not guarantee that all upper-frequency material will survive fold-down.
• tune/harmonize depend on monophonic pitch tracking. Do not feed a dense polyphonic mix and assume accurate harmony extraction. Vocoding requires both an audible carrier and a useful modulator.
• glitchShift has a deliberately unusual speed-based pitch law; its nominal intermediate “semitones” are not a guarantee of equal-tempered tuning.
• Processing with process/process2 has runtime cost and output guards; shape bakes a fixed transfer curve. Neither is a license to assume an arbitrary third-party DSP algorithm already exists.

The extensive effects reference describes the remaining character processors and their exact knobs. Also see EQ, BBD, convolution, spectral, vocal, and spatial.

Sidechain is an audio relationship#

For ordinary bus ducking, apply duck kickT depth attack release to the signal that should move. Name the detector track by its binding: the resolver refuses a misspelling at the argument, and rename/find-references follow it. The quoted spelling duck "kickT" is legacy (volta fmt --modernize rewrites it); bus, group and submix names, "input" and "master" stay strings. Write explicit 5ms/180ms durations: a bare number adopts the port's unit, so duck kickT 0.5 5 180 reads five and 180 seconds (the compiler warns). A missing or silent detector produces no pump.

follower kickT 5ms 180ms provides an envelope for a patch's amplitude, filter, or other modulation. A patch-level duck does not duck reverb already ringing on a separate return; put duck after the return's reverb to do that. duck is an envelope-controlled gain reduction, not a complete threshold/ratio compressor. The detector has a delayed window; audition very tight kick/bass relationships instead of claiming zero-latency transient avoidance.

Where the duck sits changes its character. Multiply the duck, gate, or follower term into the raw oscillator sum before the drive/filter stage — (raw * duckTerm) |> drive … |> lpf … — for a chain that blooms back into distortion as it recovers. After saturation the same term is only volume automation.

A predictable rhythmic pump can instead use a transport-locked control shape. State whether ducking should follow the audible kick, a dedicated trigger source, or a fixed rhythmic curve, especially during kick-free breakdowns. See follower and duck and cross-track audio.

Gain staging and mastering#

Use the right level mechanism:

Several velocity factors multiply together, then clamp. A gain = vel * 0.6 + 0.2 patch deliberately retains a floor even at zero velocity. A very quiet hook may be a low velocity multiplied by several envelopes/trims rather than an export fault. Preserve the distinction between musical dynamics and faders.

Balance kick, bass, and foreground first; add support layers around them. Keep room for coincident transients and release tails. Check the loudest section and the transition into it before deciding on master gain. Compression or limiting cannot recover a buried motif or fix a wrong bass note.

Give the brief a delivery context and a target, not an assertion that one LUFS figure is right for every genre. The CLI's default master target is −14 LUFS with a −1 dBTP ceiling; that is an export policy, not a genre rule. A louder club master and a dynamic ambient master can need different decisions. Record achieved integrated loudness, true peak, duration, and any limiting. Check the encoded delivery file too if a lossy format is produced.

Use limiter when needed, with explicit ceiling/release, but independently meter the final file. The engine also has device safety processing and export delivery processing; an authored master limiter is not the whole level path. Different true-peak meters have produced different readings in past production audits, so leave appropriate margin for the required deliverable.

Do not assume isolated stems reconstruct a mastered mix. Stems can each pass through sends and master processing; nonlinear processing, mix-dependent ducking, and master-only loudness targeting break a simple sum identity. --dry only bypasses master inserts, not all voice/track effects or sends. Define a separate render configuration when genuinely dry stems are required. See mixing, velocity, mastering, and interchange.

Gain staging for a print#

The numbers below are what the tools measure; they are not a genre rule.

• The master bus prints 3.1 dB under its inserts. The device stage multiplies the master by MASTER_GAIN = 0.7 (engine/src/mixer.rs) after the master inserts, and the true-peak limiter holds its internal ceiling 0.5 dB under the one you write. So an authored master limiter (-1dB) prints at about −4.6 dBFS, not −1. Do not chase −1 by driving that limiter harder; the delivery level is the export's loudness target.
• Faders at or below +6 dB. A fader far above unity is making up for a patch that is too quiet, and the level it adds is invisible to the compile checks. Put the level in the patch (gain) and keep the strip for balance. The TrackHeadroom estimate (doctor) is pre-fader and weights overlapping notes by the ampEnv; when the track's fader is past +6 dB it says "raise the patch, lower the fader" instead of "lower gain". The fader only picks that advice, so meter the mixer separately and rerender: moving gain across a nonlinear effect is not a null.
• Aim the loud sections' PLR at ≲ 11–12 dB for a −14 LUFS print. PLR is true peak − section LUFS. Above that, the print's peak limiter works on every hit and takes the loudness back from exactly the sections that were meant to be loudest: at −14, a drop with a PLR of 14–15 dB lost ≈ 4.8 dB while the quiet sections kept all of the gain. Lower it where the peaks are made: glue compression on the drum bus, or clip the kick on its own track or the drum bus. Not a master clipper: that pins every section to one peak, and the form flattens (equal section LUFS and PLR; measure_audio and render-manifest warn when every section lies within 2 LU).
• Low-pass noise sources at 16–18 kHz. Noise hats, glitches and unfiltered noise layers carry energy to Nyquist. The limiter's realtime 4× detector cannot see those inter-sample peaks, so the offline print verifies at 8× and lowers its own ceiling to compensate; on one measured set that spent ≈ 1.5 dB of loudness on content above 20 kHz. A lpf 17kHz on the source costs nothing audible.
• Choose −16 LUFS for dynamic, cinematic material. The same song that lost 4.8 dB per drop at −14 needed 5.3 dB less gain at −16 and its drops lost ≈ 1.3 dB. A lower target is a decision about contrast, not a failure.
• Ask the print what it cost. render-manifest --lufs -14 --max-loss 1.5 (and max_loss on MCP export_song / render_audio, --max-loss on volta export stems) caps what the limiter may take and prints quieter instead, saying so. Its sidecar lists each section's LUFS, true peak and PLR in the raw render and in the delivered print, and the gain each section kept — the limiter's cost section by section (mastering § "A loudness-loss budget").
• Read measure_audio bands against pink noise, not against each other flat: each band is a band-power level, and the bands span different widths. The reference table (pink noise relative to mid) is in MCP server under measure_audio; a mix whose presence and air sit 10–25 dB under the pink figures is dark, and one whose sections all read the same LUFS and PLR has a flat form.

10. Arrangement and automation#

An eight-bar loop is material for a song. A finished piece needs an opening, development, contrasting passages, transitions, and an ending appropriate to its intended use. Define an energy curve with density, register, timbre, bass presence, harmonic tension, and space, not only a rising master level.

For every section, specify start bar, duration, active tracks, harmonic phase, motif variant, automation endpoints, and the event connecting it to the next section. Include a DJ intro/outro only when the intended format needs one. Avoid treating 8/16/32-bar sections as mandatory for all electronic music.

Scene and timeline semantics#

• song { scenes = {...}, arrange = arrange [[8, intro], [16, drop]] } is a fixed form. It loops by default; append |> once for a single complete pass.
• scenes, edges, and arrange must be written literally inside song { … }; a top-level scenes = { … } binding referenced by name is rejected.
• Scene algebra can add/remove earlier scenes' track membership: drop = groove + [leadT] - [padT]. Automation is not inherited from a referenced scene; declare the new scene's controls explicitly.
• Track patterns follow the shared transport. A scene selects the active set; it is not a DAW clip launch that necessarily restarts every phrase. Check phase at entrances, especially when a progression spans several bars. at Nbars provides an explicit absolute track anchor.
• phraseOrigin "entry" gives a track an entry-relative phrase origin when that is the desired musical behavior. Use the documented alternatives for transport-relative or anchored phrases; check re-entry and seeking rather than assuming every new scene resets every pattern.
• A marker list is the song's timeline under any binding name — markers = form.markers [[0, "intro"], [8, "drop"]] and landmarks = form.markers […] mean the same thing. Binding it to the name markers shadows the stdlib name, which is why that spelling qualifies the call as form.markers. One list per module (a second is an error). Bar positions are zero-based; a marker at 8 begins the ninth notated bar.
• play voice pattern |> at 8bars |> once starts at that absolute location and plays one complete track-pattern cycle. If that pattern is multi-bar or contains multiple notes, once does not mean “one note.”
• A scene weight may be a sub-bar duration on a whole-beat boundary. In 4/4, [1Beat, hush] supplies a one-beat scene. Edge lead-ins have different limits; do not assume every timeline surface supports arbitrary fractions.

Transitions and motion#

An edge such as build -> drop : [1, [rollT]] overlays the transition track in the last bar before the incoming drop. replace makes the transition tracks play alone during that lead-in. It occupies outgoing time; it is not an extra bar appended to the arrangement. Use exact edges when a transition should happen only on one handoff; wildcard * -> drop applies to arrivals from any scene. Test repeated appearances of the same scene.

Scene with { brightness = ramp 0.2 0.8 } sweeps a macro over the section. sectionPos runs 0–1 inside the current section and songPos across the form; without song playback they read zero. Direct mixer addresses can automate a declared destination: padT.sends.hall = ramp 0.05 0.3, padT.level, or master.plate.mix. A site already controlled by a user macro can conflict with a direct-address automation; choose one ownership path.

For every automation row in a brief, give start/end values with units, curve or step behavior, time span, and reset behavior in the next section. Basic scene ramp is a linear endpoint instruction, not an arbitrary breakpoint curve. Use control expressions, smaller sections, or other supported scheduling tools when the contour needs more detail.

A useful transition can combine a roll, a rising filter/pitch, widening upper layers, a short bass withdrawal, a deliberate gap, and an impact—but choose only the moves that support the style. Make the incoming groove's first bar stronger through contrast. Check whether a long tail obscures the new kick or hook. See arrangement, linear time, and tapestop.

11. A complete editable song#

This is a 64-bar demonstration at 120 BPM: 128 seconds of arranged music before export tail. It uses synthesized drums, a shared four-bar harmonic cycle, a melodic motif, a ducked reverb return, a build, a transition replacement, and an ending. It is a structural example to adapt, not a genre template.

timingVersion = 2
tempo = 120bpm
key = "c minor"
brightness = macro 0.3

kick = patch { source = kick909 0.4 0.3 0.45, gain = vel * 0.65 }
clap = patch { source = clap909 0.3, gain = vel * 0.35 }
hat = patch { source = hat606 0.1 0.55, gain = vel * 0.22 }
snare = patch { source = snare808 0.45 0.5, gain = vel * 0.3 }
bass = patch {
  source = sine (freq pitch) |> phase 0,
  ampEnv = adsr 3ms 120ms 0.65 35ms,
  gain = vel * 0.55, voices = 1
}
lead = patch {
  source = saw (freq pitch) |> unison 3 12Cents,
  ampEnv = adsr 4ms 180ms 0.15 100ms,
  filtEnv = adsr 2ms 130ms 0 50ms,
  cutoff = 450Hz + brightness * 2200Hz + filtEnv * 1800Hz,
  gain = vel * 0.25, voices = 8
}
pad = patch {
  source = triangle (freq pitch),
  ampEnv = adsr 160ms 250ms 0.5 380ms,
  cutoff = 1600Hz, gain = vel * 0.2, voices = 8
}
riser = patch {
  source = noise |> hpf 500Hz 1,
  ampEnv = adsr 30ms 0ms 1 120ms,
  cutoff = 800Hz + sectionPos * 6500Hz,
  gain = vel * sectionPos * 0.14
}

roots = !"<c2 ab1 eb2 bb1>"
chords = !"<c3:min ab2:maj eb3:maj bb2:maj>"
melody = arrange [
  [1, !"c4 ~ eb4 g4"], [1, !"ab3 ~ c4 eb4"],
  [1, !"eb4 ~ g4 bb4"], [1, !"bb3 ~ d4 f4"]
]
kickT = play kick !"c2 c2 c2 c2"
clapT = play clap !"~ c3 ~ c3"
hatT = play hat !"~ c5=0.65 ~ c5=0.5 ~ c5=0.7 ~ c5=0.5"
bassT = play bass (roots |> struct !"~ t ~ t ~ t ~ t")
  |> duck kickT 0.5 5ms 160ms
leadT = play lead melody |> pingpong (3/16c) 0.25 0.35
padT = play pad chords
riseT = play riser !"c4"
rollT = play snare !"c3*16" |> velocity !"0.3 0.45 0.6 0.8"

bus hall = reverb 0.65 1 |> duck kickT 0.4 5ms 180ms
group drums = [kickT, clapT, hatT, rollT]
mixer {
  kickT = { level = -3dB },
  clapT = { level = -5dB, sends = { hall = -20dB } },
  hatT = { level = -8dB, pan = 0.15 },
  bassT = { level = -4dB },
  leadT = { level = -6dB, sends = { hall = -16dB } },
  padT = { level = -9dB, sends = { hall = -14dB } },
  riseT = { level = -10dB },
  rollT = { level = -8dB },
  master = { inserts = [monoBelow 110Hz, limiter -1dB 100ms] }
}
markers = form.markers [[0, "intro"], [8, "groove"], [24, "break"],
  [32, "build"], [40, "drop"], [56, "outro"]]
demo = song {
  scenes = {
    intro = [kickT, hatT] with { brightness = 0.2 },
    groove = [kickT, clapT, hatT, bassT, leadT] with { brightness = 0.4 },
    break = [padT, leadT] with { brightness = 0.2 },
    build = [kickT, clapT, hatT, leadT, riseT]
      with { brightness = ramp 0.25 0.85 },
    drop = [kickT, clapT, hatT, bassT, leadT, padT]
      with { brightness = 0.75 },
    outro = [kickT, hatT, bassT] with { brightness = 0.2 }
  },
  edges = { build -> drop : [1, [rollT]] replace },
  arrange = arrange [[8, intro], [16, groove], [8, break],
    [8, build], [16, drop], [8, outro]] |> once
}

The section starts are multiples of the four-bar harmonic cycle, keeping bass, chords, and melody aligned. The replacement roll occupies bar 39; the drop begins at bar 40. The lead's delay is a dotted eighth in 4/4; its reverb send is taken before that track delay. The outro removes harmonic layers for a clearer exit. A genre-specific version should change the rhythm, timbres, motif, form, and contrast as its research requires.

12. Libraries and advanced production#

Reuse instruments without hiding their behavior#

The canonical standard library sources are ordinary .volta files under examples/songs/. Inspect the source of an imported patch before assuming its velocity law, envelopes, root pitch, or effects. Imports are resolved relative to the project/module bundle; an external research agent should include the required module names in the handoff.

For example, an importable Foundations recipe is: import "creator_foundations" (rootSub), then bass = rootSub { tone = 0.4, body = 0.65, decay = 0.45, drive = 0.2 }, then play bass.voice !"c2 ~ c2 g1". The normalized decay here is the instrument's control, not an ADSR time. Consult the preset manifest for its intended range.

Use base with { ... } or patch from base { ... } for instrument variants. Parameterized modules create separately named instruments and macros per instance. A reusable track-effect function can be typed Track -> Track. Named track reuse copies the realized track while retaining its declaration's randomness, and a UI edit of a shared definition reaches every use. See stdlib, creator palette, parameterized modules, modules, namespaces, and track reuse.

Procedural composition and performance#

Compile-time lists, records, functions, recursion, map, fold, and related operations can generate harmonies, fills, and form. events and patternOfEvents expose patterns as data. These tools are useful for a controlled family of variations; they do not replace decisions about motif, contrast, or register. Keep generated results inspectable and avoid materializing huge combinations of unrelated periods.

songGraph supplies conditional, walk-driven form. Shreds use do, wait, trigger, and concurrent score operations for imperative timing and gestures. Some live decisions depend on external controls; an offline export cannot infer a performance that has not been recorded or specified. Prefer an explicit fixed arrangement for a song deliverable unless generative form is the intent. See programmability, programmability 2, shreds, and generative feedback.

Advanced audio graphs#

tap someTrack reads another track's bus with delayed feedback-safe semantics; tapLive reads the current block and requires an acyclic dependency graph. follower measures level, onsets makes triggers, playOn turns triggers into notes, and pitchOf provides a detected fundamental in Hz. vocode, specMorph, specMask, convLive, and resonate build audio-dependent instruments and cross-synthesis. The source must actually be active, audible, and available to the render. An isolated stem is not equivalent to a full mix with its detector and excitation tracks present.

feedback and feedbackAt create explicit signal loops with bounded feedback behavior. Give the loop a decay/damping/drive design and check its transient and steady state. shape builds a static transfer LUT from a scalar function; process runs a scalar kernel and process2 adds bounded state cells. These can implement missing small DSP primitives, but a custom kernel needs its own numerical and audio validation. See feedback, shape, user kernels, audio events, and pitch tracking.

morph a b t structurally interpolates compatible patches. It requires compatible shapes; it is not an arbitrary morph between any two recordings. For recorded sources use the relevant granular, spectral, or resynthesis path. Neural audio requires compatible model assets, backend features, and execution resources. neural/neuralMod, encode/decode, latent combinators, latentOf, latentPath, latentAxis, latentPlay, and latentScrub provide specialized timbre transformations; the latent surface has stricter backend requirements. See patch morph and neural.

Recording, hardware, and inspection#

MIDI devices, MIDI CC/MPE, OSC, Link, live audio input, loop recording, comping, and native plugin hosting can be part of a project. Name the exact dependency and capture plan. An instrument that only emits MIDI produces no Volta audio unless hardware output is returned or recorded. A live input cannot be reproduced from source alone. Native CLAP/AU/VST3 state and samples have their own portability requirements. Patch plugin export is a separate way to package a compatible Volta voice for a DAW, not proof that every host plugin renders inside a Volta offline song.

Use Source for the canonical score; Bench/Rack for inspecting and auditioning patches; Mixer for audio relationships; Scopes and spectrum displays for transients, spectra, and stereo; Lens for harmonic questions; and the profiler for load. Commit intended control changes to source or a recorded performance before judging a deterministic export. GUI control state and the on-disk score can differ.

See MIDI, connect, audio input, looper, tracking, native plugins, patch plugin export, bench tools, Lens, and cost model.

13. Capability boundaries#

Classify each recipe by its actual dependencies. “The compiler accepts it” and “the intended host can produce it” are different checks.

Consequential current boundaries:

1. Offline native plugins: the direct engine load used by ordinary offline rendering installs no plugin instrument host. Instruments can be silent and hosted effects can pass through. Compiling with a plugin feature alone does not establish offline hosting. Use a verified capture/print or a specifically tested host workflow, and identify the result as recorded plugin audio.
2. CLI sample loading: volta export stems --samples DIR loads flat WAV filenames as bank names. It is not the workbench's full sample manifest loader. Do not assume variant directories, zones, root metadata, or BPM metadata have been loaded. Missing banks can silently remove a part.
3. Bakes and assets: sampleOf, bounceOf, and generated wavetable definitions have engine bake paths; older statements that they categorically cannot render in the CLI are stale. Their external source assets and the particular host's preparation still need checking.
4. Arrangement versus print: bounceOf Nc master does not follow the arranged scenes. volta export stems does walk fixed form, including lead-in transitions. Conditional graph exports resolve under their export policy, not an imagined live sequence of knob moves.
5. Slices and speed: source slicing has the limitation described in sampling. Audition transformations in combination rather than assuming every modifier composes identically.
6. Stem context: isolated rendering changes sidechains, taps, and nonlinear bus interactions. Aligned files are not a guarantee of identical processing or of reconstructing the delivered master by summing.
7. MIDI interchange: SMF transfer is lossy. It does not preserve all audio synthesis, CC/MPE/glide, transition, or audio-trigger behavior; MIDI import quantizes and reduces polyphony. Audio-driven playOn MIDI export uses a grid stand-in. See interchange before promising DAW parity.
8. Realtime versus offline: many long-release, unison, grain, convolution, and spectral voices can exceed a realtime buffer budget while still exporting successfully. A DSP cost estimate is advisory, not a listening test or a measured guarantee on the user's machine.
9. Determinism scope: retain source, imports, asset bytes, sample rate, engine build, and relevant host settings. Live input, plugins, model implementations, and different execution targets can change reproducibility. Do not promise identical files across untested machines or builds.

For an unverified dependency, preserve the musical target and provide a substitution: native FM instead of an unavailable digital synth, a verified sample print instead of live plugin hosting, an explicit rhythm instead of live onset detection, or a simpler effect chain for realtime use. Describe what the substitute changes audibly. A workaround is not evidence that the requested original technique was performed.

14. Implementation and verification#

A production sequence for the implementation agent#

1. Read the genre guide, choose a particular song concept, and resolve the critical dependency/ambiguity list. Record the current code revision and chosen timing version. New work uses version 2 without a declaration.
2. Make or verify the assets and a minimal rhythm/bass pair. Compile and render a few bars with no mastering target hiding level problems.
3. Implement the foreground instrument and motif; audition it alone and in the rhythm/bass context. Fix attack, register, pitch, and level before layering.
4. Add harmony and support parts against one explicit harmonic timeline. Inspect events around every chord change, including the repeat seam.
5. Write the entire form, including transitions, section controls, and ending. Check every entrance/exit. Automate in source; do not rely on unsaved knobs.
6. Mix through the intended routing. Check low-end interaction, mono behavior, dry/wet balance, transient clarity, tails, and the quietest/strongest sections.
7. Render the complete arranged song, meter the actual output, and listen to the whole file. Make changes based on both musical and technical findings.
8. Deliver source, dependencies, audio, and a brief verification/limitations report. State what was compiled, rendered, measured, and heard separately.

Commands that exist in this repository#

Run from the repository root. These examples assume the complete program from section 11 was saved in examples/songs/ as my_song.volta. Use a fresh output directory so a new render does not overwrite an accepted delivery. None of these commands publishes or uploads the song.

# Build the current CLI, rather than relying on an older executable.
cargo build -p volta-cli

# Compile and save IR for inspection/reproduction.
./target/debug/volta --out=/tmp/my_song.ir.json examples/songs/my_song.volta

# Structured diagnostics; inspect the JSON's ok field and diagnostic levels.
./target/debug/volta --diagnostics-json examples/songs/my_song.volta

# Silence diagnosis; inspect findings, not just the exit code.
./target/debug/volta doctor --json examples/songs/my_song.volta

# Fast arrangement excerpt. Target off still retains the delivery ceiling.
./target/debug/volta export stems examples/songs/my_song.volta \
  -o /tmp/my-song-preview --cycles 8 --target-lufs off

# The full arranged form: do not supply a truncating cycle count.
./target/debug/volta export stems examples/songs/my_song.volta \
  -o /tmp/my-song-delivery --target-lufs -14 --ceiling-dbtp -1

# Explicit sample directory when using compatible flat WAV banks.
./target/debug/volta export stems examples/songs/my_song.volta \
  -o /tmp/my-song-sampled --samples /path/to/verified-flat-wavs

# Interchange, when requested.
./target/debug/volta export midi examples/songs/my_song.volta -o /tmp/my_song.mid

# Read-only formatting/modernization previews.
./target/debug/volta fmt --check examples/songs/my_song.volta
./target/debug/volta fmt --modernize --check examples/songs/my_song.volta

Replace the illustrative sample directory before running that command; the section 11 program needs none. The CLI exports master.wav and named stems at 48 kHz. Its default master is 24-bit and default stems float32; --bit-depth 16|24|float overrides the written format. --cycles overrides the render horizon; without a fixed arrangement the default is eight cycles.

--diagnostics-json reports compile success in the JSON and can exit zero even when ok is false. doctor findings are advisory and its exit status is not an audibility gate. doctor --samples=.../index.json uses a manifest for name checking; this is different from export's --samples DIR WAV loader. There is no generic volta render or volta export wav command to invent.

For synthesis-only stems, the CLI is a useful reproducible baseline. For full manifest loading, native plugins, neural assets, or custom capture paths, use and document the host/helper that actually supplies those dependencies. The repository's engine/examples/guide-production.rs is a specialized production helper, not an interchangeable spelling of the CLI. Keep input IR separate from output/measurement sidecars to avoid basename collisions.

What to check#

For a fixed-tempo song, calculate expected music length from its bar count. Tail rendering can extend that length. With tempo maps or varispeed, integrate the actual timeline/rate; don't apply the constant-tempo formula blindly. Inspect the beginning, every transition, the loudest passage, and the ending. Measure a quiet foreground stem in isolation: a non-silent master can conceal a nearly inaudible hook.

An independent meter can check the exported file when FFmpeg is available:

ffmpeg -hide_banner -i /tmp/my-song-delivery/master.wav \
  -af ebur128=peak=true -f null -

Measurement does not establish groove, genre identity, enjoyable timbre, or a compelling song. If an agent cannot listen, it should report that limitation explicitly and leave listening acceptance open. Do not call a render “mastered” solely because it reaches a target or contains a limiter.

For a new corpus song, follow the repository's canonical source/manifests and golden-IR conventions. Generated browser copies are never the editing target. Formatting and asset sync do not replace compiling the final saved source.

Debugging by symptom#

Delivery manifest#

Deliver the editable source with its imports, all required assets or reproducible generation instructions, and the finished audio requested by the user. Include an arrangement table, asset provenance/metadata, render command/settings, actual duration and meter results, and deviations from the brief. Label stems as processed or dry according to their real routing. Record listening acceptance separately from automated checks. If a substitute was used, name it and explain its audible consequence.

Handbook example validation#

At the dated baseline, all 11 fenced Volta programs compiled with a freshly built CLI and rendered through native export stems --target-lufs off. Short examples used four- or eight-cycle horizons; the resampling demonstration and complete song used their entire arrangements. Independent FFmpeg decoding and metering found finite, non-silent, unclipped master PCM. The complete song rendered 128 seconds of music plus a two-second tail, with all eight authored instrument parts non-silent in their isolated stems. Event checks confirmed the shared harmonic periods; audio-window checks confirmed the kick-free break and replacement roll at bar 39.

These checks cover the example programs and documented timing assertions. Human listening and browser interaction were not performed; the examples remain audition starting points.

15. Genre guide and song brief template#

For a research-to-composition handoff, produce a reusable genre guide and a concrete song brief when both are needed. A single-song request can use a concise version of the brief below. The guide defines a design space; the brief makes choices that the implementation can follow. Fill this template with specific values, evidence, and explicit uncertainties, removing inapplicable rows. Do not leave the implementation agent to invent every important decision.

# <Genre / subgenre / era> — production guide for Volta

## Scope and identity
- Subgenre, era/region, intended listening context, and neighboring styles.
- Three to six identity-defining audible traits, with evidence.
- Common but optional conventions; traits that would pull the result elsewhere.
- Range of valid approaches, including sparse/dense or restrained/extreme variants.

## Evidence and reference listening
| Claim | Source and date | Track/demo timestamp | Documented or inferred | Confidence |
|---|---|---|---|---|

Explain what each reference demonstrates. Link to the original source.
Distinguish producer statements from listening inference and proposed recipes.
Label unavailable listening material and unresolved disagreement.

## Tempo, meter, groove, and phrase grammar
- Sourced BPM conventions or clearly labeled starting choices; half/double-time interpretations.
- Meter, swing/groove relationships, normal phrase lengths and exceptions.
- Per-role onset grids for at least a main groove and a contrasting groove.
- Accents/ghosts, note gates, open/closed articulation, push in milliseconds.
- Fill vocabulary: exact placement, frequency, density, and interaction with bass.

## Harmony and melodic vocabulary
- Tonality/modes, harmonic rhythm, typical chord qualities or static-harmony practice.
- Register, inversions, bass/chord relationship, tension/resolution, voice leading.
- Motif contour and rhythm; development methods; explicit non-repeating moments.
- Tuning requirements, if any; separate conventional practice from experiments.

## Instrument recipes
Give each role its own recipe, with alternative implementations where useful:
- Role and audible target; why it belongs in this style.
- Source/layers, oscillator ratios or sample requirements, register and tuning.
- Amp, filter, and pitch envelopes: values/ranges with units and note duration.
- Filter topology, cutoff/resonance, saturation, phase/unison/mono policy.
- Modulation destination, rate/period, depth, shape, timing scope, reset behavior.
- Ordered voice effects, track effects, sends; initial mix position.
- Volta primitives/module; whether the code is tested or is conceptual pseudocode.
- Audible check, common failure, and fallback if a dependency is unavailable.

## Mixing and space
- Foreground hierarchy and spectral roles; kick/sub timing and phase plan.
- Sidechain source, destination, depth/recovery intent; breakdown behavior.
- EQ/dynamics/transient objectives; processing order and gain compensation.
- Stereo plan and mono check; reverb/delay timing, return wet law, tail policy.
- Delivery context and tentative loudness/peak targets, with musical rationale.

## Arrangement vocabulary
- Typical forms and meaningful departures; intro/outro requirements by use case.
- How energy changes through density, register, timbre, harmony, and silence.
- Transitions appropriate to the form: drops, refrains, gradual transformations,
  episodes, process changes or deliberate cuts; one-time events and variations.
- What distinguishes the second main section from the first.

## Volta capability and dependency map
| Technique | Volta primitive/module | Voice/track/bus/bake scope | Required asset/host | Verification | Fallback |
|---|---|---|---|---|---|

Separate implemented, asset-dependent, host-dependent, and unverified recipes.
Do not copy historical missing-feature claims without checking this baseline.

# Concrete song brief — <working title>

## Intent and chosen constraints
- Original concept, emotional trajectory, and intended format.
- Chosen BPM/perceived pulse, meter, tonal or non-tonal plan, approximate duration.
- New songs use timing version 2 by default; omit a redundant version header.
- Required style traits and deliberate creative departures.
- Dependency policy: native synthesis only, supplied samples, or a specified host.

## Score and sound inventory
| Track ID | Role/register | Patch recipe | Pattern ID | Harmony relationship | Level/pan | Sends/inserts |
|---|---|---|---|---|---|---|

Define every pattern ID as notes/hits or a numbered step grid, with duration,
velocity, articulation, microtiming, repeat period, and variation rules.
Use explicit rests. Define the shared harmonic timeline and bass pitches.
Supply an original motif rather than only asking for a catchy melody.

## Full arrangement
| Section | Start bar (0-based) | Bars | Active tracks | Motif/harmony variant | Energy change | Exit/transition |
|---|---|---|---|---|---|---|

Sum the bar counts and compute the intended music duration.
Specify phrase origins and whether gestures retain transport phase or restart.
For beatless or cue-based work, supply seconds/attention windows as appropriate
and reconcile them with the implemented arrangement and tail policy.

## Automation
| Destination | Scope | Start/end with units | Curve/steps | Bar/beat span | Value in next section |
|---|---|---|---|---|---|

## Assets and host requirements
| Bank/file | Provenance/use | Root pitch | BPM | Region/length/channels | Loader/capture path | Fallback |
|---|---|---|---|---|---|---|

## Acceptance and deliverables
- Source/import/asset files and requested master/stem formats.
- Exact musical checks: groove, low-end relationship, audible hook, chord alignment.
- Required transition and ending checks; at least one contrast specific to this song.
- Compile/asset/full-render checks, expected length, metering targets and actuals.
- Listening and target-host checks, including any that remain unperformed.
- Ranked unresolved questions and permitted substitutions.

A usable instrument row might specify: “Mono offbeat bass, C2–B2; sine core plus quieter filtered saw; 3 ms attack, roughly 120 ms decay, 0.2 sustain, 25 ms release; velocity opens the saw filter within 400–1800 Hz; dry centered sub; kick-keyed duck recovering before the next offbeat.” These are testable instructions. The research must establish whether that role and articulation suit its genre; this example is not a universal bass prescription.

16. Prompt for the research agent#

Copy this prompt together with the handbook and, when possible, the language reference. Replace the bracketed scope before sending it.

Research [genre/subgenre, era, and intended format] and produce a production
guide that will be handed to Codex to implement original songs in Volta.

Use the attached Volta production handbook as the capability baseline and
handoff contract. Use language.md/current implementation for exact syntax;
historical notes and design proposals do not establish current limitations.
If supplied, use production-library.md to choose relevant genre/technique/form
resources and production-sources.md for source context; read only the routes
useful for this scope. Otherwise follow the evidence distinctions in this handbook.
You are researching music and production practice, not proposing new engine
features. Do not require every Volta feature to appear in a song.

Explain the genre's defining traits, variation across relevant eras/subgenres,
rhythm and microtiming, bass/kick relationship, harmony and motifs, instrument
recipes, effect order, space/stereo, arrangement, transitions, and delivery.
Support consequential genre/artist claims with primary sources where possible.
Give recording/demo timestamps for audible observations. Label listening
inference, uncertainty, inaccessible audio, and conflicting evidence honestly.
For a hybrid, state which tradition supplies rhythm, timbre, harmony and form.
For beatless or non-tonal work, replace inapplicable drum/harmony requirements
with a specific material, spectral, spatial and temporal development plan.

Translate each technique into an audible target and a practical Volta route.
Give units, initial settings and useful ranges, event/note/section timing scope,
source assets, host requirements, and a way to check the result. Distinguish a
normalized knob from physical time/frequency and distinguish pitch from rate.
When you cannot verify code, label it conceptual and supply precise musical
instructions instead of inventing function names or claiming it compiles.

Use the handbook's genre-guide/song-brief template. Return a reusable guide
that can support multiple distinct compositions, followed by a concrete song
brief with an original motif, explicit groove grids, shared harmonic timeline,
instrument inventory, full bar-numbered form, and automation table. Include
alternative directions without leaving the concrete brief undecided.
For a set, map required techniques to songs, audible roles and checks, and
explain the shared identity and meaningful contrasts between pieces.

Rank essential traits separately from optional conventions. Include an asset
manifest, capability/dependency map, permitted fallbacks, acceptance criteria,
and a short prioritized list of unresolved questions. Preserve musical intent
when a dependency is unavailable and explain the audible cost of the fallback.
The final handoff should let Codex start implementing, rendering, and evaluating
the song without having to redo the genre research.