textflowkit 0.1.10__tar.gz → 0.1.11__tar.gz

{textflowkit-0.1.10 → textflowkit-0.1.11}/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## v0.1.11 — 2026-10-06
+
+Optional native live streaming supports **Windows x86_64 only**. Core version:
+0.1.11; unchanged optional fonts: 0.1.6. Existing standalone Whistle defaults,
+file/URL jobs, CLI, and MCP behavior are unchanged. The public site remains static
+documentation and serves no streams. Local source validation does not establish
+published-package verification or cross-platform live support.
+
+
+### Added
+
+- **Public `StreamingSession` API.** Bounded PCM feed, typed incremental events,
+  flush/finish, cancellation, canonical final `Transcript`, and context-manager
+  cleanup. One owned native child per session binds directly to the separately
+  pinned `libneedle3.dll`; no upstream Python SDK or telemetry module is loaded.
+  Live sessions are ephemeral, with no replay or durable resume.
+- **Live microphone streaming (opt-in, loopback-only).** When
+  `TEXTFLOWKIT_STREAMING=1` is set, the developer HTTP app serves a `/stream`
+  WebSocket and the local UI serves `/api/stream`, both transcribing audio as it
+  arrives. A runnable, self-hosted browser example is at `/streaming-example`
+  (and `/api/streaming-example` under the UI); its `AudioWorklet` resamples any
+  device rate to 16 kHz mono with continuous phase. Off by default: with the
+  switch unset the endpoint does not exist. The standalone `textflowkit` CLI is
+  unaffected — it does not open a microphone or a streaming socket. Requires the
+  new `streaming` extra (`pip install "textflowkit[streaming]"`), which adds the
+  `websockets` dependency. Auth is fail-closed: the UI accepts only its own origin
+  and capability, the standalone API requires the API token (even in developer
+  mode), and a separate origin may stream only if the operator lists it in
+  `TEXTFLOWKIT_STREAMING_ORIGINS` (a browser needs its own origin listed, including
+  the standalone example's). See [docs/streaming.md](docs/streaming.md).
+  **Bounded live runs verified on this machine's native engine** — 65 s and 300 s
+  through the product core on Windows x86_64. A separate assembled UI WebSocket
+  run fed prerecorded PCM at real time for 12 s. Browser lifecycle and resampling
+  checks used fake audio; **physical microphone capture was not verified**. Only
+  English was measured natively; the other six accepted languages and live
+  Linux/macOS were not exercised. No public remote streaming is provided.
+
 ## v0.1.10 — 2026-10-06
 
 **The local browser interface ships.** The loopback-only browser workspace
@@ -51,7 +88,7 @@ security boundaries. A **native Windows** machine, in a real browser, proved the
 workspace end to end (drop a file, submit, download, stop). That is one platform's
 browser proof, **not** a live Linux or macOS UI run — those platforms are covered
 by automated tests only, and cross-platform CI (Windows/Linux/macOS) is a separate
-step run by the coordinator. **No live optional-backend (translation or
+release gate. **No live optional-backend (translation or
 diarization) run through the UI is claimed.** The engine and packaging changes of
 v0.1.9 are unchanged by this release.
 

{textflowkit-0.1.10 → textflowkit-0.1.11}/CONTRIBUTING.md

@@ -14,9 +14,15 @@ python -m venv .venv
 # Windows: .venv\Scripts\activate
 # POSIX:   source .venv/bin/activate
 pip install ./packages/textflowkit-fonts  # local optional PDF font companion
-pip install -e ".[dev,mcp,http,export]"
+pip install -e ".[dev,mcp,http,streaming,export,whisper]"
 ```
 
+The full suite needs both `streaming` (WebSocket transport) and `whisper`
+(optional standalone engine) dependencies. Use a development environment; for
+an existing AMD ROCm torch stack, follow [the install guide](docs/install.md)
+to preserve that stack. Native live streaming supports Windows x86_64 only;
+ordinary standalone platform support and defaults remain unchanged.
+
 ## Test and lint — the commands CI runs
 
 ```bash

{textflowkit-0.1.10 → textflowkit-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.10
+Version: 0.1.11
 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
@@ -32,6 +32,7 @@ Requires-Dist: python-docx>=1.1; extra == 'all'
 Requires-Dist: reportlab>=4.0; extra == 'all'
 Requires-Dist: textflowkit-fonts<0.2,>=0.1.5; extra == 'all'
 Requires-Dist: uvicorn>=0.30; extra == 'all'
+Requires-Dist: websockets<16,>=15; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: hatchling>=1.25; extra == 'dev'
@@ -53,6 +54,11 @@ 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: streaming
+Requires-Dist: fastapi>=0.115; extra == 'streaming'
+Requires-Dist: pydantic>=2.7; extra == 'streaming'
+Requires-Dist: uvicorn>=0.30; extra == 'streaming'
+Requires-Dist: websockets<16,>=15; extra == 'streaming'
 Provides-Extra: whisper
 Requires-Dist: openai-whisper>=20240930; extra == 'whisper'
 Description-Content-Type: text/markdown
@@ -67,7 +73,7 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [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.10](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.10).**
+**Current release: [v0.1.11](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.11).**
 
 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
@@ -128,7 +134,7 @@ DOCX and PDF are available through the optional `export` extra.
 
 ## Architecture
 
-![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above 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.10/docs/assets/architecture-overview.svg)
+![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above 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.11/docs/assets/architecture-overview.svg)
 
 The design principle is **one shared core, thin doors**. Everything of substance
 lives in the core; the interfaces are thin — the local browser UI is a fifth door
@@ -150,6 +156,32 @@ means writing one source adapter, not another tool.
 For the job lifecycle, process ownership, checkpoints, and output publication,
 see [docs/architecture.md](https://github.com/scottconverse/textflowkit/blob/main/docs/architecture.md).
 
+## Live microphone streaming (opt-in)
+
+In v0.1.11, live streaming supports **Windows x86_64 only**. When
+`TEXTFLOWKIT_STREAMING=1` is set, the developer HTTP app serves a `/stream`
+WebSocket and the local UI serves `/api/stream`, both transcribing a live microphone
+as you speak. A **runnable, self-hosted browser example** ships at
+`/streaming-example` (and `/api/streaming-example` under the UI): it captures with an
+`AudioWorklet`, resamples any device rate to 16 kHz mono, and shows the transcript.
+No CDN, no analytics, no external fetch. Requires the `streaming` extra:
+
+```bash
+python -m pip install "textflowkit[streaming]==0.1.11"
+```
+
+It is **off by default** — with the switch unset the endpoint does not exist — and
+**loopback-only**: auth is fail-closed, so the UI accepts only its own origin and
+capability, the standalone API requires `TEXTFLOWKIT_API_TOKEN` (even in developer
+mode), and a separate origin — including the standalone browser example's own origin —
+may stream only if listed in `TEXTFLOWKIT_STREAMING_ORIGINS`. The standalone
+`textflowkit` CLI is unaffected: it does not open a microphone or a streaming socket.
+**Bounded live runs are verified on the native engine here** — 65 s and 300 s
+end-to-end on Windows x86_64; the transport and the browser resampler are covered by
+tests, and a physical browser microphone has not yet been captured (the browser proof
+drives the page against a fake audio device). See
+[docs/streaming.md](https://github.com/scottconverse/textflowkit/blob/main/docs/streaming.md).
+
 ## Recognized sources
 
 YouTube · TikTok · Facebook · Instagram · Vimeo · Twitch · Bilibili · Rumble ·
@@ -296,7 +328,7 @@ textflowkit export ./transcript.json --format vtt
 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.10/docs/assets/whistle-resume.svg)
+![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.11/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
@@ -313,7 +345,7 @@ torch; `openai-whisper` is an explicitly selectable opt-in engine.
   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
+- **Standalone 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
@@ -407,7 +439,7 @@ its own beyond the `http` extra. It ships with the core package as of v0.1.10:
 a regular install of the current release carries it.
 
 ```bash
-python -m pip install 'textflowkit[http,export]==0.1.10'
+python -m pip install 'textflowkit[http,export]==0.1.11'
 textflowkit-ui
 ```
 
@@ -478,29 +510,34 @@ browser interface share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.10 release.** Core, CLI, MCP, HTTP, and the local browser interface have
-automated coverage. This release **ships the local browser interface**
-(`textflowkit-ui`) in the core package: a loopback-only workspace that reuses the
-same pipeline, submission contract, and job store, with a durable store, cancel
-and resume, and a Windows desktop shortcut (`textflowkit-ui --create-shortcut`).
-It adds **no new dependency** beyond the existing `http` extra, so a regular
-`pip install 'textflowkit[http,export]==0.1.10'` carries it. The engine, CLI,
-Python, MCP, and HTTP surfaces are unchanged and there is **no endpoint-breaking
-change**. It builds on v0.1.9, which made **Whistle the default engine** — a
-native CPU-only transcriber that needs no PyTorch — and moved `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.
+**v0.1.11 release.** Optional live streaming adds a transport-neutral
+`StreamingSession` Python API, incremental transcript events, and authenticated
+loopback WebSockets (`/stream` on the developer HTTP API and `/api/stream` on the
+local UI), with a packaged browser microphone example. The native live capability
+supports **Windows x86_64 only** and uses one owned child with a separately pinned
+`libneedle3.dll`. The `streaming` extra supplies the WebSocket dependency;
+`TEXTFLOWKIT_STREAMING=1` enables the server routes. Streaming is off by default.
+
+Existing file and URL transcription, CLI, MCP, durable jobs, and local browser
+workspace defaults remain unchanged. Whistle stays the CPU-only standalone default;
+`openai-whisper` remains an explicit opt-in engine. The local browser workspace
+introduced in v0.1.10 still needs only the `http` extra for its ordinary job flow.
+Fonts remain 0.1.6. Live sessions are ephemeral and have no durable resume.
+
+**Streaming evidence.** Local English PCM runs exercised the native core for 65 s
+and 300 s; a separate assembled UI WebSocket run fed prerecorded PCM at real time
+for 12 s and returned incremental events and a final transcript. Browser lifecycle
+and resampling checks used fake audio. Physical browser microphone capture, live
+Linux/macOS, and the six other accepted languages were not verified. The public
+website remains static documentation and serves no streaming endpoint. Local source
+validation does not establish published-package or exact-commit CI results.
 
 **Verification limit.** The local browser interface is covered by an automated
 suite, and the UI's behavior was proved on a **native Windows** machine in a real
 browser. No live optional-backend (translation/diarization) run through the UI is
 claimed, and **no live Linux or macOS UI run was performed here** — those
 platforms are covered by automated tests only, and CI across Windows, Linux, and
-macOS is the coordinator's separate step. Release publication uses the tag
+macOS is a separate release gate. 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
@@ -517,7 +554,7 @@ 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 releases' record, not evidence
-for v0.1.10.
+for v0.1.11.
 
 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
@@ -536,7 +573,7 @@ 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 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.10, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.11, 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.10 → textflowkit-0.1.11}/README.md

@@ -8,7 +8,7 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [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.10](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.10).**
+**Current release: [v0.1.11](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.11).**
 
 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
@@ -69,7 +69,7 @@ DOCX and PDF are available through the optional `export` extra.
 
 ## Architecture
 
-![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above 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.10/docs/assets/architecture-overview.svg)
+![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above 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.11/docs/assets/architecture-overview.svg)
 
 The design principle is **one shared core, thin doors**. Everything of substance
 lives in the core; the interfaces are thin — the local browser UI is a fifth door
@@ -91,6 +91,32 @@ means writing one source adapter, not another tool.
 For the job lifecycle, process ownership, checkpoints, and output publication,
 see [docs/architecture.md](https://github.com/scottconverse/textflowkit/blob/main/docs/architecture.md).
 
+## Live microphone streaming (opt-in)
+
+In v0.1.11, live streaming supports **Windows x86_64 only**. When
+`TEXTFLOWKIT_STREAMING=1` is set, the developer HTTP app serves a `/stream`
+WebSocket and the local UI serves `/api/stream`, both transcribing a live microphone
+as you speak. A **runnable, self-hosted browser example** ships at
+`/streaming-example` (and `/api/streaming-example` under the UI): it captures with an
+`AudioWorklet`, resamples any device rate to 16 kHz mono, and shows the transcript.
+No CDN, no analytics, no external fetch. Requires the `streaming` extra:
+
+```bash
+python -m pip install "textflowkit[streaming]==0.1.11"
+```
+
+It is **off by default** — with the switch unset the endpoint does not exist — and
+**loopback-only**: auth is fail-closed, so the UI accepts only its own origin and
+capability, the standalone API requires `TEXTFLOWKIT_API_TOKEN` (even in developer
+mode), and a separate origin — including the standalone browser example's own origin —
+may stream only if listed in `TEXTFLOWKIT_STREAMING_ORIGINS`. The standalone
+`textflowkit` CLI is unaffected: it does not open a microphone or a streaming socket.
+**Bounded live runs are verified on the native engine here** — 65 s and 300 s
+end-to-end on Windows x86_64; the transport and the browser resampler are covered by
+tests, and a physical browser microphone has not yet been captured (the browser proof
+drives the page against a fake audio device). See
+[docs/streaming.md](https://github.com/scottconverse/textflowkit/blob/main/docs/streaming.md).
+
 ## Recognized sources
 
 YouTube · TikTok · Facebook · Instagram · Vimeo · Twitch · Bilibili · Rumble ·
@@ -237,7 +263,7 @@ textflowkit export ./transcript.json --format vtt
 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.10/docs/assets/whistle-resume.svg)
+![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.11/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
@@ -254,7 +280,7 @@ torch; `openai-whisper` is an explicitly selectable opt-in engine.
   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
+- **Standalone 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
@@ -348,7 +374,7 @@ its own beyond the `http` extra. It ships with the core package as of v0.1.10:
 a regular install of the current release carries it.
 
 ```bash
-python -m pip install 'textflowkit[http,export]==0.1.10'
+python -m pip install 'textflowkit[http,export]==0.1.11'
 textflowkit-ui
 ```
 
@@ -419,29 +445,34 @@ browser interface share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.10 release.** Core, CLI, MCP, HTTP, and the local browser interface have
-automated coverage. This release **ships the local browser interface**
-(`textflowkit-ui`) in the core package: a loopback-only workspace that reuses the
-same pipeline, submission contract, and job store, with a durable store, cancel
-and resume, and a Windows desktop shortcut (`textflowkit-ui --create-shortcut`).
-It adds **no new dependency** beyond the existing `http` extra, so a regular
-`pip install 'textflowkit[http,export]==0.1.10'` carries it. The engine, CLI,
-Python, MCP, and HTTP surfaces are unchanged and there is **no endpoint-breaking
-change**. It builds on v0.1.9, which made **Whistle the default engine** — a
-native CPU-only transcriber that needs no PyTorch — and moved `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.
+**v0.1.11 release.** Optional live streaming adds a transport-neutral
+`StreamingSession` Python API, incremental transcript events, and authenticated
+loopback WebSockets (`/stream` on the developer HTTP API and `/api/stream` on the
+local UI), with a packaged browser microphone example. The native live capability
+supports **Windows x86_64 only** and uses one owned child with a separately pinned
+`libneedle3.dll`. The `streaming` extra supplies the WebSocket dependency;
+`TEXTFLOWKIT_STREAMING=1` enables the server routes. Streaming is off by default.
+
+Existing file and URL transcription, CLI, MCP, durable jobs, and local browser
+workspace defaults remain unchanged. Whistle stays the CPU-only standalone default;
+`openai-whisper` remains an explicit opt-in engine. The local browser workspace
+introduced in v0.1.10 still needs only the `http` extra for its ordinary job flow.
+Fonts remain 0.1.6. Live sessions are ephemeral and have no durable resume.
+
+**Streaming evidence.** Local English PCM runs exercised the native core for 65 s
+and 300 s; a separate assembled UI WebSocket run fed prerecorded PCM at real time
+for 12 s and returned incremental events and a final transcript. Browser lifecycle
+and resampling checks used fake audio. Physical browser microphone capture, live
+Linux/macOS, and the six other accepted languages were not verified. The public
+website remains static documentation and serves no streaming endpoint. Local source
+validation does not establish published-package or exact-commit CI results.
 
 **Verification limit.** The local browser interface is covered by an automated
 suite, and the UI's behavior was proved on a **native Windows** machine in a real
 browser. No live optional-backend (translation/diarization) run through the UI is
 claimed, and **no live Linux or macOS UI run was performed here** — those
 platforms are covered by automated tests only, and CI across Windows, Linux, and
-macOS is the coordinator's separate step. Release publication uses the tag
+macOS is a separate release gate. 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
@@ -458,7 +489,7 @@ 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 releases' record, not evidence
-for v0.1.10.
+for v0.1.11.
 
 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
@@ -477,7 +508,7 @@ 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 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.10, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.11, 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.10 → textflowkit-0.1.11}/docs/adapters.md

@@ -1,6 +1,6 @@
 # Developer and integration manual
 
-Current release: [v0.1.10](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.10).
+Current release: [v0.1.11](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.11).
 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.
@@ -8,7 +8,8 @@ the version of TextFlowKit currently published.
 textflowkit has one core and several thin doors. Nothing is duplicated between
 them: the CLI, the MCP server, the HTTP API, and the local browser
 interface (`textflowkit-ui`) all call `textflowkit.core.submission` and share one
-job model.
+job model for file and URL transcription. The optional live `StreamingSession`
+API and WebSockets are ephemeral and bypass durable job submission.
 
 ![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above 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)
 
@@ -506,6 +507,47 @@ agree. So if you do leave it on, put it behind a proxy that appends its own
 observation rather than forwarding the caller's header, and keep
 `FORWARDED_ALLOW_IPS` narrow.
 
+## Live microphone streaming (`/stream`, opt-in)
+
+In v0.1.11, native live streaming supports **Windows x86_64 only**. Other live
+platforms are unsupported; existing standalone defaults and platform support are
+unchanged. Physical browser microphone capture was not verified. The public site
+is static documentation and serves no streams. Both local server surfaces can
+carry a live microphone stream when
+`TEXTFLOWKIT_STREAMING=1` is set: the developer HTTP app at `/stream`, and the UI at
+`/api/stream`. It is **off by default** - with the switch unset the route does not
+exist and a connection is refused before any session is allocated - and it needs the
+`streaming` extra (`websockets`).
+
+```powershell
+python -m pip install "textflowkit[streaming]==0.1.11"
+# Native Windows PowerShell:
+$env:TEXTFLOWKIT_API_TOKEN="choose-a-long-random-token"
+$env:TEXTFLOWKIT_STREAMING="1"
+textflowkit-http --streaming          # ws://127.0.0.1:8767/stream
+# or the documented import target directly - the WS bounds are NOT automatic here,
+# the plain uvicorn line above would keep uvicorn's larger defaults and deflate on:
+uvicorn textflowkit.adapters.http_server:app --host 127.0.0.1 --port 8767 `
+  --ws-max-size 32768 --ws-max-queue 5 --ws-per-message-deflate false --no-proxy-headers
+```
+
+The launcher (`textflowkit-http --streaming`) applies those bounds for you; a direct
+ASGI invocation only has them when the flags are passed. `--no-proxy-headers` keeps
+a proxy header from rewriting the peer address the loopback check reads (the same
+switch the proxy-identity section above discusses).
+
+The endpoint is a plain version-1 JSON + PCM WebSocket: one `start`, binary audio
+(16 kHz mono s16le, ≤ 32000 bytes/frame), then `finish` or `cancel`; the server sends
+`ready`, `event`s, and exactly one terminal `final` or `error`. Sessions are
+ephemeral - no job row, no resume, no reconnect. Auth is fail-closed and there is no
+anonymous path: a non-browser client sends `Authorization: Bearer` (or `token` in the
+start JSON); a browser the UI served sends the UI capability. The standalone
+`/stream` may additionally admit exact extra origins from
+`TEXTFLOWKIT_STREAMING_ORIGINS` (token-authenticated); the UI's own origin is never
+widened by that list. Streaming is loopback-only even under
+`TEXTFLOWKIT_ALLOW_REMOTE`. The full contract, lifecycle, limits, and a generic
+integration recipe are in [streaming.md](streaming.md).
+
 ## Local browser interface (`textflowkit-ui`)
 
 `textflowkit-ui` is a fourth thin door beside the CLI, MCP, and HTTP entry
@@ -518,7 +560,7 @@ supplies FastAPI and uvicorn, and adds no new dependency). It has no public site
 of its own: it is a local app, not a hosted service.
 
 ```bash
-python -m pip install 'textflowkit[http,export]==0.1.10'
+python -m pip install 'textflowkit[http,export]==0.1.11'
 textflowkit-ui                 # serve on 127.0.0.1 and open a browser
 textflowkit-ui --no-browser --port 8901
 ```

{textflowkit-0.1.10 → textflowkit-0.1.11}/docs/architecture.md

@@ -1,4 +1,4 @@
-# Architecture and job lifecycle
+# Architecture and job lifecycle — v0.1.11
 
 This guide describes how textflowkit is put together and how a job moves through
 it. It is orientation for maintainers and integrators; it is not a deployment
@@ -26,6 +26,20 @@ a streamed upload, and a capability endpoint. It **ships in the core package as
 of v0.1.10** and adds no new dependency beyond the `http` extra. It is a local
 app: the published website is static documentation and never runs the pipeline.
 
+Live streaming added in v0.1.11 is an optional **Windows x86_64 only** path:
+`StreamingSession` drives one owned native child through direct `ctypes` bindings
+to a separately pinned `libneedle3.dll`. Authenticated loopback WebSockets and a
+packaged browser example sit above that core; no job row or resume is created.
+Server routes are off unless `TEXTFLOWKIT_STREAMING=1` is set and need the
+`streaming` extra. The existing standalone Whistle default and ordinary file/URL
+job paths are unchanged. Physical microphone capture and live Linux/macOS were
+not verified; the static public site does not run this path.
+
+![Optional Windows x86_64 streaming: bounded PCM passes through an authenticated loopback WebSocket to an ephemeral StreamingSession and one owned native child; incremental events return, finish flushes to a canonical Transcript, and cancel releases the session. No durable job or resume; off by default; physical microphone capture not verified; the public site serves no streams.](assets/live-streaming-flow.svg)
+
+This separate live path bypasses durable job submission; the file/URL job
+diagrams describe the existing standalone workflow.
+
 ### One owner per database
 
 The durable SQLite store is owned by exactly one process. `textflowkit-ui`
@@ -88,8 +102,19 @@ flowchart LR
     TR --> RENDER[Render and publish files]
     RUN --> STORE
     STORE --> READ[Shared paging and search]
+    MIC[Browser mic or programmatic client] -. opt-in .-> WS[WebSocket /stream or /api/stream]
+    WS --> SESSION[core.streaming StreamingSession]
+    SESSION --> WPROC[Owned stream_worker child, libneedle3]
+    WPROC --> SESSION
+    SESSION -. events .-> WS
 ```
 
+Streaming is the one path that does **not** go through `core.submission`: a live
+session is ephemeral, owns no job row, and is driven by its own transport-neutral
+`StreamingSession`. It is off unless `TEXTFLOWKIT_STREAMING=1`. The dotted edges are
+that opt-in, loopback-only path, running in parallel with the batch pipeline above
+and sharing only the native engine library, never a job row.
+
 ## Components
 
 | Component | Source | Responsibility |
@@ -106,6 +131,7 @@ flowchart LR
 | Postprocessing | `core/diarize.py`, `core/translate.py` | Optional speaker assignment and translation |
 | Output | `render/` | Human-readable formats and canonical JSON; atomic file publication |
 | Retrieval | `core/retrieval.py` | Hidden filtering, time selection, paging, substring search |
+| Live streaming | `core/streaming.py`, `core/stream_worker.py`, `adapters/streaming_ws.py` | Opt-in, loopback-only microphone stream: a transport-neutral session drives one owned native child over line JSON, fed by a guarded WebSocket. No job row, no resume. See [streaming.md](streaming.md). |
 
 ## Job lifecycle
 

textflowkit-0.1.11/docs/assets/live-streaming-flow.svg

@@ -0,0 +1,50 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1180 490" width="1180" height="490" role="img" aria-labelledby="streamTitle streamDesc" font-family="Inter, ui-sans-serif, system-ui, 'Segoe UI', sans-serif">
+  <title id="streamTitle">TextFlowKit v0.1.11 optional local live streaming</title>
+  <desc id="streamDesc">Windows x86_64 only, off by default. A browser AudioWorklet or programmatic PCM client feeds signed 16-bit little-endian mono 16000 Hz audio into an authenticated loopback WebSocket: /stream on the developer HTTP API or /api/stream on the UI. Origin, Host and peer checks guard the transport. StreamingSession bounds audio backlog at five seconds and defaults to one native session per process. One owned child binds directly to a separately pinned libneedle3.dll. Incremental committed text and a replacement provisional tail return to the client. Finish flushes accepted audio and returns a canonical Transcript; cancel or disconnect cleans up the owned child. No durable job, replay or resume. Existing standalone Whistle defaults remain unchanged. The public site serves no streams; physical microphone capture was not verified.</desc>
+  <defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#3b556e"/></marker></defs>
+  <style>
+    .title {fill:#14303f;font-size:24px;font-weight:700}
+    .head {fill:#14303f;font-size:18px;font-weight:700}
+    .body {fill:#3b556e;font-size:15px}
+    .note {fill:#5b7186;font-size:14px}
+    .edge {fill:none;stroke:#3b556e;stroke-width:2;marker-end:url(#arrow)}
+  </style>
+  <rect x="1" y="1" width="1178" height="488" rx="18" fill="#f7fafc" stroke="#d5e0e9"/>
+  <text x="30" y="42" class="title">Optional local live streaming — v0.1.11</text>
+  <text x="30" y="70" class="body">Windows x86_64 only · streaming extra + TEXTFLOWKIT_STREAMING=1 · off by default</text>
+  <rect x="30" y="105" width="250" height="150" rx="12" fill="#e0e7f8" stroke="#b8c7df"/>
+  <text x="46" y="133" class="head">Browser or PCM client</text>
+  <text x="46" y="161" class="body">AudioWorklet resampling</text>
+  <text x="46" y="186" class="body">16 kHz mono · s16le</text>
+  <text x="46" y="211" class="body">≤ 32000 bytes per frame</text>
+  <text x="46" y="236" class="body">Explicit Start / Stop / Cancel</text>
+  <path d="M 282 180 H 313" class="edge"/>
+  <rect x="315" y="105" width="250" height="150" rx="12" fill="#eef4f8" stroke="#b8c7df"/>
+  <text x="331" y="133" class="head">Loopback WebSocket</text>
+  <text x="331" y="161" class="body">/stream or /api/stream</text>
+  <text x="331" y="186" class="body">Token / UI capability auth</text>
+  <text x="331" y="211" class="body">Exact origin + Host + peer</text>
+  <text x="331" y="236" class="body">Bounded queues and sends</text>
+  <path d="M 567 180 H 598" class="edge"/>
+  <rect x="600" y="105" width="250" height="150" rx="12" fill="#dff3ea" stroke="#a6cdbc"/>
+  <text x="616" y="133" class="head">StreamingSession</text>
+  <text x="616" y="161" class="body">Transport-neutral core API</text>
+  <text x="616" y="186" class="body">≤ 5 s unprocessed audio</text>
+  <text x="616" y="211" class="body">Bounded events and history</text>
+  <text x="616" y="236" class="body">Default: 1 session / process</text>
+  <path d="M 852 180 H 883" class="edge"/>
+  <rect x="885" y="105" width="265" height="150" rx="12" fill="#dff3ea" stroke="#a6cdbc"/>
+  <text x="901" y="133" class="head">One owned native child</text>
+  <text x="901" y="161" class="body">Pinned libneedle3.dll</text>
+  <text x="901" y="186" class="body">Direct ctypes · shared model</text>
+  <text x="901" y="211" class="body">No upstream Python SDK</text>
+  <text x="901" y="236" class="body">Cleanup on cancel / disconnect</text>
+  <path d="M 1017 258 V 306 H 155 V 258" class="edge"/>
+  <rect x="235" y="284" width="700" height="39" rx="10" fill="#f7fafc"/>
+  <text x="250" y="309" class="body">Incremental events: append committed text + replace the provisional tail</text>
+  <rect x="30" y="347" width="1120" height="64" rx="12" fill="#fff8ea" stroke="#e2cc9e"/>
+  <text x="46" y="373" class="body">Finish: flush accepted PCM → canonical Transcript. Cancel / disconnect: release the owned session.</text>
+  <text x="46" y="397" class="body">Ephemeral stream: no durable job row, replay or resume. Existing standalone Whistle defaults stay unchanged.</text>
+  <text x="30" y="442" class="note">Evidence: 65 s / 300 s native core PCM runs; separate 12 s UI WebSocket PCM run. Physical mic not verified.</text>
+  <text x="30" y="466" class="note">This is a local app capability. The public website is static documentation and serves no streams.</text>
+</svg>