fork v2.0.0-rc.1 - cross-platform release candidate

fork-v2.0.0-rc.1 — cross-platform release candidate

This is a GitHub pre-release from the exact merged master commit
62341b0fb396dec657823a55bf2cb9293e5b9048.

This release candidate keeps speech recognition local and makes the component
boundary explicit: the Server owns models and ASR inference; Clients own audio
input, interaction, and result presentation. It is not yet a stable
real-device, real-model, GPU, or target-hardware qualification claim.

Start here: Server and Clients are separate

Server

The CapsWriter Server is the only component that loads the ASR model and runs
recognition. It owns model/runtime setup, server-side FFmpeg decoding, hotwords,
inference scheduling, transcripts, health, and readiness.

Server deployment choices:

• Windows package/native: start_server.exe or
  python start_server_universal.py.
• Linux Docker: the recommended headless/NAS/shared-service path on
  linux/amd64.
• Windows/Linux source: for development, debugging, and custom installs.

Server interfaces:

Interface	Default	Consumers
WebSocket ws://127.0.0.1:6016	Enabled	Windows/Linux X11 desktop Client
OpenAI-compatible HTTP http://127.0.0.1:6017	Disabled; explicit opt-in	Web, CLI, TUI, OpenAI SDK, curl
HTTP /health	With HTTP	Process liveness only
HTTP /ready	With HTTP	Model/runtime readiness for audio

/health does not replace /ready. Authentication is required for an enabled
non-loopback HTTP bind unless the explicitly unsafe test-only override is used.

Clients

Clients do not load the recognition model and do not run ASR inference.

Client	Connects to	Owns locally	Important boundary
Windows/Linux X11 desktop	WebSocket :6016	Microphone, tray, global hotkeys, file workflow, clipboard/text injection	Its normal path does not require the HTTP API
Web Console	HTTP :6017	Browser recording/upload, downloads, browser/OS TTS	The Web image serves static UI on :8080; the browser still calls the Server on :6017
No-GUI CLI	HTTP :6017	Batch/file workflow, atomic output, optional OS TTS	No model, microphone, tray, or global hotkey
Textual TUI	HTTP :6017	Keyboard workflow, file input, atomic save, optional native microphone	No model, TTS, tray, or global hotkey
OpenAI SDK / curl	HTTP :6017/v1	Integration-specific file upload/handling	This is an external caller, not a bundled user interface

Web/CLI TTS is client-local. The ASR Server does not expose a TTS endpoint.

Attached Windows package

The attached CapsWriter-Offline-windows-x86_64.zip is the unmodified ZIP
produced by the exact post-merge portability workflow. It contains two separate
programs:

1. start_server.exe loads the model and provides recognition.
2. start_client.exe provides tray, hotkeys, recording, and text-input UX.

Keep the complete extracted directory layout; do not copy either EXE out by
itself.

The ZIP deliberately has an empty models/ directory and does not bundle
GGUF runtime DLLs or FFmpeg. To start the package's default Qwen Server, first
install the two SHA-256-pinned upstream assets in the
Windows package guide:

• the documented default Qwen ASR model; and
• its matching Windows x86-64 GGUF/llama.cpp runtime DLLs.

FFmpeg is a separate media-path requirement, not a prerequisite for starting
the microphone/WebSocket path. Install trusted ffmpeg.exe for desktop
file/media transcription or HTTP file decoding; ffprobe.exe adds
duration/progress reporting. The guide SHA-pins the model and GGUF runtime, but
does not assign a release SHA-256 to a third-party FFmpeg distribution.

A desktop Client that connects to a different Server does not need a local ASR
model or GGUF runtime.

Windows asset checksum

9f1661c0e2bfcf34f5e433fa1d42dcc394b4ff0a882490d69a64e99197cd87e6  CapsWriter-Offline-windows-x86_64.zip

Verify the attached files from the same directory:

sha256sum -c SHA256SUMS

Or verify the ZIP directly in Windows PowerShell and compare the output with
the checksum above:

(Get-FileHash .\CapsWriter-Offline-windows-x86_64.zip -Algorithm SHA256).Hash.ToLowerInvariant()

SHA256SUMS covers the attached Windows ZIP. It does not cover GitHub's
dynamically generated source archives.

Immutable container images

Both images were published from the exact tagged commit for linux/amd64.
Pin the full commit tag and, where reproducibility matters, the OCI digest.

Server image

ghcr.io/df-wu/capswriter-offline-server:sha-62341b0fb396dec657823a55bf2cb9293e5b9048
sha256:138f0435c14b97ee7243dcd8d821090f801293cd421aea855fcf98bf9aab727f

Web image

ghcr.io/df-wu/capswriter-offline-web:sha-62341b0fb396dec657823a55bf2cb9293e5b9048
sha256:5ac83447eecc64848bf5d11b78ab3a5fd30019683325ff0b618bcb9b6498d317

