diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 160 |
1 files changed, 83 insertions, 77 deletions
@@ -74,109 +74,115 @@ Edit default settings in `config.toml` ## Optional local browser GUI ```bash -./producer.sh gui --root /path/to/recordings +./producer.sh gui # Optional alternate loopback port: -./producer.sh gui --root /path/to/recordings --port 8766 +./producer.sh gui --port 8766 ``` -The browser studio guides you through **Choose recording → Try a short passage -→ Compare sound → Export full recording**. 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. Browse folders beneath your chosen root and select a mono WAV. The overview - is a streaming scan reduced to 2,048 peak bins, not a full recording loaded +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. Start with noise cleanup, quiet pauses, tone and even volume. Expand **All - settings & advanced controls** for every other setting and its units/help. - Disabled effects retain their knob values. Nothing renders per keystroke, - and no dependent effect is silently enabled. Click **Render sound comparison**. +3. Every control's help text explains what it does and how to switch the + effect off. Turning an effect off greys out and disables its dependent + values — for example unchecking "Remove low rumble" deactivates its cutoff + field — while keeping those values for later. FFT reduction only applies + to the lightweight FFT denoiser: it is scaled by cleanup strength, cannot + be set to 0, and disappears entirely when you pick DeepFilter, ClearVoice + or "none". "Silence pauses" uses a local speech detector to zero non-speech + pauses without moving anything; "Shorten long gaps (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. Choose an existing output folder, review the frozen current settings and - confirm **Export full recording**. This processes the entire original even - if you selected only a few seconds. Completed local paths appear in the - export panel; find the files with your operating system's file manager. - -Open the printed `http://127.0.0.1:.../#token=...` URL on the same machine and -keep it private. The server binds only to loopback, rejects untrusted -Host/Origin headers, and requires the session credential for every API read -or mutation. Do not expose it through a proxy or port-forwarding service. -`--root` bounds browsing and output directories, including resolved symlinks; -its default is the current working directory. There are no recording uploads -or arbitrary host-file download endpoints. 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 change this loopback-only -binding. The simplest supported setup is to run `./producer.sh gui` directly -on the machine with your browser and recordings. This development container -has no GUI. Do not change the bind to `0.0.0.0`, disable the Host/Origin checks, -or expose the token through a proxy to work around access. No insecure -container-host access mode is provided. - -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 & launch defaults** 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 per -root in this browser. Snapshots retain the source identity, excerpt times and +5. Enter an existing **absolute** output folder (default: + `producer-gui-exports` next to where you launched), review the frozen + current settings and confirm **Export full recording**. 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-selected. Download/import small -TOML presets to move settings between browsers. Local browser storage can be -cleared or disabled and is specific to the loopback address/port; use TOML for -backup. Session credentials are never saved in presets or comparison snapshots. - -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. +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 --root /path/to/recordings --no-denoise --no-pause-silence`. -These explicit flags establish initial controls, not hidden permanent bypasses. -Reload retains the credential in the same tab and reconnects to recent jobs, -but does not automatically restore/play old audio. If Producer restarts, open -its newly printed private URL. If a connection drops during an export request, -check Activity before submitting another export; the first may have succeeded. +`./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. Pacing 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. +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 into a new, non-clobbering `producer-export-*` folder in the chosen output directory: `master.wav`, optional `master.mp3`, and `logs/master.report.json`. 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 preset or source recording is rewritten by the API. +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. - +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 |