# 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.