The Web image is only the static UI. It does not contain the ASR model or the
Server, and inference requests still go to the configured Server HTTP API.

latest is a movable alias, not an immutable release identifier. Do not use
latest when an auditable deployment or rollback requires this exact release.

HTTP API scope

The optional Server HTTP interface implements a bounded, transcription-only
subset compatible with the official OpenAI Python SDK's whisper-1 request
shape.

• GET /health, GET /ready, and GET /v1/models (Bearer-authenticated when
  a Server key is configured).
• POST /v1/audio/transcriptions.
• text, json, verbose_json, srt, and vtt response formats.
• Explicit upload, decoded-audio, queue, concurrency, deadline, response-size,
  authentication, and browser CORS controls.

It does not implement streaming, speaker diarization, log probabilities,
translation, or the complete OpenAI Audio API. Unsupported fields return
explicit errors; /v1/audio/translations returns 501.

Default HTTP resource limits are configurable, validated at startup, and set
as follows in this release:

Setting	Default	Meaning
CAPSWRITER_HTTP_API_MAX_UPLOAD_MB	100	Maximum uploaded file bytes; the multipart body has a separate bounded overhead
CAPSWRITER_HTTP_API_MAX_AUDIO_SECONDS	3600	Maximum decoded 16 kHz mono audio duration
CAPSWRITER_HTTP_API_TASK_TIMEOUT	600	One end-to-end deadline in seconds
CAPSWRITER_HTTP_API_MAX_CONCURRENT_REQUESTS	2	Active upload/decode/transcription requests
CAPSWRITER_HTTP_API_MAX_PENDING_REQUESTS	4	Bounded waiting callers; overflow returns 429

For the browser Client, the packaged Web Console is served from :8080 and
Vite development from :5173; in both cases the browser calls the Server on
:6017. Configure an exact allowlist containing only the origins you use, for
example:

CAPSWRITER_HTTP_API_CORS_ORIGINS=http://127.0.0.1:8080,http://localhost:8080,http://127.0.0.1:5173,http://localhost:5173

localhost and 127.0.0.1 are different browser origins. Remove unused
origins, and recreate the Server after changing the allowlist. CLI, TUI, SDK,
and curl are not governed by browser CORS.

What changed in this release candidate

• A Windows/Linux universal Server entrypoint and a CI-built Windows production
  package containing separately self-checked Server and Client executables.
• A Linux Docker/Compose Server with model bootstrap, CPU fallback, optional
  GPU paths, persistent model/hotword/log locations, and readiness-aware health
  checks.
• An opt-in OpenAI-compatible transcription API with bounded resource and
  security controls.
• A React/Vite Web Console, standard-library no-GUI CLI, and bilingual Textual
  TUI, all kept separate from Server inference.
• Bounded Linux X11 desktop hotkeys with explicit Wayland/headless refusal.
• Paired English/Traditional Chinese documentation, release gates, pinned
  workflow dependencies, and Server/Web image provenance/SBOM requests.

See the tag-pinned complete English release notes
or 完整繁體中文 release notes.

Automated evidence for this exact merge commit

• CI run 29605187536 — passed.
• Portability and Windows-package run 29605187484 — passed; source of the attached ZIP.
• Server-image run 29605187527 — passed.
• Web-image run 29605187523 — passed.

These checks prove the recorded source/package/image gates for this commit.
They do not prove production recognition quality or real target-host behavior.

Still required before a stable fork-v2.0.0 claim

• Real Windows launch/exit, tray, shortcut, microphone, clipboard, FFmpeg,
  model, known-audio, child-process cleanup, and target-hardware tests.
• Real Linux X11 shortcut and desktop workflow tests; Wayland/headless global
  hotkeys remain unsupported.
• Cold model bootstrap plus known Mandarin/English audio for every advertised
  model/profile.
• Target CPU/GPU/DirectML driver, memory, performance, fallback, and hardware
  evidence.
• Real browser microphone/secure-context tests and optional TUI
  sounddevice/PortAudio microphone tests.
• Upgrade/rollback rehearsal and a final known-limit review....

fork v1.0.0-rc.1 - legacy source release candidate

fork-v1.0.0-rc.1 — legacy source-only release candidate

This is a GitHub pre-release from the exact maintenance/v1 commit
efd24cb1bd1ea5e624561dd869aaea9c5d5c02a5.

This release is deliberately source-only. It is the isolated legacy v1 line,
not fork v2, and it is not a stable real-device/model qualification claim.

Deliverables by role

Server

• Legacy Linux bare-metal and Docker Server source.
• WebSocket service on 6016.
• Opt-in, transcription-only OpenAI-compatible HTTP API on 6017.
• Compose builds locally as capswriter-offline-v1-local:source; no v1 image is
  published.
• v1 must never consume or publish the v2
  ghcr.io/df-wu/capswriter-offline-server:latest image.

