decibri · rossarmstrong · Aug 4, 2026 · Aug 4, 2026
diff --git a/docs/docs/apis/browser.html b/docs/docs/apis/browser.html
@@ -403,7 +403,7 @@ <h4><code>Microphone.version()</code></h4>
         </div>
         <div class="code-tab-panel" id="code-panel-11-browser" aria-labelledby="code-tab-11-browser" data-lang="browser" role="tabpanel">
           <pre><code class="language-javascript">Microphone.version();
-// { decibri: '5.0.0' }</code></pre>
+// { decibri: '<version>' }</code></pre>
         </div>
       </div>
 

diff --git a/docs/docs/apis/node.html b/docs/docs/apis/node.html
diff --git a/docs/docs/apis/python.html b/docs/docs/apis/python.html
diff --git a/docs/docs/audio.html b/docs/docs/audio.html
@@ -77,7 +77,7 @@ <h3>Acoustic Echo Cancellation (AEC)</h3>
         </a>
         <a href="/docs/audio/afp" class="doc-card">
           <h3>Audio File Processor (AFP)</h3>
-          <p>The offline source: run a recording, or samples already in memory, through the same conditioning chain, or score the whole recording for speech in one pass. The <code>File</code> class in Python and Node.js.</p>
+          <p>The offline source: stream a recording, or samples already in memory, through the same conditioning chain, score the whole recording for speech, or save the conditioned result. The <code>File</code> class in Python and Node.js.</p>
         </a>
       </div>
 
@@ -94,7 +94,7 @@ <h2>Related</h2>
         <ul>
           <li><a href="/docs/audio/ace">Audio Capture Engine (ACE)</a>: the built-in conditioning chain and its options</li>
           <li><a href="/docs/audio/aec">Acoustic Echo Cancellation (AEC)</a>: remove your own loudspeaker from the microphone capture</li>
-          <li><a href="/docs/audio/afp">Audio File Processor (AFP)</a>: the same chain over recorded audio, plus whole-recording speech analysis</li>
+          <li><a href="/docs/audio/afp">Audio File Processor (AFP)</a>: the same chain over recorded audio, plus whole-recording speech analysis and saving to disk</li>
           <li><a href="/docs/getting-started">Getting started</a>: install and first capture</li>
           <li><a href="/docs/integrations">Integrations</a>: connect conditioned audio to STT, TTS, VAD, and KWS providers</li>
           <li><a href="/docs/apis/python">Python API</a>: the full constructor surface, including the ACE options</li>

diff --git a/docs/docs/audio/afp.html b/docs/docs/audio/afp.html
diff --git a/docs/docs/index.html b/docs/docs/index.html
@@ -124,7 +124,7 @@ <h3>Acoustic Echo Cancellation (AEC)</h3>
         </a>
         <a href="/docs/audio/afp" class="doc-card">
           <h3>Audio File Processor (AFP)</h3>
-          <p>The offline source: condition a recording or in-memory samples through the same chain, or score a whole recording for speech in one pass. The File class in Python and Node.js.</p>
+          <p>The offline source: condition a recording or in-memory samples through the same chain, score a whole recording for speech, or save the conditioned result. The File class in Python and Node.js.</p>
         </a>
       </div>
 

diff --git a/docs/llms.txt b/docs/llms.txt
@@ -112,10 +112,20 @@ Speaker output:
 - Node events: `'drain'`, `'finish'`, `'error'`, `'close'`, `'pipe'`, `'unpipe'`.
 - Context manager (Python): `with decibri.Speaker(...) as spk:` opens on enter and stops on exit.
 
