textflowkit 0.1.8__tar.gz → 0.1.9__tar.gz

{textflowkit-0.1.8 → textflowkit-0.1.9}/.github/workflows/ci.yml

@@ -58,7 +58,11 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install ./packages/textflowkit-fonts
-          python -m pip install -e ".[dev,mcp,http,export]"
+          # `whisper` is installed here because the existing engine tests
+          # (openai-whisper's verbose/quiet contract, model-name validation)
+          # genuinely need the openai-whisper package present. It is an optional
+          # extra now that Whistle is the default engine, so it must be named.
+          python -m pip install -e ".[dev,mcp,http,export,whisper]"
 
       - name: Show ffmpeg version
         shell: bash

{textflowkit-0.1.8 → textflowkit-0.1.9}/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## v0.1.9 — 2026-10-05
+
+**Whistle is now the default engine.** This release ships the Whistle integration
+prepared on the `feat/whistle-primary` branch.
+
+### Changed
+
+- **Whistle is the default engine; openai-whisper becomes an explicit opt-in.**
+  Whistle is a CPU-only native CLI that needs no PyTorch, so a fresh
+  `pip install textflowkit` no longer pulls the torch stack. `openai-whisper`
+  moves to a new optional `whisper` extra and is selected with `--engine whisper`
+  (or `engine="whisper"` on the Python/MCP/HTTP surfaces); the `all` extra still
+  includes it. A saved request or checkpoint from before this change keeps running
+  on the engine it names, so legacy Whisper work is never silently migrated, and
+  legacy engine aliases are preserved so older decoders keep working.
+- **Engine selection is never silent.** An unknown engine name, an unsupported
+  language, or a non-CPU device for Whistle is refused at request construction —
+  before any media is fetched — and the message names `--engine whisper` as the
+  GPU alternative. The engine is not switched to satisfy a request.
+
+### Added
+
+- **Whistle engine.** Seven advertised languages (`en`, `de`, `fr`, `es`, `it`,
+  `nl`, `pl`); native Windows x86-64/arm64, Linux x86-64/arm64, and Apple Silicon
+  (an Intel Mac is refused and pointed at the explicit Whisper engine); no WSL.
+  One pinned native binary and one pinned model are downloaded and hash-verified
+  on first use, outside the package. Long audio is split into 26-second cores with
+  up to 2 seconds of context (each clip ≤ 30 s); a word is owned by the clip whose
+  core contains its midpoint, so repeated phrases are preserved. Native
+  `--audio-stream` is never used.
+- **Durable per-block resume for Whistle.** A long run persists a partial
+  checkpoint after each core; a resume validates the source and decoded-WAV
+  hashes and the configuration, then re-runs only the unfinished blocks and adopts
+  the rest. A partial body is Whistle-only. Reuses the existing single SQLite
+  store and its one-owning-process model.
+- **Prompt, bounded cancellation.** A running Whistle run polls for cancellation
+  between clips and terminates its exact owned child process, bounded by a
+  per-clip timeout and a bounded stdout cap. A single long `openai-whisper` model
+  call is still cancellable only at its next stage boundary.
+- **Telemetry off, unconditionally.** Every Whistle child process forces
+  `NEEDLE_TELEMETRY=0`, `DO_NOT_TRACK=1`, and `CI=1`, overriding a parent that
+  opted in, and there is no opt-in setting. The product adds no analytics, usage
+  SDK, anonymous ids, or events. `TEXTFLOWKIT_OFFLINE` refuses downloads and
+  `TEXTFLOWKIT_MODELS_DIR` chooses the asset directory; the pinned first-use
+  asset/model download is not telemetry.
+
+### Documentation
+
+- README, user manual, install/adapter/architecture/roadmap/release docs and the
+  website source now describe Whistle as the shipped default. ROCm (and the
+  torch-pinning caveat) is scoped to the explicit `whisper` engine and
+  diarization, never to Whistle.
+- Self-contained checked-in SVG architecture drawings were added under
+  `docs/assets` and embedded in the README, both manuals (`user-manual.md` and the
+  renamed **Developer and integration manual**, `adapters.md`), the architecture
+  guide, and the landing page.
+- The live YouTube release smoke pins `--engine whisper --model tiny` so its
+  measured default-clip word stays reproducible across the default-engine change.
+
+### Verification boundary
+
+Local evidence only: a 4-hour (14,407-second) CPU run produced 555
+clips / 34,596 words / 2,875 segments in 731 seconds, offline with telemetry
+forced off, and a separate two-process run proved durable block resume. These are
+first local test numbers on one machine — not a universal performance claim, and
+not a claim that Whistle's accuracy equals Whisper's. No human-scored
+word-error rate is claimed.
+
 ## v0.1.8 — 2026-10-02
 
 The 2026-10-02 audit-lite repair release. Core version: 0.1.8; unchanged optional fonts: 0.1.6. It carries the four fixes for the post-release audit-lite of 2026-10-01 (findings AL-001 – AL-004). Release artifacts and publication status are recorded on [GitHub Releases](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.8). Local source-candidate verification does not establish installed-package or individual harness compatibility.

