Skip to content

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

Pre-release
Pre-release

Choose a tag to compare

View all tags
@DF-wu DF-wu released this 17 Jul 19:20
fork-v2.0.0-rc.1
62341b0
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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

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.

Documentation

fork-v2.0.0-rc.1 — 跨平台 release candidate（繁體中文）

這是精確指向已合併 master commit
62341b0fb396dec657823a55bf2cb9293e5b9048
的 GitHub pre-release，不是 stable release，也不宣稱已完成真實裝置、模型、
GPU 或目標硬體驗證。

先說清楚：Server 與 Client 是兩件事

Server 端

**只有 Server 會載入 ASR 模型並執行語音辨識。**Server 負責模型與 runtime、
Server 端 FFmpeg 解碼、熱詞、推論排程、逐字稿、health 與 readiness。

  • Windows 可執行 start_server.exe；Linux headless 建議使用 Docker；Windows／
    Linux 也可從 source 執行 start_server_universal.py。
  • Desktop Client 使用 WebSocket 6016，預設開啟。
  • Web、CLI、TUI、OpenAI SDK／curl 使用 HTTP 6017；HTTP API 預設關閉，需明確
    啟用    。
  • /health 只代表 process 存活；真正送 audio 前應確認 /ready。

Client 端

**Client 不載入 ASR 模型，也不自行推論。**各 Client 只負責輸入、操作與顯示：

  • **Windows／Linux X11 Desktop Client：**經 WebSocket 6016 連線，負責麥克風、
    tray、global hotkey、檔案流程、clipboard／文字注入。
  • **Web Console：**經 HTTP 6017 連線。Web image 只在 8080 提供 static UI；
    browser 仍直接把 ASR request 送到 Server 6017。
  • **CLI：**經 HTTP 6017 連線，提供 script、batch、atomic output 與選用本機 OS
    TTS。
  • **Textual TUI：**經 HTTP 6017 連線，提供 keyboard-first diagnostics、file
    transcription、儲存與選用 native microphone。
  • **OpenAI SDK／curl：**經 HTTP 6017/v1 呼叫 transcription subset；是外部 API
    caller，不是另一套 bundled UI。

Web／CLI 的 TTS 在 Client 本機完成，不是 Server endpoint。

Windows ZIP 怎麼使用

附件 CapsWriter-Offline-windows-x86_64.zip 是 post-merge portability workflow
產生的原始 ZIP，內含兩個角色不同的程式：

  1. start_server.exe：載入模型並提供辨識服務。
  2. start_client.exe：提供 tray、hotkey、錄音與文字輸入操作。

請保留完整解壓目錄，不要只抽出其中一個 EXE。ZIP 的 models/ 刻意保持空白，
也不內含 GGUF runtime DLL 或 FFmpeg。要啟動 package 的預設 Qwen Server，需先依
Windows package 指南
安裝兩個有固定 SHA-256 的 upstream assets：預設 Qwen ASR model，以及相符的
Windows x86-64 GGUF／llama.cpp runtime DLL。

FFmpeg 是另一項 media-path 需求，不是 microphone／WebSocket path 啟動 Server 的
先決條件。Desktop 檔案／media 轉錄或 HTTP file decode 才需要可信來源的
ffmpeg.exe；ffprobe.exe 可提供 duration／progress。指南固定的是 model 與 GGUF
runtime checksum，並未替第三方 FFmpeg distribution 指定 release SHA-256。只連到
遠端 Server 的 Desktop Client 不需要本機 ASR model 或 GGUF runtime。

ZIP 的 SHA-256：

9f1661c0e2bfcf34f5e433fa1d42dcc394b4ff0a882490d69a64e99197cd87e6  CapsWriter-Offline-windows-x86_64.zip

同目錄執行 sha256sum -c SHA256SUMS 即可驗證；SHA256SUMS 不涵蓋 GitHub
動態產生的 source archives。

Windows PowerShell 也可直接核對 ZIP，輸出必須與上方 checksum 相同：

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

Container images

  • Server：
    ghcr.io/df-wu/capswriter-offline-server:sha-62341b0fb396dec657823a55bf2cb9293e5b9048
    （digest sha256:138f0435c14b97ee7243dcd8d821090f801293cd421aea855fcf98bf9aab727f）
  • Web：
    ghcr.io/df-wu/capswriter-offline-web:sha-62341b0fb396dec657823a55bf2cb9293e5b9048
    （digest sha256:5ac83447eecc64848bf5d11b78ab3a5fd30019683325ff0b618bcb9b6498d317）

兩者皆為這個 exact commit 的 linux/amd64 image。latest 是會移動的 alias，
不是 immutable release identifier；需要可稽核部署／rollback 時請 pin full commit
tag 與 digest。

HTTP API 邊界

Server 的選用 HTTP API 提供 /health、/ready、/v1/models 與
POST /v1/audio/transcriptions，支援 text、json、verbose_json、srt、
vtt 五種 format。

它只相容 whisper-1 檔案轉錄 subset，不支援 streaming、speaker
diarization、log probabilities、translation 或完整 OpenAI Audio API；
/v1/audio/translations 明確回 501。

本 release 的可調整 HTTP 預設限制如下：

設定 預設值 意義
CAPSWRITER_HTTP_API_MAX_UPLOAD_MB 100 最大 uploaded file bytes；multipart body 另有有界 overhead
CAPSWRITER_HTTP_API_MAX_AUDIO_SECONDS 3600 最大 decoded 16 kHz mono audio 秒數
CAPSWRITER_HTTP_API_TASK_TIMEOUT 600 單一 end-to-end deadline 秒數
CAPSWRITER_HTTP_API_MAX_CONCURRENT_REQUESTS 2 Active upload／decode／transcription requests
CAPSWRITER_HTTP_API_MAX_PENDING_REQUESTS 4 有界等待 callers；超過時回 429

Browser Client 的 packaged Web Console 使用 8080；Vite development 使用
5173；兩者都由 browser 直接呼叫 Server 6017。CORS allowlist 只應保留實際
使用的 exact origins，例如：

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

localhost 與 127.0.0.1 是不同 browser origins；未使用的 origin 應移除，修改後
必須重建 Server。CLI、TUI、SDK 與 curl 不受 browser CORS 管制。

Exact commit 的自動化證據

這些證據驗證的是 source／package／image gates，不等於真實 ASR 品質或目標主機
行為已驗證。

Stable fork-v2.0.0 前仍需完成

  • 真實 Windows 的 launch／exit、tray、hotkey、microphone、clipboard、FFmpeg、
    model、known-audio、child-process cleanup 與 target hardware 測試。
  • 真實 Linux X11 shortcut／desktop workflow；Wayland／headless global hotkey 仍
    不支援。
  • 每個宣稱 profile 的 cold model bootstrap 與中／英文 known-audio。
  • 目標 CPU／GPU／DirectML 的 driver、memory、performance、fallback 與 hardware
    evidence。
  • 真實 browser secure-context microphone 與選用 TUI sounddevice／PortAudio
    microphone 測試。
  • Upgrade／rollback rehearsal 與最後 known-limit review。

完整文件請從 繁體中文 README
或 English README
開始；元件與連接埠請先讀 Server 與 Client 分工。

Assets 4
Loading