+Offline audio files (the `File` class, Python and Node.js; not in the browser build):
+- Construct: `decibri.File(path)` / `new File(path)` (sync), `await decibri.AsyncFile.open(path)` / `await File.open(path)` (off the event loop), `decibri.File.buffer(samples, input_rate=...)` / `File.buffer(samples, { inputRate })` for samples already in memory. Node's `File` is a `Readable`; Python's is an iterator and a context manager. Note that Node also has a global `File` (the web File API), so import decibri's explicitly.
+- Formats read: WAV (8-bit unsigned, 16/24/32-bit integer PCM, 32- and 64-bit IEEE float, mu-law, A-law, plus `WAVE_FORMAT_EXTENSIBLE` and RF64), AIFF and AIFF-C (the same widths and companded encodings, plus little-endian `sowt`), and FLAC (bit depths 4 through 32). The container is identified from the file's first twelve bytes, not from its name. MP3, AAC, m4a, Ogg Vorbis, Opus, WMA and ADPCM are not supported and are not planned; decode those yourself and use the buffer constructor.
+- Conditioning: the same five options as `Microphone` (`dc_removal` / `dcRemoval`, `denoise`, `highpass`, `agc`, `limiter`), same names, same ranges, same fixed order, all off by default. Multi-channel files are downmixed to mono and the source is resampled to the target rate. Echo cancellation is not available on a `File`.
+- Three single passes, not a sequence: stream (iterate the chunks), `analyze()` / `analyse()` (whole-recording VAD, returns a `VadReport` of per-window `scores` and merged speech `segments` in seconds of file time, requires `vad='silero'`), and `save()`. Each consumes the source once; starting one forecloses the others on that instance. Construct a second `File` to do two of them.
+- Save: `file.save(path, *, format=None, compression=None)` (Python; `format` and `compression` are keyword-only, and `await AsyncFile.save(...)` is the async parallel) and `await file.save(path, options?)` (Node). Writes WAV, AIFF or FLAC, always 16-bit PCM mono at the target rate. The container comes from the extension (`.wav`, `.aiff`, `.aif`, `.aifc`, `.flac`, case-insensitive; `.aifc` writes a plain AIFF), or from `format` (`'wav'`, `'aiff'`, `'flac'`); an unrecognised extension is an error, never a default. `compression` is the FLAC level, 0 to 8, default 5, ignored for WAV and AIFF. So decibri reads a file by its content and writes one by its name.
+- Save report: `SaveReport` with `clipped_samples` / `clippedSamples` (finite samples clamped back to full scale, which AGC without a limiter can produce) and `non_finite_samples` / `nonFiniteSamples` (NaN written as silence, an infinity as full scale).
+- `AudioWriter` (Node only): a `Writable` file sink for any stream of PCM bytes. `new AudioWriter(path, { sampleRate, channels?, dtype?, format?, compression? })`; `sampleRate` is required, `channels` may only be `1`, and `dtype` (`'int16'` default, or `'float32'`) describes the incoming bytes rather than the file, which is 16-bit PCM either way. `writer.report` carries the `SaveReport` once `'finish'` has fired. Output is byte-identical to `save()`. Python has no equivalent and deliberately does not get one, because Python has no stream-sink convention to match.
+- File errors: `AudioFormatUnsupported` / `AUDIO_FORMAT_UNSUPPORTED` (a container, codec, sample width or channel layout decibri cannot decode, and a save extension it does not write), `AudioFileMalformed` / `AUDIO_FILE_MALFORMED` (structurally wrong, including a RIFF/WAVE with a `fmt` chunk and no `data` chunk), `AudioFileTruncated` / `AUDIO_FILE_TRUNCATED` (ends before the audio it declares, including a declared data length that is not a whole number of frames), `FileReadFailed` / `FILE_READ_FAILED`, `FileWriteFailed` / `FILE_WRITE_FAILED`, `FileEngaged` / `FILE_ENGAGED`, `FileConsumed` / `FILE_CONSUMED`, `VadNotConfigured`, and `FlacCompressionOutOfRange` in Python against a plain `RangeError` in Node.
+
 Module-level helpers:
 - Device enumeration: `decibri.input_devices()` and `decibri.output_devices()` (Python) return `list[MicrophoneInfo]` and `list[SpeakerInfo]`. Node exposes the same data via `Microphone.devices()` and `Speaker.devices()`, plus the module-level `inputDevices()` and `outputDevices()` functions.
 - Version info: `decibri.version()` (Python) and `Microphone.version()`, `Speaker.version()`, or the module-level `version()` (Node) return a `VersionInfo` with three fields: the decibri Rust core version (`decibri`), the audio backend version (`audio_backend` / `audioBackend`, the cpal version), and the binding package version (`binding`).
-- File capture (Python only): `decibri.record_to_file(path, duration_seconds, sample_rate=16000, channels=1, device=None)` and the async variant `decibri.async_record_to_file(...)` record a 16-bit PCM WAV file. In Node.js, pipe the `Microphone` Readable into `fs.createWriteStream()` for raw PCM output, or into any WAV-writing transform.
+- One-shot recording to disk (Python only; distinct from the `File` class above, which reads and conditions existing recordings): `decibri.record_to_file(path, duration_seconds, sample_rate=16000, channels=1, device=None)` and the async variant `decibri.async_record_to_file(...)` record a 16-bit PCM WAV file. In Node.js, pipe the `Microphone` Readable into `fs.createWriteStream()` for raw PCM output, or into any WAV-writing transform.
 
 Async (Python only):
 - `decibri.AsyncMicrophone` and `decibri.AsyncSpeaker` mirror the sync `Microphone` and `Speaker` classes with `async with`, `async for`, and `await`-based read/write methods.
@@ -162,6 +172,8 @@ import { Microphone, MicrophoneInfo, MicrophoneOptions } from 'decibri';
 - [Browser API reference](https://decibri.com/docs/apis/browser): AudioWorklet runtime, permission flow, CSP, differences from Node.js
 - [CLI reference](https://decibri.com/docs/apis/cli): decibri-cli commands, flags, exit codes, JSON schemas
 - [Audio Processing / ACE](https://decibri.com/docs/audio/ace): built-in capture conditioning (DC removal, denoise, high-pass, AGC, limiter)
+- [Audio Processing / AFP](https://decibri.com/docs/audio/afp): the offline `File` class, the formats it reads and writes, whole-recording analysis, and `save()`
+- [Audio Processing / AEC](https://decibri.com/docs/audio/aec): acoustic echo cancellation on the capture path, the reference signal, and its metrics
 - [Integrations index](https://decibri.com/docs/integrations): how decibri feeds STT, TTS, VAD, and KWS engines
 - [STT integrations](https://decibri.com/docs/integrations/stt): AssemblyAI, AWS Transcribe, Azure AI Speech, Deepgram, Google Cloud STT, Mistral Voxtral, OpenAI Realtime, Sherpa-ONNX, Whisper.cpp
 - [Silero VAD guide](https://decibri.com/docs/integrations/vad/silero): bundled neural voice activity detection