{textflowkit-0.1.8 → textflowkit-0.1.9}/Dockerfile

@@ -77,11 +77,13 @@ RUN set -eux; \
 WORKDIR /app
 COPY pyproject.toml README.md LICENSE ./
 COPY src ./src
-# The base dependencies are yt-dlp and openai-whisper, so this image is large:
-# openai-whisper pulls a torch build. That is the product's own requirement, not
-# something this file adds.
+# The base dependencies are yt-dlp alone: the default engine (Whistle) is a
+# native CPU binary fetched on first use, so this image does not pull a torch
+# build. Selecting the openai-whisper engine needs the `whisper` extra named
+# here; the image installs it because the container is meant to serve the
+# Whisper stack too, and openai-whisper is what pulls the torch build.
 RUN python -m pip install --no-cache-dir --upgrade pip \
- && python -m pip install --no-cache-dir ".[http]"
+ && python -m pip install --no-cache-dir ".[http,whisper]"
 
 # Non-secret defaults only. The roots are the directories created above; Compose
 # repeats them so the volumes it mounts land on the paths the service reads.

{textflowkit-0.1.8 → textflowkit-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.8
+Version: 0.1.9
 Summary: Cross-platform media transcription toolkit: URL or file in, timestamped transcripts and subtitle files out.
 Project-URL: Homepage, https://www.textflowkit.org/
 Project-URL: Issues, https://github.com/scottconverse/textflowkit/issues
@@ -21,11 +21,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Classifier: Topic :: Text Processing
 Requires-Python: >=3.10
-Requires-Dist: openai-whisper>=20240930
 Requires-Dist: yt-dlp>=2025.1.1
 Provides-Extra: all
 Requires-Dist: fastapi>=0.115; extra == 'all'
 Requires-Dist: mcp>=2.0; extra == 'all'
+Requires-Dist: openai-whisper>=20240930; extra == 'all'
 Requires-Dist: pyannote-audio>=4.0; extra == 'all'
 Requires-Dist: pydantic>=2.7; extra == 'all'
 Requires-Dist: python-docx>=1.1; extra == 'all'
@@ -53,6 +53,8 @@ Requires-Dist: pydantic>=2.7; extra == 'http'
 Requires-Dist: uvicorn>=0.30; extra == 'http'
 Provides-Extra: mcp
 Requires-Dist: mcp>=2.0; extra == 'mcp'
+Provides-Extra: whisper
+Requires-Dist: openai-whisper>=20240930; extra == 'whisper'
 Description-Content-Type: text/markdown
 
 # textflowkit
@@ -62,9 +64,10 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [Project landing page](https://www.textflowkit.org/) ·
 [PyPI package](https://pypi.org/project/textflowkit/) ·
 [GitHub releases](https://github.com/scottconverse/textflowkit/releases) ·
-[User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
+[User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md) ·
+[Developer and integration manual](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md)
 
-**Current release: [v0.1.8](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.8).**
+**Current release: [v0.1.9](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.9).**
 
 The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
 Pages. GitHub remains the source and CI host; the website does not run the
@@ -111,7 +114,7 @@ URL or file  ─►  detect platform  ─►  acquire media  ─►  ffmpeg
                                                           │
                               ┌───────────────────────────┘
                               ▼
-                    speech-to-text (Whisper)
+              speech-to-text (Whistle default; Whisper on request)
                               │
                               ▼
                  canonical transcript (JSON)
@@ -125,6 +128,8 @@ DOCX and PDF are available through the optional `export` extra.
 
 ## Architecture
 
+![TextFlowKit shared-core architecture: four thin entry points (CLI, Python, MCP, HTTP) feed one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/architecture-overview.svg)
+
 The design principle is **one engine, three doors**. Everything of substance lives in
 the core; the interfaces are thin.
 
@@ -164,6 +169,22 @@ python -m pip install textflowkit
 textflowkit doctor
 ```
 
+The default engine is **Whistle**: a native CPU-only transcription CLI that
+needs no PyTorch. It downloads one pinned model (about 17 MB) and a small pinned
+binary on first use; a fresh default install therefore stays small and pulls no
+torch. To use the `openai-whisper` engine instead — the ROCm/CUDA/CPU torch
+stack — install the `whisper` extra and name it explicitly:
+
+```bash
+python -m pip install 'textflowkit[whisper]'
+textflowkit transcribe meeting.mp4 --engine whisper --model small
+```
+
+See [Whistle (default engine)](#whistle-default-engine) for platform and
+language coverage, and the [install guide](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md)
+for the AMD ROCm path, which applies to the explicit `whisper` engine and
+diarization.
+
 For MCP or the JSON HTTP adapter, install the matching extra:
 
 ```bash
@@ -187,7 +208,6 @@ from textflowkit import transcribe
 
 result = transcribe(
     "meeting.mp4",            # also accepts supported URLs
-    model="small",
     formats=["json", "srt", "txt"],
     output_dir="transcripts", # omit to return the transcript without writing files
 )
@@ -200,6 +220,10 @@ for segment in result.transcript.segments:
         print("  ", word.start, word.end, word.text)
 ```
 
+`engine` defaults to the product default (Whistle) and `model=None` resolves to
+that engine's own model. To use the Whisper-family engines, name one and its
+model explicitly: `transcribe("meeting.mp4", engine="whisper", model="small")`.
+
 `transcribe()` returns `TranscribeResult` with a canonical `Transcript` and
 written output paths. `Transcript.to_dict()` / `.to_json()` preserve segment and
 word timing; older transcript JSON without `words` remains readable. Pass
@@ -264,6 +288,60 @@ does **not** assert that the remote bytes are still identical.
 textflowkit export ./transcript.json --format vtt
 ```
 
+## Whistle (default engine)
+
+**Whistle is the default engine** as of v0.1.9. It is a native CPU-only CLI that
+needs no PyTorch, so a fresh `pip install textflowkit` stays small and pulls no
+torch; `openai-whisper` is an explicitly selectable opt-in engine.
+
+![Whistle bounded block run and durable resume: a decoded PCM WAV is split into 26-second cores with up to 2 seconds of context (each clip ≤ 30 s), each core runs as one owned child with forced telemetry-off flags, a partial checkpoint is written after each core, and a resume validates the source and decoded-WAV hashes then re-runs only the unfinished cores.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/whistle-resume.svg)
+
+- **CPU only, no torch.** It runs a pinned native binary and downloads one pinned
+  model on first use. Naming a GPU device is refused rather than silently
+  ignored: a GPU request names the explicit `whisper` engine as the alternative,
+  and the engine is never switched for you.
+- **Seven advertised languages:** `en`, `de`, `fr`, `es`, `it`, `nl`, `pl`. A
+  request for another language is refused at request construction, before any
+  media is fetched.
+- **Native platforms:** Windows x86-64 and arm64, Linux x86-64 and arm64, and
+  Apple Silicon. **Intel Macs are not supported**; a request there is refused
+  with a message that names the explicit `whisper` engine instead. No WSL layer
+  is involved.
+- **How it works:** long audio is split into 26-second cores with up to 2 seconds
+  of context on each side, so every standalone clip is ≤ 30 seconds (the native
+  CLI's limit). Overlap words are selected by core midpoint rather than text
+  deduplication, so repeated spoken phrases are preserved.
+- **Streaming is not used.** The native `--audio-stream` mode failed its
+  coverage and is never passed; only the committed standalone output is parsed.
+- **Durable block resume.** With `TEXTFLOWKIT_DB` set, a long run writes partial
+  per-block checkpoints; a resume checks the source and decoded-WAV hashes and the
+  config, then re-runs only the blocks that were not finished. The durable store
+  still assumes one owning process.
+- **Cancellation.** A running Whistle run terminates its exact owned child
+  process bounded by a per-clip timeout. A single long `openai-whisper` model call
+  is still only cancellable at its next stage boundary, as documented for the
+  Whisper engine.
+- **Telemetry is off, unconditionally.** Every Whistle child process forces
+  `NEEDLE_TELEMETRY=0`, `DO_NOT_TRACK=1`, and `CI=1`, overriding a parent that
+  opted in. The product ships no analytics, usage SDK, anonymous ids, or events,
+  and there is no opt-in setting. This applies the upstream documented gate; it
+  is **not** a claim that the upstream binary's tracking code is physically
+  removed.
+- **Offline and downloads.** Set `TEXTFLOWKIT_OFFLINE` to refuse any download, and
+  `TEXTFLOWKIT_MODELS_DIR` to choose the asset directory. The Whistle asset helper
+  downloads only pinned runtime/model assets; media acquisition and optional
+  translation may independently use the network. These downloads are not
+  telemetry.
+
+**Verification boundary.** A local run transcribed a 4-hour (14,407 s)
+recording on CPU into 555 clips / 34,596 words / 2,875 segments in 731 s, with
+telemetry forced off and offline mode on; a separate run proved durable block
+resume across two processes. These are **first local test numbers**, not a
+promise of universal performance or of accuracy equal to Whisper — no
+human-scored word-error rate is claimed. See the
+[user manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
+and [install guide](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md).
+
 ## Use as an MCP server
 
 ```bash
@@ -323,7 +401,7 @@ scope here, so no image is claimed to build or start. See
 
 ```bash
 TEXTFLOWKIT_DB=./jobs.db            # job state survives restart (SQLite)
-TEXTFLOWKIT_MAX_CONCURRENCY=1        # default; Whisper saturates a GPU alone
+TEXTFLOWKIT_MAX_CONCURRENCY=1        # default; bounded job worker pool
 ```
 
 `cancel_job` stops a queued job immediately, or a running job at its next stage
@@ -338,14 +416,31 @@ web frontend share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.8 release.** Core, CLI, MCP, and HTTP have automated
-coverage. This release carries the four fixes for the 2026-10-01 post-release
-audit-lite (findings AL-001 – AL-004): CLI owning-process startup recovery so an
-interrupted run's saved work can be resumed instead of being refused as
-"already active", preservation of the completed transcript across resume setup
-failures, a correction to the MCP batch cookie capability, and corrected roadmap
-evidence receipts. It builds on the v0.1.7 audit repair set and the v0.1.6
-review repairs that precede it. The preceding v0.1.7 source candidate was verified with real CLI, HTTP and MCP speech, seven-format exports and completed resume. The v0.1.8 runtime fixes were independently checked through fresh-process CLI restart probes, real SQLite setup-failure tests, and the full Windows test suite; those checks are not new individual-harness receipts. Release publication uses the tag workflow, which requires successful exact-commit main CI before PyPI uploads and creates the public GitHub release only afterward. Check the linked release for artifacts and workflow status; local source verification is not a fresh PyPI-install or individual-harness receipt.
+**v0.1.9 release.** Core, CLI, MCP, and HTTP have automated
+coverage. This release makes **Whistle the default engine** — a native CPU-only
+transcriber that needs no PyTorch — and moves `openai-whisper` to the optional
+`whisper` extra, selected explicitly with `--engine whisper` or
+`engine="whisper"`. Legacy engine aliases are preserved, so older saved jobs and
+`transcribe()` calls still decode. Whistle refuses an unsupported platform,
+language, or GPU request instead of silently falling back. Its engine's
+verification boundary is in [Whistle (default engine)](#whistle-default-engine)
+above. Release publication uses the tag workflow, which requires successful
+exact-commit main CI before PyPI uploads and creates the public GitHub release
+only afterward. Check the linked release for artifacts and workflow status; local
+source verification is not a fresh PyPI-install or individual-harness receipt.
+
+The v0.1.8 release carried four fixes for the 2026-10-01 post-release audit-lite
+(findings AL-001 – AL-004): CLI owning-process startup recovery so an interrupted
+run's saved work can be resumed instead of being refused as "already active",
+preservation of the completed transcript across resume setup failures, a
+correction to the MCP batch cookie capability, and corrected roadmap evidence
+receipts. It built on the v0.1.7 audit repair set and the v0.1.6 review repairs
+that precede it. The v0.1.7 source candidate was verified with real CLI, HTTP and
+MCP speech, seven-format exports and completed resume; the v0.1.8 runtime fixes
+were independently checked through fresh-process CLI restart probes, real SQLite
+setup-failure tests, and the full Windows test suite. Those checks are not new
+individual-harness receipts. That is the previous release's record, not evidence
+for v0.1.9.
 
 The v0.1.6 release was the post-v0.1.5 review repair set: security hardening
 for media acquisition and the HTTP and MCP adapters, safer subtitle wrapping and
@@ -362,9 +457,9 @@ The v0.1.6 release is public: the
 [v0.1.6 GitHub release](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.6)
 and both [core](https://pypi.org/project/textflowkit/0.1.6/) and
 [fonts](https://pypi.org/project/textflowkit-fonts/0.1.6/) PyPI projects are
-live — that is the previous release's evidence, not a receipt for v0.1.8.
+live — that is the v0.1.6 release's evidence, not a receipt for a later release.
 Everything from here to the end of this section is the v0.1.6 release's
-historical record as published: it is not re-verified for v0.1.8, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.9, whose separate release evidence is not supplied by these historical paragraphs.
 Merged-main CI passed 16/16 on the tagged commit; the published wheel and
 sdist digests match the GitHub release assets and their SHA-256 list; and a fresh
 Windows Python 3.12 install of `textflowkit[export,mcp,http]==0.1.6` from PyPI

{textflowkit-0.1.8 → textflowkit-0.1.9}/README.md

@@ -5,9 +5,10 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [Project landing page](https://www.textflowkit.org/) ·
 [PyPI package](https://pypi.org/project/textflowkit/) ·
 [GitHub releases](https://github.com/scottconverse/textflowkit/releases) ·
-[User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
+[User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md) ·
+[Developer and integration manual](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md)
 
-**Current release: [v0.1.8](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.8).**
+**Current release: [v0.1.9](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.9).**
 
 The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
 Pages. GitHub remains the source and CI host; the website does not run the
@@ -54,7 +55,7 @@ URL or file  ─►  detect platform  ─►  acquire media  ─►  ffmpeg
                                                           │
                               ┌───────────────────────────┘
                               ▼
-                    speech-to-text (Whisper)
+              speech-to-text (Whistle default; Whisper on request)
                               │
                               ▼
                  canonical transcript (JSON)
@@ -68,6 +69,8 @@ DOCX and PDF are available through the optional `export` extra.
 
 ## Architecture
 
+![TextFlowKit shared-core architecture: four thin entry points (CLI, Python, MCP, HTTP) feed one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/architecture-overview.svg)
+
 The design principle is **one engine, three doors**. Everything of substance lives in
 the core; the interfaces are thin.
 
@@ -107,6 +110,22 @@ python -m pip install textflowkit
 textflowkit doctor
 ```
 
+The default engine is **Whistle**: a native CPU-only transcription CLI that
+needs no PyTorch. It downloads one pinned model (about 17 MB) and a small pinned
+binary on first use; a fresh default install therefore stays small and pulls no
+torch. To use the `openai-whisper` engine instead — the ROCm/CUDA/CPU torch
+stack — install the `whisper` extra and name it explicitly:
+
+```bash
+python -m pip install 'textflowkit[whisper]'
+textflowkit transcribe meeting.mp4 --engine whisper --model small
+```
+
+See [Whistle (default engine)](#whistle-default-engine) for platform and
+language coverage, and the [install guide](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md)
+for the AMD ROCm path, which applies to the explicit `whisper` engine and
+diarization.
+
 For MCP or the JSON HTTP adapter, install the matching extra:
 
 ```bash
@@ -130,7 +149,6 @@ from textflowkit import transcribe
 
 result = transcribe(
     "meeting.mp4",            # also accepts supported URLs
-    model="small",
     formats=["json", "srt", "txt"],
     output_dir="transcripts", # omit to return the transcript without writing files
 )
@@ -143,6 +161,10 @@ for segment in result.transcript.segments:
         print("  ", word.start, word.end, word.text)
 ```
 
+`engine` defaults to the product default (Whistle) and `model=None` resolves to
+that engine's own model. To use the Whisper-family engines, name one and its
+model explicitly: `transcribe("meeting.mp4", engine="whisper", model="small")`.
+
 `transcribe()` returns `TranscribeResult` with a canonical `Transcript` and
 written output paths. `Transcript.to_dict()` / `.to_json()` preserve segment and
 word timing; older transcript JSON without `words` remains readable. Pass
@@ -207,6 +229,60 @@ does **not** assert that the remote bytes are still identical.
 textflowkit export ./transcript.json --format vtt
 ```
 
+## Whistle (default engine)
+
+**Whistle is the default engine** as of v0.1.9. It is a native CPU-only CLI that
+needs no PyTorch, so a fresh `pip install textflowkit` stays small and pulls no
+torch; `openai-whisper` is an explicitly selectable opt-in engine.
+
+![Whistle bounded block run and durable resume: a decoded PCM WAV is split into 26-second cores with up to 2 seconds of context (each clip ≤ 30 s), each core runs as one owned child with forced telemetry-off flags, a partial checkpoint is written after each core, and a resume validates the source and decoded-WAV hashes then re-runs only the unfinished cores.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/whistle-resume.svg)
+
+- **CPU only, no torch.** It runs a pinned native binary and downloads one pinned
+  model on first use. Naming a GPU device is refused rather than silently
+  ignored: a GPU request names the explicit `whisper` engine as the alternative,
+  and the engine is never switched for you.
+- **Seven advertised languages:** `en`, `de`, `fr`, `es`, `it`, `nl`, `pl`. A
+  request for another language is refused at request construction, before any
+  media is fetched.
+- **Native platforms:** Windows x86-64 and arm64, Linux x86-64 and arm64, and
+  Apple Silicon. **Intel Macs are not supported**; a request there is refused
+  with a message that names the explicit `whisper` engine instead. No WSL layer
+  is involved.
+- **How it works:** long audio is split into 26-second cores with up to 2 seconds
+  of context on each side, so every standalone clip is ≤ 30 seconds (the native
+  CLI's limit). Overlap words are selected by core midpoint rather than text
+  deduplication, so repeated spoken phrases are preserved.
+- **Streaming is not used.** The native `--audio-stream` mode failed its
+  coverage and is never passed; only the committed standalone output is parsed.
+- **Durable block resume.** With `TEXTFLOWKIT_DB` set, a long run writes partial
+  per-block checkpoints; a resume checks the source and decoded-WAV hashes and the
+  config, then re-runs only the blocks that were not finished. The durable store
+  still assumes one owning process.
+- **Cancellation.** A running Whistle run terminates its exact owned child
+  process bounded by a per-clip timeout. A single long `openai-whisper` model call
+  is still only cancellable at its next stage boundary, as documented for the
+  Whisper engine.
+- **Telemetry is off, unconditionally.** Every Whistle child process forces
+  `NEEDLE_TELEMETRY=0`, `DO_NOT_TRACK=1`, and `CI=1`, overriding a parent that
+  opted in. The product ships no analytics, usage SDK, anonymous ids, or events,
+  and there is no opt-in setting. This applies the upstream documented gate; it
+  is **not** a claim that the upstream binary's tracking code is physically
+  removed.
+- **Offline and downloads.** Set `TEXTFLOWKIT_OFFLINE` to refuse any download, and
+  `TEXTFLOWKIT_MODELS_DIR` to choose the asset directory. The Whistle asset helper
+  downloads only pinned runtime/model assets; media acquisition and optional
+  translation may independently use the network. These downloads are not
+  telemetry.
+
+**Verification boundary.** A local run transcribed a 4-hour (14,407 s)
+recording on CPU into 555 clips / 34,596 words / 2,875 segments in 731 s, with
+telemetry forced off and offline mode on; a separate run proved durable block
+resume across two processes. These are **first local test numbers**, not a
+promise of universal performance or of accuracy equal to Whisper — no
+human-scored word-error rate is claimed. See the
+[user manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
+and [install guide](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md).
+
 ## Use as an MCP server
 
 ```bash
@@ -266,7 +342,7 @@ scope here, so no image is claimed to build or start. See
 
 ```bash
 TEXTFLOWKIT_DB=./jobs.db            # job state survives restart (SQLite)
-TEXTFLOWKIT_MAX_CONCURRENCY=1        # default; Whisper saturates a GPU alone
+TEXTFLOWKIT_MAX_CONCURRENCY=1        # default; bounded job worker pool
 ```
 
 `cancel_job` stops a queued job immediately, or a running job at its next stage
@@ -281,14 +357,31 @@ web frontend share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.8 release.** Core, CLI, MCP, and HTTP have automated
-coverage. This release carries the four fixes for the 2026-10-01 post-release
-audit-lite (findings AL-001 – AL-004): CLI owning-process startup recovery so an
-interrupted run's saved work can be resumed instead of being refused as
-"already active", preservation of the completed transcript across resume setup
-failures, a correction to the MCP batch cookie capability, and corrected roadmap
-evidence receipts. It builds on the v0.1.7 audit repair set and the v0.1.6
-review repairs that precede it. The preceding v0.1.7 source candidate was verified with real CLI, HTTP and MCP speech, seven-format exports and completed resume. The v0.1.8 runtime fixes were independently checked through fresh-process CLI restart probes, real SQLite setup-failure tests, and the full Windows test suite; those checks are not new individual-harness receipts. Release publication uses the tag workflow, which requires successful exact-commit main CI before PyPI uploads and creates the public GitHub release only afterward. Check the linked release for artifacts and workflow status; local source verification is not a fresh PyPI-install or individual-harness receipt.
+**v0.1.9 release.** Core, CLI, MCP, and HTTP have automated
+coverage. This release makes **Whistle the default engine** — a native CPU-only
+transcriber that needs no PyTorch — and moves `openai-whisper` to the optional
+`whisper` extra, selected explicitly with `--engine whisper` or
+`engine="whisper"`. Legacy engine aliases are preserved, so older saved jobs and
+`transcribe()` calls still decode. Whistle refuses an unsupported platform,
+language, or GPU request instead of silently falling back. Its engine's
+verification boundary is in [Whistle (default engine)](#whistle-default-engine)
+above. Release publication uses the tag workflow, which requires successful
+exact-commit main CI before PyPI uploads and creates the public GitHub release
+only afterward. Check the linked release for artifacts and workflow status; local
+source verification is not a fresh PyPI-install or individual-harness receipt.
+
+The v0.1.8 release carried four fixes for the 2026-10-01 post-release audit-lite
+(findings AL-001 – AL-004): CLI owning-process startup recovery so an interrupted
+run's saved work can be resumed instead of being refused as "already active",
+preservation of the completed transcript across resume setup failures, a
+correction to the MCP batch cookie capability, and corrected roadmap evidence
+receipts. It built on the v0.1.7 audit repair set and the v0.1.6 review repairs
+that precede it. The v0.1.7 source candidate was verified with real CLI, HTTP and
+MCP speech, seven-format exports and completed resume; the v0.1.8 runtime fixes
+were independently checked through fresh-process CLI restart probes, real SQLite
+setup-failure tests, and the full Windows test suite. Those checks are not new
+individual-harness receipts. That is the previous release's record, not evidence
+for v0.1.9.
 
 The v0.1.6 release was the post-v0.1.5 review repair set: security hardening
 for media acquisition and the HTTP and MCP adapters, safer subtitle wrapping and
@@ -305,9 +398,9 @@ The v0.1.6 release is public: the
 [v0.1.6 GitHub release](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.6)
 and both [core](https://pypi.org/project/textflowkit/0.1.6/) and
 [fonts](https://pypi.org/project/textflowkit-fonts/0.1.6/) PyPI projects are
-live — that is the previous release's evidence, not a receipt for v0.1.8.
+live — that is the v0.1.6 release's evidence, not a receipt for a later release.
 Everything from here to the end of this section is the v0.1.6 release's
-historical record as published: it is not re-verified for v0.1.8, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.9, whose separate release evidence is not supplied by these historical paragraphs.
 Merged-main CI passed 16/16 on the tagged commit; the published wheel and
 sdist digests match the GitHub release assets and their SHA-256 list; and a fresh
 Windows Python 3.12 install of `textflowkit[export,mcp,http]==0.1.6` from PyPI

{textflowkit-0.1.8 → textflowkit-0.1.9}/compose.yaml

@@ -72,9 +72,10 @@ services:
       - "textflowkit-output:/srv/textflowkit/output"
       - "textflowkit-work:/srv/textflowkit/work"
       - "textflowkit-state:/srv/textflowkit/state"
-      # openai-whisper downloads each model into `~/.cache/whisper` (its own
-      # default download root), so without this volume a recreated container
-      # downloads the model again.
+      # Each engine caches its own model under `~/.cache`: openai-whisper in
+      # `~/.cache/whisper`, and Whistle's pinned binary and model in its own
+      # directory there. Without this volume a recreated container downloads
+      # them again.
       - "textflowkit-cache:/home/textflowkit/.cache"
     healthcheck:
       test:

{textflowkit-0.1.8 → textflowkit-0.1.9}/docs/adapters.md

@@ -1,6 +1,6 @@
-# Adapters and integration
+# Developer and integration manual
 
-Current published release: [v0.1.8](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.8).
+Current release: [v0.1.9](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.9).
 Start with the [user manual](user-manual.md) for everyday use. Harness versions
 in the compatibility table below identify **historical test sessions**, not
 the version of TextFlowKit currently published.
@@ -9,6 +9,8 @@ textflowkit has one core and several thin doors. Nothing is duplicated between
 them: the CLI, the MCP server, and the HTTP API all call
 `textflowkit.core.submission` and share one job model.
 
+![TextFlowKit shared-core architecture: four thin entry points (CLI, Python, MCP, HTTP) feed one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](assets/architecture-overview.svg)
+
 ```
                     ┌──────────────────────┐
    CLI ────────────►│                      │
@@ -200,11 +202,15 @@ the same options: `source`, `language`, `formats`, `output_dir`, `model`,
 `/jobs/batch` these are **per item**: each entry is its own full request, so an
 item's model/language/device apply only to that item (unlike the MCP batch tool,
 which takes one shared set for every source).
-`engine` defaults to `whisper` — openai-whisper on the torch stack: ROCm on AMD,
-CUDA on NVIDIA, CPU otherwise — and may be set to `faster-whisper`, the opt-in
-CTranslate2 engine for CPU and Apple Silicon that needs
-`pip install "textflowkit[faster-whisper]"`. The default is unchanged, and no
-speed or accuracy comparison between the engines is claimed. On a **single**
+`engine` defaults to `whistle` (a CPU-only native CLI needing no torch).
+`engine: "whisper"`
+selects openai-whisper on the torch stack — ROCm on AMD, CUDA on NVIDIA, CPU
+otherwise — and needs `pip install "textflowkit[whisper]"`; `engine:
+"faster-whisper"` is the opt-in CTranslate2 engine for CPU and Apple Silicon that
+needs `pip install "textflowkit[faster-whisper]"`. An unknown engine name, an
+unsupported language or non-CPU device for Whistle, or a missing extra is refused
+rather than silently re-routed, and no speed or accuracy comparison between the
+engines is claimed. On a **single**
 submission (`POST /jobs`) an unknown engine name or a missing extra is answered
 with **422 before a job record is written**. On `/jobs/batch` each item is
 admitted independently: an unusable engine (or any other per-item refusal - an
@@ -530,8 +536,9 @@ pool:
 TEXTFLOWKIT_MAX_CONCURRENCY=1   # default
 ```
 
-The default is **1** deliberately. Whisper saturates a GPU on its own, so parallel
-jobs thrash VRAM rather than finishing sooner.
+The default is **1** deliberately. A single model call saturates a GPU (Whisper)
+or holds a CPU-bound native run (Whistle) on its own, so parallel jobs contend for
+that resource rather than finishing sooner.
 
 **Raising the bound does not by itself parallelise transcription.** Model inference
 is serialized per engine *instance*: `WhisperEngine.transcribe` holds a lock across
@@ -563,7 +570,11 @@ because these are genuinely different situations:
 mid-call. Download hooks and the ffmpeg process respond during acquisition and
 decode, but cancellation during a 20-minute Whisper call takes effect when that
 call returns. The API reports `cancelling` rather than claiming an instant stop
-it cannot deliver.
+it cannot deliver. The default Whistle engine is the exception: a
+running Whistle run polls for cancellation between clips and terminates its exact
+owned child process, bounded by a per-clip timeout — so a long Whistle job stops
+promptly, while a single long `openai-whisper` model call is still only
+cancellable at its next stage boundary.
 
 ## Export formats