readme

1 files changed, 24 insertions, 176 deletions

diff --git a/README.md b/README.md
index c1faf42..075d6ae 100644
--- a/README.md
+++ b/README.md
@@ -82,137 +82,9 @@ Edit default settings in `config.toml`
 ./producer.sh gui --port 8766
 ```
 
-The studio is a compact workbench: pick a WAV, select a passage, tune
-settings, compare, and export. Use a current desktop browser (Chromium
-tested); JavaScript is required. No Node/npm build, CDN, telemetry, or cloud
-audio service is used. The launcher installs the optional FastAPI/uvicorn
-extra only when `gui` is requested. Existing CLI commands do not need it.
-Direct package installs can use `producer[gui]` and need system FFmpeg or the
-`bundled-ffmpeg` extra for processing.
-
-1. Click **Browse…** and choose a mono WAV from anywhere on this machine (the
-   file picker can also batch-select several). The browser uploads a temporary
-   copy for processing; your original file is never touched. The overview is a
-   streaming scan reduced to 2,048 peak bins, not the whole recording loaded
-   into the browser. You can enter times before scanning finishes.
-2. Click or drag the waveform, or enter exact `HH:MM:SS.sss` start/end times
-   (seconds also work). Zoom enlarges the same coarse overview; exact times
-   are best for fine selection on multi-hour recordings.
-3. Every control's help text briefly explains what it does. Turning an effect
-   off greys out and disables its dependent values while keeping them. FFT
-   reduction only applies to the lightweight FFT denoiser: it is scaled by
-   cleanup strength and disappears entirely when you pick DeepFilter,
-   ClearVoice or "none". "Pause silencing (VAD)" uses a local speech detector
-   to zero non-speech pauses without moving anything; "Gap shortening (export
-   only)" trims long gaps on the full export and is never auditioned in the
-   comparison. Click **Render sound comparison**.
-4. Play/loop the passage and switch A/B without losing your place. Optional
-   matching attenuates the louder snippet for fair listening. File loudness
-   and peak readings are separate from monitoring gain, not quality scores
-   or full-export measurements. Changes pause playback and mark older renders;
-   late jobs never replace the visible comparison after you edit the selection.
-5. Enter an existing **absolute** output directory (default: the directory
-   you launched Producer from — start it next to your recording and exports
-   land beside the input). The audio file
-   (`<name>.<profile>.wav`, optional `.mp3`) is written directly into that
-   directory; the timestamped diagnostic report goes to the `logs/`
-   directory next to `producer.sh`. Settings that differ from the built-in
-   profile are named `custom`, and the browser asks before replacing
-   existing audio. This processes the entire original even if you
-   selected only a few seconds. Completed exports
-   list their full local paths; find the files with your operating system's
-   file manager.
-
-The server binds only to loopback (127.0.0.1) and has no login: **anything
-that can reach this port on this machine can use it**, so run it only on a
-machine you control and do not expose it through a proxy, port-forwarding, or
-`0.0.0.0`. Stop the server with Ctrl-C.
-
-**Containers/remote shells:** loopback belongs to the machine/network
-namespace running Producer. A browser on the host cannot normally reach a
-container's `127.0.0.1`; publishing a container port does not help because the
-server still only answers `127.0.0.1`. The simplest supported setup is to run
-`./producer.sh gui` directly on the machine with your browser and recordings.
-
-Settings use the same strict resolver and configuration precedence as the
-CLI. The initial controls include your launch TOML and CLI overrides.
-**Restore launch settings** resets edits. **Apply profile** resets through
-that precedence too: explicit launch values still win. Changing only the
-profile name keeps your other explicit knob values. TOML import instead loads
-standalone settings (package defaults/profile plus the imported TOML).
-
-Save up to 20 named settings presets and 12 immutable comparison snapshots in
-this browser. Snapshots retain the recording identity, excerpt times and
-requested settings, never audio. **Restore & render** explicitly recreates a
-comparison; a changed source file must be re-uploaded and re-selected.
-Download/import small TOML presets to move settings between browsers.
-Browser storage can be cleared or disabled; use TOML for backup.
-
-Uploads, waveform scans and jobs run in the background, one at a time, with
-up to three waiting. Activity shows per-stage progress, frozen snapshots and
-cancellation. Cancellation is cooperative: a model download may take up to 60
-seconds to reach a safe callback, and files already published can remain.
-There is no total recording-duration cap; typical 1–4 hour and longer
-recordings still need sufficient processing time and temporary disk space.
-Inputs must be readable mono WAVs; stereo needs an explicit downmix outside
-Producer first. Uploaded copies live in a private temporary directory and are
-deleted when the server stops.
-
-First AI noise cleanup or pause silencing use downloads dependencies/models;
-processing stays local afterwards. For a quick no-model trial, launch with
-`./producer.sh gui --no-denoise --no-pause-silence`. These explicit flags
-establish initial controls, not hidden permanent bypasses. Reload reconnects
-to recent jobs, but does not automatically restore/play old audio. If Producer
-restarts, open its printed URL again. If a connection drops during an export
-request, check Activity before submitting another export; the first may have
-succeeded.
-
-Sound-comparison previews select up to 120 seconds anywhere in a recording,
-process with up to 10 seconds of context on each side, then crop to the
-selected interval. They are **approximate, not exact export previews**:
-chapter-level normalization and inference context differ. Gap-trimming edits
-are not previewed; comparisons preserve timing even when export gap trimming
-is selected. Normalization and other effects are never forced on for
-comparison. Optional loudness matching is playback-only attenuation, not a
-change to export settings.
-
-Exports process the whole original with the requested settings and write the
-audio file directly into the chosen output directory:
-`<name>.<profile>.wav` (named `custom` when settings differ from the built-in
-profile), optional `<name>.<profile>.mp3`. Replacing existing audio asks for
-explicit confirmation. The timestamped diagnostic report goes to the `logs/`
-directory next to `producer.sh`, so reports never collide. The API
-returns persistent local paths, **not browser blobs of multi-hour exports**.
-The browser only fetches bounded preview snippets. TOML presets can be
-imported as text or downloaded; no source recording is rewritten by the API.
-The server retains at most eight repeated-result cache entries and 128 MiB of
-artifacts; expired previews must be rendered again. Job history is limited to
-24 entries and is lost when the server stops, while completed output files
-persist. Browser preview WAVs are bounded to about 11.6 MB per side (120
-seconds of mono PCM16 at 48 kHz). Full exports never become browser Blobs.
-These are generic WAV/MP3 delivery files, not delivery-platform compliance
-certification.
-### GUI development checks (optional)
-
-The application itself needs no browser automation or Node dependencies. With
-an external test environment containing `producer[gui,test]`, use:
-
-```bash
-python -m pytest lib/project/tests -q
-node --check lib/project/src/producer/web/app.js
-node --test lib/project/tests/gui_state.test.mjs
-# Optional real headless browser checks, no AI models:
-python -m pip install playwright
-python -m playwright install chromium
-PRODUCER_BROWSER_TESTS=1 python -m pytest lib/project/tests/test_gui_browser*.py -q
-```
-
-Playwright may need OS-specific browser shared libraries in the test container;
-these are not application runtime dependencies. Browser checks generate a
-short test WAV, exercise real scan/preview/export and cancellation, and mock a
-bounded four-hour overview. They do not claim a four-hour AI processing run.
-Screenshots default to `/tmp/producer-browser-smoke`; set
-`PRODUCER_BROWSER_ARTIFACTS` to keep them elsewhere.
+Opens a local web page where you pick a WAV, tune settings, render an A/B
+comparison, and export. The server binds only to loopback (127.0.0.1); stop
+it with Ctrl-C.
 
 ## Profiles
 
@@ -225,57 +97,33 @@ Screenshots default to `/tmp/producer-browser-smoke`; set
 
 ## Speech starts and silent pauses
 
-Denoising and pause silencing are different jobs. Pushing a denoiser harder
-can damage quiet consonants without eliminating all room tone. Compression
-and normalization then raise the remaining noise. The shipped `config.toml`
-uses ClearVoice at 0.85 strength, speech-aware pause silencing, and **no gap
-trimming**. Bare package defaults leave pause silencing off (opt in with
-`--pause-silence`).
-
-Pause silencing detects speech on the **pre-denoise** audio using pinned
-Silero VAD v5.1 ONNX weights. First use downloads a separate CPU runtime and
-~2.3 MB model; it needs no GPU or cloud service. After EQ/dynamics, gaps
-outside protected speech fade to zero before loudness normalization. This
-keeps the timeline unchanged unless you separately enable `--trim-silence`.
-32-bit export uses no dither so silent cores can remain digital zero;
-resampling/filter tails may extend slightly into their edges. MP3 need not
-retain sample-exact silence near speech boundaries.
-
-Defaults protect 120 ms before and after detections, use 10 ms fades, and
-require an additional 80 ms silent core. Shorter gaps are left alone rather
-than risking chopped words. Controls:
-
-- `--pause-threshold 0.25`: lower = preserve more possible speech.
-- `--pause-pre-ms 180`: protect more of quiet sentence starts.
-- `--pause-post-ms 200`: keep longer word tails and decay.
-- `--pause-min-ms 40`: allow shorter silent cores after margins and fades.
-- `--no-pause-silence`: bypass this stage; no detector download. Combine with
-  `--no-denoise` to avoid all AI model/runtime downloads.
-
-The detector can miss whispers, breaths, or unusual speech. If it detects
+Pause silencing detects speech on the **pre-denoise** audio with pinned Silero
+VAD v5.1 ONNX weights (a ~2.3 MB CPU-only download on first use). After
+EQ/dynamics, gaps outside protected speech fade to zero before loudness
+normalization, leaving the timeline unchanged unless you enable
+`--trim-silence`. Defaults protect 120 ms before and after detections, use
+10 ms fades, and require an 80 ms silent core; shorter gaps are left alone.
+Enable it in `config.toml` (`pause_silence = true`) or with `--pause-silence`.
+
+- `--pause-threshold 0.35`: lower = preserve more possible speech.
+- `--pause-pre-ms` / `--pause-post-ms`: padding around detected speech.
+- `--pause-min-ms` / `--pause-fade-ms`: silent core and fade lengths.
+- `--no-pause-silence`: bypass this stage; combine with `--no-denoise` to
+  avoid all AI model/runtime downloads.
+
+The detector can miss whispers, breaths, or unusual speech; if it detects
 **no speech**, cleanup fails open with a warning instead of muting the file.
-Other detector failures stop processing, not silently switch to a level gate.
-Reports in the `logs/` directory next to `producer.sh` include the attenuated
-intervals on the original,
-pre-trim timeline for inspection. With VAD enabled, optional trimming only
-shortens near-zero cores; without it, legacy `gap_threshold_db` trimming can
-mistake quiet speech for silence.
-
-This stage does **not** restore consonants a denoiser has already removed.
-Compare denoisers and try `--denoise-strength 0.65` if attacks remain soft;
-a dry/wet blend trades some noise reduction for speech preservation.
-A low, consistent room tone can sound more natural than dead silence.
-Professional quality requires listening for artifacts, breaths, sibilance,
-clipping and reverb, not just checking a meter. LUFS targets here are not
-ACX RMS/noise-floor certification; no one-click chain guarantees every
-recording meets a delivery specification.
-
-Test the difference on your own audio before committing:
+Denoising and pause silencing are different jobs: this stage does not restore
+consonants a denoiser has already removed. Audition the result before
+committing:
 
 ```bash
 ./producer.sh preview recording.wav --start 10 --duration 30
 ```
 
+Reports in the `logs/` directory next to `producer.sh` include the attenuated
+intervals for inspection.
+
 ## Troubleshooting
 
 - **Bootstrap fails:** the first run needs `uv` or Python 3 with venv support