File formats
Every file format FaustWave reads, writes, or distributes — in one place.
DSPs + libraries
| Extension | Content | Tool |
|---|---|---|
| .builder | Builder graph document (JSON: nodes, edges, polyphonic config, sample metadata) | DSP Builder module |
| .dsp | Faust DSP source — a process = ... definition | Faust DSP module + Faust editor |
| .lib | Faust library — collection of definitions, no process. Mounted into libfaust VFS via faust-library.mount. | Faust editor |
| .nodepack.json | Community node-pack manifest. Declares new node-kinds the Builder can use. | Build-tool / Hub install |
A .builder is JSON; you can edit it in any text editor. The schema documents itself — open one and read.
Knowledge + content
| Extension | Content | Tool |
|---|---|---|
| .md (book) | Markdown bundle with ## Section-headed blocks. Each section is a retrieval unit + optionally carries a YAML actions block. | Book Reader |
| .fwproject.zip | Exported project bundle — project.json + workspace.json + assets/ folder, zipped. Portable across machines. | Project import/export |
| .json (generic) | Free-form JSON editor — useful for node-pack manifests, app.json edits, etc. | JSON editor module |
Audio
| Extension | Read | Write | Notes |
|---|---|---|---|
| .wav | ✓ Full header (channels / rate / duration) | ✓ 32-bit float, Recorder default | Lossless, big |
| .flac | ✓ Bytes only (header parsing is TODO) | — | Lossless, smaller |
| .aiff | ✓ Bytes only (header parsing is TODO) | — | Lossless |
For non-WAV imports, channels / sample rate / duration land as zeros in the SampleEntry — playback still works (Faust's soundfile primitive handles arbitrary formats), but the metadata isn't there.
App state
| File | Purpose |
|---|---|
| app.json | App-shell preferences (theme, window state, audio devices, AI provider, active-project pointer). Per-install / machine-global. |
| project.json | The song — MixerTracks, sequencer patterns, routing, controller bindings, param bases, surfaces. Auto-saved. |
| workspace.json | How you were sitting — which documents were open, which track had focus. Travels with the project, but it is view state, not content. |
| assets/ | Per-project asset folder — the .builder / .dsp / .lib files referenced by the project. |
Both are JSON — readable, diffable, git-able. Don't hand-edit while FaustWave is running; the auto-save will clobber your changes. Edit while the app is closed.
Recordings
| Path | Content |
|---|---|
<userData>/recordings/<ISO-date>_<rand>.wav | 32-bit float WAV, stereo, project sample rate |
OS-specific userData:
- Windows:
%APPDATA%\FaustWave IDE\ - macOS:
~/Library/Application Support/FaustWave IDE/ - Linux:
~/.config/FaustWave IDE/
Sample store
| Path | Content |
|---|---|
<userData>/samples/<sha>/<filename>.<ext> | Original bytes, content-addressed by sha256 |
The folder structure is sha-prefixed — that's what lets samples.import be idempotent + content-addressed. The original filename is preserved inside the folder so the file is recognizable on disk.
Hub artifacts
When you publish to the Hub, your file uploads as an Artifact. The Hub serves it via /api/v1/artifacts/<id> URLs — those are the downloadUrl fields you see in hub.item.get responses. Artifacts live behind the item's visibility (public artifacts are CDN-cached; private artifacts require an authenticated download).
Where to go from here
- FaustWave — Builder § 2 — what's in a
.builder, how to round-trip + diff. - FaustWave — Builder § 3 — how samples land in the sample store (sha-keyed).
- FaustWave — Hub § 3 — publishing + artifact handling.