The standard library

Import reusable instruments, patterns and helpers, then adapt them to your own songs.

What it is#

A curated set of reusable patches, effect chains, and rhythm patterns that ship with Volta as plain .volta source. They live under a served /lib/ tree and are pulled into a song with ordinary imports, so a newcomer can reach for a tuned kick, acid bass, or hall reverb instead of hand-spelling every voice. The library needs no compiler support of its own — it is built entirely on Reuse sounds and patterns with imports, and it composes the primitive DSP builtins (sine/saw, reverb, pingpong, …) rather than replacing them.

Surface#

Library modules group reusable sounds and tools, each importable by name. A song imports the bindings it needs and wires them with play, |>, and pattern literals:

import "drums"  (kick, snare, hat)
import "bass"   (acid)
import "keys"   (pad)
import "fx"     (hall)
import "rhythm" (fourFloor, backbeat, offbeat)

kickTrack = play kick fourFloor
padTrack  = play pad  (!"c3 ab2 f2 g2" |> slow 2) |> hall

The modules and their public bindings (as shipped):

Notable surface facts:

• Instruments may declare live knobs, namespaced by module (Macro Namespacing): the bass module ships bass.cutoff / bass.res macros (additive, default 0 — the voice is unchanged until you turn them up). Macro names are the one namespace the resolver qualifies, so two libraries never collide on a knob. drums (drums.punch), keys (keys.bright / keys.space), pads, leads, circuits, modal, mira, machines and the guitar modules declare knobs the same way (priv … = macro …); fx, pedals, vintage, rhythm and harmony declare none. To modulate any other field, still with-override at the call site.
• Effects come in two families (Voice signal flow §5). Bus effects (reverb / echo) are track-transform lambdas applied with play … |> hall — they live once on the mixer bus so tails overlap note-to-note (fx, and the pedals bus row: spaceEcho, spring, slapback). Voice effects (drive / modulation — chorus, phaser, flanger, bitcrush, drive, fold) are signal lambdas applied inside a patch source — source = saw (freq pitch) |> grit; wrap these audio functions in audioFx to process a track or return persistently. The pedals voice row (grit, warmth, dimension, phase90, flange, crush) covers these.
• vintage instruments lean on the voice's ZDF-ladder filter (the cutoff / resonance / filtEnv fields are Moog-style) plus source effects (unison supersaw, additive drawbars, fm operators, in-voice chorus / drive).
• Rhythms trigger on c2, so a pattern drives any drum patch: play kick fourFloor. They are concrete pattern literals (including euclidean clave = !"c2(3,8)"), not pattern-combinator lambdas.
• …and rhythmKit moves the whole set to another register. c2 is a kick's note; a snare wants c3 and a hat c5, and that single missing specialization is why 49 corpus songs re-type !"c2 ~ ~ ~ …" instead of importing it (Names and library imports §0.2). rhythm therefore also exports module rhythmKit(shift: Semitones), a Configurable library modules kit parameterized over the trigger register rather than a timbre: one application flattens into all six patterns transposed by shift, reached by qualified access — snares = rhythmKit { shift = 12 } then play snare snares.backbeat, play clap snares.backbeat. The register is named once on the application line instead of re-typed into every literal, and the fields are ordinary patterns, so tops.sixteenths |> degradeBy 0.5 still works. Pattern pipes, named offsets and reusable transforms now also work: shiftC3 = 12, then backbeat |> transpose shiftC3, or a helper up = \p -> p |> transpose 12. Use rhythmKit to choose one register for the whole kit; use a transform to vary a particular part. The rhythmlib preset (examples/songs/rhythmlib.volta) is the worked kit: an eight-track drum arrangement containing no note literal at all. Everything above rhythmKit in rhythm.volta is byte-frozen — an imported pattern's event source_offset points into that file, so inserting a line above the literals re-blesses the golden snapshot of every song that imports them.

The studio preset is the worked tour — it imports drums, bass, keys, fx and rhythm and builds intro/main/lead/outro sections. See examples/songs/studio.volta.

How it's implemented#

• Library source: examples/songs/ — one <module>.volta per row above (drums.volta, bass.volta, …). They are ordinary corpus files: golden_ir snapshots them, volta fmt checks them, and a song imports one by bare name because it sits in the same directory.
• Which files are "the library": runtime/public/lib/index.json, a flat JSON array of the module stems above. It is both the browser's boot manifest and the list runtime/scripts/sync-assets.mjs copies out of the corpus into runtime/public/lib/ — so adding a module means editing that one array. The copies themselves are generated and gitignored; edit them and the next sync throws your edit away.
• Loading: runtime/src/modules.ts — ModuleLibrary fetches /lib/index.json at boot, then each /lib/<path>.volta, and exposes the set as the bundle passed as compile's second argument (sources()). Imports resolve against this bundle exactly like any module (Reuse sounds and patterns with imports).
• Historical browser adapters (removed 2026-08-10): the old workbench's reference panel line-scanned each loaded module for its header blurb and public (non-priv) bindings, presenting Standard library and Your modules sections, and cmd/ctrl-click on an import "name" jumped there. Those TypeScript files were deleted with the workbench; see git history. The Rust workbench uses ui/src/docsview.rs for the canonical language reference and compiler-backed editor navigation, and does not ship that module browser.
• Compile test: compiler/src/lower/tests.rs (studio_song_compiles_against_the_standard_library) resolves, checks, and lowers examples/songs/studio.volta against the library bundle.

What the library can and cannot carry#

The boundary is measured, not argued: a builtin can become a library function only if the library spelling compiles to the same masked IR — same events, payloads, articulation and graph, spans and the source-hashed seed stripped. compiler/tests/library_equivalence.rs is that test, with a row per candidate, and its 2026-09-22 verdict over the candidates Language Foundations P6 named is that one shape carries and four do not.

A pattern constructor carries. A pattern is an ordinary value, so naming one in a module and importing it changes nothing but the source offsets: all six of rhythm.volta's patterns are byte-identical to the literals they replace. That is why the rhythm module never needed a builtin.

Four kinds of builtin cannot move, each for a reason that is about the language and not about the function:

And even a function that passed every row could only be added, not moved: the compiler reads no .volta source, so no builtin is implemented by a library definition. An import "m" (scale) does take the bare name over for that one file, which is the only shadowing that exists.

Notes & limits#

• Flat namespace. One module per concern — the Reuse sounds and patterns with imports namespace is flat and re-export is not built, so there is no lib/all aggregate or nested lib/drums/909.
• Live macro control is namespaced. The macro-naming question is settled: the resolver qualifies each library's macro names by module path (bass.cutoff), so two imported instruments never collide (Macro Namespacing). Which modules are knobbed is listed under Notable surface facts above.
• Concrete rhythms only. A rhythm of lambdas (every, swing shapes) awaits lambda pattern transforms; the shipped set is concrete literals, plus the rhythmKit register parameterization above.
• No stdlib versioning. A saved draft that imports a library can break if the library changes — Reuse sounds and patterns with imports punts on versioning and the stdlib is the first place that bites. Planned extensions (more instruments, effects, and rhythms) and the open core-vs-library boundary questions live in The standard library / ideas.md.

The Moving Parts preset demonstrates the mod controls and the same fx.filterMotion helper in a voice, track insert and return; see Modulation recipes.