[tang-vu]

Ready for independent review (2026-09-15). Candidate 86a7427504c310092e089d25274d267a17a5fe6a has a successful GitHub check rollup and no base-branch conflict at this review snapshot. This supersedes earlier draft-status wording only. All validation gaps, migration requirements, live gates and independent human review requirements below remain in force; this is not a merge-ready approval.

Add ods stt transcribe FILE [MODEL] so an operator can send a local recording to the already-running Whisper/Speaches service and pipe the JSON transcript into a file or another command. The existing CLI can manage STT models but cannot submit an audio file.

Why this matters

This provides a direct local transcription path without requiring an SDK or manually assembling a multipart request. It uses the configured published Whisper port and model, supports an explicit model override, preserves caller-relative filenames, and returns a failed command for HTTP or transport errors. Output contains only the service's JSON response. The input and .env are not modified.

The contract is one multipart POST to /v1/audio/transcriptions with the exact input bytes, literal model, and JSON response format. Shell quoting and curl's multipart filename quoting are handled separately, including commas, semicolons, quotes, backslashes, Unicode and leading hyphens. --form-string keeps a model beginning with @ from becoming a file upload. Requests use a one-hour limit and do not retry.

Overlap check

Searched open and closed PRs for stt transcribe, audio transcription CLI, and transcription, and inspected the ods/ods-cli production-file index. #984/#985/#986 implement model management. #2498/#2502/#3714/#2503/#2499 concern workflow transcription, not a CLI file operation. #4971 fixes quoted dotenv reads in the existing current/status/download commands; this new command reads its own configuration through the existing safe loader and does not depend on #4971. The pair shares the CLI file and needs combined validation before merging the batch. No existing CLI transcription PR was found.

Regression and validation

• python3 ods/tests/test-cli-stt-transcribe.py: 4 tests pass, with real full CLI subprocesses, real curl, and a local HTTP server parsing the multipart bytes. Cases cover relative paths outside the install directory, filename grammar, exact audio bytes, quoted dotenv settings, explicit model precedence, JSON stdout, invalid arguments without upload, and HTTP 422 propagating as failure. Before implementation, the command was rejected and the new boundary assertions failed.
• The test runs from make test. Bash syntax, ShellCheck at the repository's error severity, scoped pre-commit, and git diff --check pass.
• make gate reproduces the existing root/WSL no-sudo fixture failure; the complete gate is not claimed green.
• Checked the endpoint and multipart fields against the exact shipped Speaches v0.9.0-rc.3 router. The HTTP fixture validates transport and CLI behavior; it does not run a speech model or prove transcription quality.

Scope and rollback

This extends the shared Bash CLI used on Linux/WSL. The separately generated native macOS CLI is unchanged, and the README states that scope. No lifecycle, authentication, Compose, or model-selection state is changed. An uncached model may be downloaded by Speaches on first use; the README points to ods stt download for pre-caching. Reverting removes only the new command and its documentation/tests. Ready for independent review; actual model inference and native platform execution remain unverified.

Final candidate 86a7427504c310092e089d25274d267a17a5fe6a: 32 successful CI checks, 4 conditionally skipped; no pending or failed checks.

Batch integration receipt

This is one of 30 independently branched public-beta PRs. The published synthetic integration head is 61f4c6fccc81bea697f4941683fefb5089ba77f4, built from baseline d49ad4bbc760be319de7f4c9b9a93b1f18fe3922 in this reproducible order:

#4946 → #4948 → #4951 → #4954 → #4972 → #4960 → #4961 → #4957 → #4964 → #4967 → #4968 → #4971 → #4975 → #4976 → #4984 → #4982 → #4990 → #4988 → #4989 → #4997 → #5003 → #5006 → #5007 → #5009 → #5012 → #5011 → #5013 → #5014 → #5020 → #5021

Reconciliation preserved all 146 files owned by a single PR byte-for-byte against their exact candidate heads. The eight shared paths preserve both CLI STT/TTS commands and help, every added Makefile test, both environment schema additions and all Extensions UI behavior. LanguageTool and Kroki both remain headless API entries. Canonical regeneration yields 76 catalog entries and 47 library manifests; all README rows are retained. Shared-file changes need these additive resolutions when merged independently.

Combined validation: 2,852 API tests passed / 1 skipped; 1,082 UI tests passed; 47 manifests passed; all 12 added Makefile commands passed; 12 catalog boundary tests passed / 12 opt-in runtime tests skipped in this combined run. Individual exact-image results remain documented above. UI lint/build, scoped secret hooks, diff checks, four platform smoke tests and installer simulation passed. Compose plans for NVIDIA/AMD/Apple each contain 20 services and no duplicate published bindings across the core plus 12 new recipes; this is static plan evidence, not simultaneous startup or GPU inference.

The first unrestricted UI run timed out in two tests under concurrent load; the complete rerun used --maxWorkers=2 with unchanged assertions and timeouts and passed. ESLint reports zero errors and 603 warnings, including the existing JSX usage-detection pattern. Full local make gate still fails the no-sudo Docker baseline covered by #3158. BATS records 416 passed / 5 failed on this root/WSL host (platform detection, root preflight and a 15 GiB versus 20 GiB free-space expectation). Neither full local gate nor BATS is described as green.

This integration receipt supplements each PR's own regression and does not waive its independent review, live hardware/browser/upgrade gates or rollback requirements. The PRs remain drafts; none was merged upstream.

[Lightheartdevs]

Thanks for this contribution. public-beta was promoted into main on 2026-09-24 and no longer receives changes, so we're closing pull requests that target it. This isn't a judgment on the change itself. If it's still needed, please rebase onto main and open a focused PR. See #7253 for details and the contribution policy.