Read Reference on the web

Read the same musical guides on the public site, hear featured examples, and continue into Studio when you want to edit.

What it is#

The public Reference is a place to explore sound before opening a project. You can read every guide without signing in, search the index by topic, and hear short examples directly in the page. Start here leads from a first sound through rhythm, melody, sound design and finishing a track.

Every example pairs a listening prompt with a complete program and something to change. Press the audio player's Play button to hear the supplied version; use Copy and open a new song in Studio when you want to make it your own. Open in the workbench opens the same guide inside Studio. It does not replace your song with the example automatically.

The site publishes plain HTML pages that work as ordinary web documents and can be found through search engines:

• volta.fm/reference/ and volta.fm/reference/<id>/ — one page per docs/reference/*.md document, grouped by the same categories the in-app Reference uses (docs/reference/categories.json).
• volta.fm/learn/ and volta.fm/learn/<id>/ — one page per lesson of the guided course, act by act, with the starter song, the goals, the riff prompt and the "further reading" link. The solution is not published; the page sends the reader into the workbench for that.
• volta.fm/sitemap.xml and volta.fm/robots.txt — the crawl contract.

Every page carries a real <title>, a meta description, a canonical URL, Open Graph tags, JSON-LD (TechArticle / LearningResource / Course + BreadcrumbList), and one Open in the workbench link that deep-routes into the app: /?view=reference/<id> (with an optional #anchor) and /?view=learn/<id>. A reader who lands on a doc from a search result is one click from the same document inside the workbench, or the same lesson with its starter loaded.

The front page itself is not noindex: its pre-boot block is a crawlable intro (what Volta is, links to the two indexes) with a description, canonical and Open Graph metadata, so volta.fm is linkable straight from a result. The twin shell studio.html and the two test pages are noindex with a canonical back to /.

Hearing and finding examples#

The Reference index has a title-and-summary search, category links and an ordered list of guides. Matches update as you type, with a count and a clear empty state. Inside a guide, On this page reveals the section list; previous/next links continue through its category. Keyboard users can skip straight to the main content.

Featured code blocks have native browser audio controls and a Copy button. Starting a second clip pauses the first. Audio uses preload="none", so browsing a long guide does not download its previews until you play one. Playback never starts automatically. The page remains readable, and native audio controls still work, with JavaScript disabled; live search, Copy and pausing other clips require JavaScript.

There are 51 distinct recordings (one per distinct volta play program, listed in runtime/public/reference-audio/index.json), reused wherever the same example appears. Each renders four bars plus a two-second tail through Volta's Rust engine, then encodes to 128 kb/s MP3 without normalization. These are demonstrations, not lossless exports. The browser audio player's volume changes playback level; it does not change the program. Use Studio to edit and hear a new version.

How it's built#

runtime/scripts/site-pages.mjs renders; runtime/scripts/gen-site-pages.mjs writes (and --checks). Both read the same sources the app reads, so the web pages cannot drift from the workbench:

The output lands in runtime/public/ (reference/**, learn/**/index.html, sitemap.xml) and is generated and gitignored, exactly like the song copies sync-assets.mjs makes: npm run dev/build/test regenerate it on their pre* hooks (npm run gen:site by hand). robots.txt, reference-reader.js and the Reference audio assets are tracked. Source-only verification stamps and reference-meta blocks are omitted from the published corpus; availability limits remain in the reader-facing text.

The Markdown renderer is dependency-free and covers what the reference docs use — headings (anchors taken from the corpus so cross-doc #anchor links land where the app's do), paragraphs, block quotes, nested lists with wrapped continuation lines, fences (including a four-backtick fence around a three-backtick one), pipe tables with alignment, rules, inline code, emphasis, links, autolinks, and wikilinks. Everything else is escaped as text: a doc line that starts with <dur> is prose, never markup. Wikilink resolution mirrors the corpus builder: [[reference/x#Heading|label]] becomes a link to /reference/x/#heading; a bare [[design-spec]] citation stays readable text with no dead link; [[verse, intro]] is a Volta list literal and is left alone.

Updating audio previews#

A volta play fence opts a complete, self-contained program into audio publication. Its trimmed source plus a final newline is hashed with SHA-256; identical sources share a file. A volta check fence opts a longer program into compiler and arrangement-render checks without publishing a short clip.

node runtime/scripts/gen-reference-audio.mjs
node runtime/scripts/gen-reference-audio.mjs --check

Regeneration needs the Rust toolchain, supplied samples and ffmpeg. Ordinary page builds use the committed MP3s and need none of those audio tools. The manifest records source IDs, peak/RMS/duration measurements, byte sizes and media hashes. Runtime tests reject stale source IDs, missing files and changed bytes. Regenerate after an intentional engine or sample change too: a source hash alone cannot detect a change in DSP behavior.

Deep routes in the workbench#

VoltaUi::set_view (ui/src/app/benchapi.rs) accepts two route shapes beside the view names the shell already knew:

• reference/<id>[#anchor] (also docs/…) — parsed with DocRoute::parse_compat, opened in the Reference overlay with Back to source as the return target. Malformed routes (reference/../x) fall through to the default view.
• learn/<id> — marks that lesson active and opens the LEARN overlay; the view's first frame asks the shell to fetch the lesson it does not hold yet, the same handshake a course click uses. Ids are [A-Za-z0-9_-]+ only.

The browser passes ?view= straight to set_view at start (index.html), and the host only restores tabs=/activetab= shell state, so the URL wins over the previous session's overlay.

Verified#

• engine/tests/reference_examples.rs compiles featured programs and renders their audio, including every part in isolation and the full-song guide.
• runtime/src/reference-reader.test.ts checks live filtering, empty states and pausing the previous player.
• runtime/scripts/reference-browser-test.mjs checks 375, 500 and 1600 px layouts, zero eager media requests, search, clipboard, two actual play actions, and decoding every MP3 in Chromium. These checks establish operation and measurable audio health; they do not establish listening quality or every browser/assistive-technology combination.

• runtime/src/site-pages.test.ts — renderer unit cases for each construct above; and, corpus-wide: one page per document and lesson, metadata on every page, no placeholder/raw-Markdown leaks, balanced tags, every internal href resolves to a generated page and (when fragmented) an anchor that page defines, both indexes link every page, the sitemap equals the page set, JSON-LD parses and cannot close its own script tag, solutions stay off the lesson pages, and the front page / twins / robots carry the intended metadata.
• ui/src/app/benchapi.rs deep_route_tests — the two routes open the right overlay and document/lesson; malformed routes fall back.
• Under npm run dev, curl /reference/filters/ and /learn/hello-sound/ serve the pages, and /?view=reference/filters boots straight into the Reference overlay on that document.

Notes & limits#

• Deployment shape. The pages ride the static workbench build; the Worker's route pattern must not answer /reference/*, /learn/*, /sitemap.xml or /robots.txt with its 404 (community.md "Domain & deployment").
• The canonical origin is a constant (SITE_ORIGIN = https://volta.fm) in site-pages.mjs; a staging deploy would need it parameterised.
• Pages are dark-only, matching the Worker's public pages; no light theme.
• Public index search covers titles and summaries. Studio's Guides search also covers headings and body text. Long guides keep their complete detail with a collapsible section list.
• lastmod is not emitted in the sitemap (no per-doc date source yet).