Client

• Compatibility-preserved upstream-era Windows desktop Client source:
  start_client.py.
• It owns microphone capture, tray, hotkeys, clipboard, and text injection, and
  connects to the Server over WebSocket 6016.
• No Windows executable is attached.
• v2 Web Console, CLI, TUI, and universal Windows package are not included.

External API callers

curl, the OpenAI SDK, or another compatible application can call the Server's
whisper-1-shaped file-transcription subset. This is a Server interface, not a
bundled Client. It supports the documented transcription formats; when a key is
configured, the transcription endpoint accepts Bearer authentication.
Translation, streaming, diarization, and the complete OpenAI Audio API are not
implemented. /v1/audio/translations returns 501.

Safety and documentation changes

• Compose now passes the HTTP settings into the container even when the API is
  disabled. The container bind (0.0.0.0) and host publish bind (loopback
  127.0.0.1) are documented separately; remote use requires an authenticated
  TLS reverse proxy and an intentional host bind.
• Mutable hot-server.txt, hot.txt, hot-rule.txt, and hot-rectify.txt are
  excluded from local Docker build layers.
• The old v1 image-publish workflow was removed; the tagged tree contains no
  package-writing publish workflow and does not publish the shared v2 latest
  image.
• English and Traditional Chinese README, maintenance, release, and HTTP API
  guides state the Server/Client boundary explicitly.

Automated evidence for this exact source

• Push matrix run
  and pull-request matrix run
  both passed all four Ubuntu 24.04/Windows 2022 × Python 3.10/3.12 legs.
• Each leg ran 51 maintenance tests and compile checks.
• Compose and docker/server/entrypoint.sh validation ran in the Ubuntu 24.04 /
  Python 3.10 validation job.
• Local verification additionally passed selected bilingual documentation-link
  checks and the isolated 51-test suite.

These checks do not prove model quality, known-audio recognition, GPU/CPU
performance, a disposable image build, or real Windows desktop behavior.

Still required before a stable v1 claim

• Cold model bootstrap and Mandarin/English known-audio transcription.
• Target CPU/GPU backend and driver/runtime evidence.
• Real Windows launch/exit, tray, hotkey, microphone, clipboard, FFmpeg, model,
  and child-process cleanup checks.
• A separately reviewed immutable v1 image workflow before advertising any v1
  image.

Documentation

• 繁體中文 README
• English README
• 繁體中文 HTTP API guide
• English HTTP API guide
• English release notes
• 繁體中文 release notes

---

fork-v1.0.0-rc.1 — legacy source-only release candidate（繁體中文）

這是精確指向 maintenance/v1 commit
efd24cb1bd1ea5e624561dd869aaea9c5d5c02a5 的 GitHub pre-release。

本 release 刻意只提供 source，屬於隔離的 legacy v1 line，不是 fork v2，也不
宣稱已完成真實裝置或 model qualification。

依角色說明

• **Server：**Linux bare-metal／Docker Server source、WebSocket 6016，以及
  opt-in、transcription-only 的 HTTP API 6017。Compose 會從 source 建立
  capswriter-offline-v1-local:source；不發布 v1 image，也不會讀取或覆寫 v2
  的 latest。
• **Client：**只有相容保留的 upstream-era Windows desktop source
  start_client.py，負責麥克風、tray、hotkey、clipboard、文字注入，透過
  WebSocket 6016 連到 Server。不附 Windows executable，不含 v2 Web／CLI／TUI
  或 universal Windows package。
• **外部 API caller：**curl／OpenAI SDK 等外部程式呼叫 Server 的 whisper-1
  檔案轉錄 subset。它不是 bundled Client；不實作 translation、streaming、
  diarization 或完整 OpenAI Audio API，/v1/audio/translations 回 501。

Compose 的 container bind 0.0.0.0 與 host publish bind 127.0.0.1 已分開說明；
非 loopback 使用必須設定 authentication、TLS reverse proxy 與明確的 host bind。
可變 hotword 檔不會進入 local image layer；舊 v1 publish workflow 已移除。

這個 exact source 的自動化證據

• Push matrix
  與 pull-request matrix
  均通過 Ubuntu 24.04／Windows 2022 × Python 3.10／3.12 四個 legs。
• 每個 leg 執行 51 個 maintenance tests 與 compile checks；Compose／entrypoint
  validation 只在 Ubuntu 24.04／Python 3.10 validation job 執行。
• 這些證據不代表 model quality、known-audio、GPU／CPU performance、image build
  或真實 Windows desktop 已驗證。

Stable v1 前仍需完成 cold model bootstrap、中文／英文 known-audio、target
CPU／GPU、真實 Windows desktop 與獨立審查的 immutable v1 image workflow。

完整雙語文件請見本 release 內的 繁中 README、
English README、
繁中 API guide
與 English API guide。