dsh-pf-stream 0.3.0 → 0.3.2

package/README.en.md

@@ -1,8 +1,31 @@
-# dsh-pf-stream
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Weilv-D/dsh-pf-stream/main/icon.svg" width="72" height="72" alt="Video understanding">
+</p>
 
-[中文](https://github.com/Weilv-D/dsh-pf-stream/blob/main/README.md) | **English**
+<h1 align="center">Video understanding</h1>
 
-Let the agent watch videos: adaptive sampling, plus the spoken lines.
+<p align="center">Frames, motion and speech from a video, aligned on a timeline for the agent.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-pf-stream"><img src="https://img.shields.io/npm/v/dsh-pf-stream?color=2f6feb" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/license-Apache--2.0-2ea44f" alt="license">
+  <img src="https://img.shields.io/badge/DSH-plugin-6e56cf" alt="DSH plugin">
+</p>
+
+<p align="center"><a href="README.md">中文</a> · <b>English</b></p>
+
+---
+
+## Quick start
+
+| Step | Do |
+| :--- | :--- |
+| 1 | Install ffmpeg ([commands below](#1-install-ffmpeg)); `ffmpeg -version` must print output |
+| 2 | Left sidebar **Plugins** → **Video understanding** → switch it on |
+| 3 | Click **Download local model** (~190 MB), then **Test transcription** |
+| 4 | Give the agent a video path and ask |
+
+Video works without transcription. Only videos that have no subtitles and need speech text require step 3.
 
 ## What it does
 
@@ -24,12 +47,12 @@ ffprobe -version
 Both must print output. If not:
 
 | OS | Command |
-| --- | --- |
+| :--- | :--- |
 | Windows | `winget install Gyan.FFmpeg` |
 | macOS | `brew install ffmpeg` |
 | Ubuntu / Debian | `sudo apt install ffmpeg` |
 
-Open a new terminal and check again. To keep it out of PATH, set `ffmpegPath` and `ffprobePath` in the plugin config.
+> Open a new terminal and check again. To keep it out of PATH, set `ffmpegPath` and `ffprobePath` in the plugin config.
 
 ### 2. Install the plugin in DSH
 
@@ -56,30 +79,32 @@ The transcription engine decides whether videos without subtitles get speech tex
 
 To open the settings: **Plugins in the left sidebar → Video understanding → the panel below the description**. Use the same path later to change settings.
 
+<p><img src="https://raw.githubusercontent.com/Weilv-D/dsh-pf-stream/main/docs/assets/panel.png" width="720" alt="Transcription settings panel on the plugin detail page: decoder, local transcription and cloud transcription cards"></p>
+
 Three cards at the top report video decode (ffmpeg), local transcription, and cloud transcription. Pick one path:
 
 | Path | Best for | What to do |
-| --- | --- | --- |
+| :--- | :--- | :--- |
 | Local (recommended) | Free, offline, no API key | Click "Download local model" (~190 MB), then "Test transcription" |
 | Cloud | You have a key, or the machine is slow | Pick OpenAI / Groq / a custom compatible endpoint, paste the key, save, then test |
 | Skip for now | Videos have subtitles | Use it as is; speech-only videos get no transcript |
 
-Local model steps:
+### Local model
 
 1. Click "Download local model". The progress bar shows bytes received; cancel at any time.
 2. Clicking again after an interruption resumes the download.
 3. When done, the card reads "Ready · whisper.cpp".
 4. Click "Test transcription". "Local engine available" means it works.
 
-Cloud key steps:
+One-click install currently supports Windows x64. On other systems, install whisper.cpp and set `audio.asr.local.binPath` in the config file, or use cloud transcription.
+
+### Cloud key
 
 1. Choose a provider under "Cloud transcription key".
 2. Paste the API key and click "Save". After saving, only "Configured" is shown; the key is never echoed back.
 3. Click "Test transcription" to verify the key and network.
 
-The default policy is `auto`: use a cloud key when configured, otherwise the local engine. Under "Advanced" you can switch to local only, cloud only, or off.
-
-One-click install currently supports Windows x64. On other systems, install whisper.cpp and set `audio.asr.local.binPath` in the config file, or use cloud transcription.
+> **Auto policy**: cloud is used when key, endpoint and model are all set (faster, billed per use); otherwise the local engine. The badge next to the panel title shows the engine in use, such as "Transcription ready · Cloud". Under "Advanced" you can switch to local only, cloud only, or off.
 
 ## Use it
 
@@ -102,7 +127,7 @@ The text block is structured metadata: each canvas packet reports time, form, an
 Four ways to look, by question:
 
 | Goal | Ask |
-| --- | --- |
+| :--- | :--- |
 | Overview first | "Look at this video" — streaming sampling; motion as process, settle as detail |
 | One exact moment | "What is written at 12.9s" — deterministic high-resolution frame |
 | Even coverage | "One frame every 5 seconds" — uniform sampling |
@@ -112,34 +137,32 @@ Four ways to look, by question:
 
 ### Dual-scale streaming perception
 
-Video is not sampled at a fixed rate. While the picture moves, low-resolution process units (P) record change; when it settles, high-resolution freeze units (F) keep detail. A single canvas packet carries both process and result, so the model does not need to re-watch a clip to recover one detail.
+Sampling is event-driven rather than fixed-rate. During motion, low-resolution process units (P) record state transitions; at settle, high-resolution freeze units (F) preserve detail. Both are delivered within a single canvas packet, so one observation carries the temporal process and the steady-state result together, and the model need not re-watch a clip to recover a detail.
 
-The sampling cadence follows the picture: fast change lowers density to avoid duplicates; slow change waits for a settle before freezing. Long static stretches keep a heartbeat instead of repeating images.
+Density adapts to picture activity: rapid change lowers the sampling rate to suppress redundant frames, while slow change extends the wait until a settle is detected; long static intervals maintain a temporal reference through heartbeats without retransmitting images.
 
 ### Canvas packing and metering
 
-A frame is divided into 42 px superpixel-aligned units. P or F units are taken as needed and packed into one canvas. One call can carry several packets; each packet holds only the units that are new, and older packets collapse into reference hashes instead of resending images. Metering follows the canvas grid (`r × (c + 1) + 2`).
+Each frame is partitioned on a 42 px superpixel grid; P or F units are selected as needed and assembled into a canvas. A call may carry multiple packets, and each packet contains only the units new relative to the previous one; historical packets collapse into content-hash references, keeping context bounded in long sessions. Metering follows canvas grid cells (`r × (c + 1) + 2`).
 
 ### Deterministic inspection
 
-Besides streaming, three paths are deterministic: `probe` reads metadata only; `timestamps` returns exact frames in milliseconds; `uniform` samples at a fixed interval; `roi_hint` crops a region. These do not depend on motion detection, so results are reproducible and suited to reading text, numbers, and small objects.
+Beyond streaming, four deterministic paths are provided: `probe` parses container metadata only; `timestamps` extracts exact frames at millisecond timestamps; `uniform` samples at a fixed interval; `roi_hint` crops and magnifies a normalized region. None depends on motion detection; outputs are reproducible and suited to verifying text, numerals, and small objects.
 
-### Three sources for speech
+### Cascaded speech sources
 
-1. **Subtitles**: a sidecar `.srt` / `.vtt` with the same name first, then embedded soft subtitles.
-2. **Acoustic check**: without subtitles, silence detection and a speech-ratio estimate run first; an all-silent video skips transcription.
-3. **Transcription**: local whisper.cpp, or OpenAI / Groq / a custom compatible endpoint. Segments are mounted on packets by PTS and stitched across block boundaries with a ±300 ms tolerance.
+Speech text is obtained through a three-stage cascade: a sidecar `.srt` / `.vtt` is read first, then embedded soft subtitles; without subtitles, silence detection and a speech-ratio estimate run, and an all-silent video skips transcription; finally ASR runs, either local whisper.cpp or OpenAI / Groq / a custom compatible endpoint. Segments are aligned by PTS and mounted on the corresponding packets, stitched across block boundaries with a ±300 ms tolerance.
 
-The default is "picture first, speech later": when the soft deadline (`graceMs`, 8 s by default) passes, the visual result returns and transcription continues in the background; the next call on the same video hits the disk cache.
+The default policy is vision-first with background transcription: once a call exceeds the soft deadline (`graceMs`, 8 s by default), the visual result returns and transcription continues in the background; later calls on the same video hit the disk cache.
 
-### Old regions
+### Cold regions in long videos
 
-Canvas packets outside the window collapse into references (anchor hash, time, and transcript text) instead of resending images. A timestamp call brings the detail back when needed.
+Historical packets outside the current window collapse into references (anchor hash, time, and transcript text) rather than retransmitting images; a timestamp call restores the detail when needed.
 
 ## Troubleshooting
 
 | Symptom | Read |
-| --- | --- |
+| :--- | :--- |
 | ffmpeg not found | [ffmpeg](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md#找不到-ffmpeg) |
 | Speech but no transcript | [No transcript](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md#有声音但没有台词) |
 | Model download fails or is slow | [Download](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md#下载失败) |
@@ -148,10 +171,12 @@ Canvas packets outside the window collapse into references (anchor hash, time, a
 
 ## Docs
 
-- [Usage Guide](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/usage-guide.md) (English)
-- [使用指南](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/使用指南.md) (Chinese)
-- [排障](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md) (Chinese)
-- [开发者指南](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/开发者指南.md) (Chinese): architecture, host contracts, tests, release
+| Document | Contents |
+| :--- | :--- |
+| [Usage Guide](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/usage-guide.md) | Usage, parameters, output, metering, every config key |
+| [使用指南](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/使用指南.md) | Chinese usage guide |
+| [排障](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md) | Troubleshooting by symptom (Chinese) |
+| [开发者指南](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/开发者指南.md) | Architecture, host contracts, tests, release (Chinese) |
 
 ## Development
 

package/README.md

@@ -1,18 +1,41 @@
-# dsh-pf-stream
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Weilv-D/dsh-pf-stream/main/icon.svg" width="72" height="72" alt="视频理解">
+</p>
 
-**中文** | [English](https://github.com/Weilv-D/dsh-pf-stream/blob/main/README.en.md)
+<h1 align="center">视频理解</h1>
 
-让智能体看懂视频：动态抽帧，加上台词。
+<p align="center">让智能体看懂视频：画面、动作与台词，按时间对齐。</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-pf-stream"><img src="https://img.shields.io/npm/v/dsh-pf-stream?color=2f6feb" alt="npm 版本"></a>
+  <img src="https://img.shields.io/badge/license-Apache--2.0-2ea44f" alt="许可证">
+  <img src="https://img.shields.io/badge/DSH-plugin-6e56cf" alt="DSH 插件">
+</p>
+
+<p align="center"><b>中文</b> · <a href="README.en.md">English</a></p>
+
+---
+
+## 30 秒上手
+
+| 步骤 | 做什么 |
+| :--- | :--- |
+| 1 | 安装 ffmpeg（[命令见下](#1-安装-ffmpeg)），确认 `ffmpeg -version` 有输出 |
+| 2 | 左侧栏「插件」→ 点「视频理解」→ 打开右上角开关 |
+| 3 | 详情页点「下载本地模型」，约 190 MB；完成后点「测试转写」 |
+| 4 | 在对话里给视频路径，直接提问 |
+
+不配置转写也能看画面。只有「没有字幕、又需要台词」的视频，才需要第 3 步。
 
 ## 能做什么
 
 - **看画面**：画面运动时记录过程，停稳时定格细节；指定时间点可以高清复核。
 - **听声音**：有字幕就用字幕；没有字幕时，配置转写引擎后生成台词，并按时间挂到对应画面。
-- **按需配置**：不配置转写也能处理画面；配置后可以处理带音轨的视频。
+- **按需配置**：默认不转写也能处理画面；配置后可以处理带音轨的视频。
 
 ## 安装
 
-### 第一步：安装 ffmpeg
+### 1. 安装 ffmpeg
 
 插件用 ffmpeg 解码视频。先确认它能运行：
 
@@ -24,14 +47,14 @@ ffprobe -version
 两条都要有输出。没有的话：
 
 | 系统 | 安装命令 |
-| --- | --- |
+| :--- | :--- |
 | Windows | `winget install Gyan.FFmpeg` |
 | macOS | `brew install ffmpeg` |
 | Ubuntu / Debian | `sudo apt install ffmpeg` |
 
-装完新开一个终端再验证。不想放进 PATH，可以在插件配置里写 `ffmpegPath` 与 `ffprobePath` 的绝对路径。
+> 装完新开一个终端再验证。不想放进 PATH，可以在插件配置里写 `ffmpegPath` 与 `ffprobePath` 的绝对路径。
 
-### 第二步：在 DSH 里安装插件
+### 2. 在 DSH 里安装插件
 
 1. 打开 DSH，点左侧栏的「插件」。
 2. 在列表里找「视频理解」（包名 `dsh-pf-stream`）。
@@ -56,30 +79,32 @@ ffprobe -version
 
 进入配置页：**左侧栏「插件」→ 点「视频理解」→ 详情页描述下方的面板**。以后要改设置，走同一条路。
 
+<p><img src="https://raw.githubusercontent.com/Weilv-D/dsh-pf-stream/main/docs/assets/panel.png" width="720" alt="插件详情页的转写设置面板：视频解码、本地转写与云端转写三张状态卡"></p>
+
 面板顶部有三张状态卡：视频解码（ffmpeg）、本地转写、云端转写。按需要选一条路线：
 
 | 路线 | 适合 | 操作 |
-| --- | --- | --- |
+| :--- | :--- | :--- |
 | 本地转写（推荐） | 免费、离线、不填密钥 | 点「下载本地模型」，约 190 MB；下载完点「测试转写」 |
 | 云端转写 | 已有 API Key，或机器性能较弱 | 选 OpenAI / Groq / 自定义兼容端点，填 Key，保存后点「测试转写」 |
 | 暂不配置 | 视频都有字幕 | 直接使用；无字幕的语音视频不会生成转写文本 |
 
-本地模型的下载步骤：
+### 本地模型
 
 1. 点「下载本地模型」。进度条显示已下载大小，可随时取消。
 2. 下载中断后再次点击会续传，不用从头开始。
 3. 完成后状态卡显示「已就绪 · whisper.cpp」。
 4. 点「测试转写」。返回「本地引擎可用」即配置成功。
 
-云端密钥的保存步骤：
+一键安装当前支持 Windows x64。其他系统请先安装 whisper.cpp，在配置文件 `audio.asr.local.binPath` 填写可执行文件路径，或改用云端转写。
+
+### 云端密钥
 
 1. 在「云端转写密钥」里选服务商。
 2. 粘贴 API Key，点「保存」。保存后只显示「已配置」，不再回显密钥。
 3. 点「测试转写」验证密钥与网络。
 
-默认策略是 `auto`：云端密钥、端点、模型都齐时用云端（更快，按量计费）；否则用本地引擎。面板标题旁会显示当前实际使用的引擎，如「转写可用 · 云端」。可以在「高级」里改成仅本地、仅云端或不转写。
-
-一键安装当前支持 Windows x64。其他系统请先安装 whisper.cpp，在配置文件 `audio.asr.local.binPath` 填写可执行文件路径，或改用云端转写。
+> **自动策略**：云端密钥、端点、模型都齐时用云端（更快，按量计费）；否则用本地引擎。面板标题旁会显示当前实际使用的引擎，如「转写可用 · 云端」。可以在「高级」里改成仅本地、仅云端或不转写。
 
 ## 开始使用
 
@@ -102,7 +127,7 @@ Audio @Packet #42: [12.1s-12.9s] "这件事我们准备了三年" | [13.0s-13.4s
 常用问法对应四种取帧方式：
 
 | 想要 | 说法 |
-| --- | --- |
+| :--- | :--- |
 | 先看整体 | 「看看这个视频」——流式采样，运动记过程、停稳给细节 |
 | 只看某一秒 | 「第 12.9 秒写了什么」——定点高清帧 |
 | 均匀看一遍 | 「每 5 秒抽一帧」——等间隔抽帧 |
@@ -112,34 +137,32 @@ Audio @Packet #42: [12.1s-12.9s] "这件事我们准备了三年" | [13.0s-13.4s
 
 ### 双尺度流式感知
 
-视频不再平均抽帧。画面运动时，插件用低分辨率的过程单元（P）记录变化；画面停稳后，用高分辨率的定格单元（F）保留细节。同一个画布包里既有过程也有结果，模型不用为了一个细节反复回看整段视频。
+采样过程不再采用固定帧率，而由画面变化事件驱动：运动阶段以低分辨率过程单元（P）记录状态转移，停稳后以高分辨率定格单元（F）保留细节；两类单元在同一画布包内交付，使单次观测同时包含时序过程与稳态结果，模型无需为恢复某一细节而回看整段视频。
 
-采样节奏由画面变化驱动：变化快时降低采样密度、避免重复帧；变化慢时等待停稳再定格。长静止画面用心跳保持时间感，不重复发图。
+采样密度随画面活动度自适应调整：快速变化时降低采样率以抑制冗余帧，缓慢变化时延长等待直至检测到停稳；长静止区间以心跳信号维持时间基准，不重复传输图像。
 
 ### 画布打包与计费
 
-一帧画面被切成 42px 超像素对齐的单元，按需取 P 或 F，再拼成一张画布。一次调用可以带多个画布包；每个包只包含当前新增的单元，历史包以引用哈希折叠，不重复传图。计费按画布网格计算（`r × (c + 1) + 2`）。
+每帧按 42 px 超像素网格切分为单元，按需选取 P 或 F 单元并拼装为画布。单次调用可携带多个画布包；每个包仅包含相对上一包新增的单元，历史包以内容哈希引用折叠，使长会话中的上下文规模保持有界。计费按画布网格单元数计算（`r × (c + 1) + 2`）。
 
 ### 确定性检视
 
-流式采样之外，另外三条路径是确定性的：`probe` 只读元数据；`timestamps` 按毫秒取指定帧；`uniform` 按固定间隔取帧；`roi_hint` 裁剪指定区域。这几种不依赖运动检测，结果可复现，适合核对文字、数字与小目标。
+流式采样之外另设四条确定性路径：`probe` 仅解析容器元数据；`timestamps` 按毫秒级时间戳抽取精确帧；`uniform` 以固定间隔均匀采样；`roi_hint` 对指定归一化区域裁剪放大。上述路径不依赖运动检测，输出可复现，适用于文字、数字与小目标的核对。
 
-### 台词的三级来源
+### 台词的级联来源
 
-1. **字幕**：优先用外挂同名 `.srt` / `.vtt`，其次内嵌软字幕。
-2. **声学判断**：没有字幕时先做静音检测与语音占比估计；全程静音的视频直接跳过转写。
-3. **语音转写**：本地 whisper.cpp，或 OpenAI / Groq / 自定义兼容端点。转写结果按 PTS 挂到对应画布包，跨块边界按 ±300ms 缝合。
+转写文本按三级级联获取：优先读取同名外挂 `.srt` / `.vtt`，其次解析内嵌软字幕；无字幕时执行静音检测与语音占比估计，全静音视频直接跳过转写；最后调用语音识别，可选本地 whisper.cpp 或 OpenAI / Groq / 自定义兼容端点。识别结果按 PTS 对齐并挂载至相应画布包，跨块边界以 ±300 ms 容差缝合。
 
-默认「先回画面、后台补台词」：首次调用超过软截止（`graceMs`，默认 8 秒）就先返回视觉结果，转写在后台继续；同一视频再调用时直接命中磁盘缓存。
+默认策略为「视觉先行、转写后台补齐」：首次调用超过软截止（`graceMs`，默认 8 s）时先行返回视觉结果，转写任务在后台继续；同一视频的后续调用直接命中磁盘缓存。
 
 ### 长视频的冷区
 
-超出窗口的历史画布包会折叠成引用（锚点哈希 + 时间 + 台词文本），不重复传图。需要回看时再按时间点取帧。
+超出当前窗口的历史画布包折叠为引用（锚点哈希、时间与台词文本），不再重复传输图像；需要复核时按时间戳重新取帧。
 
 ## 遇到问题
 
 | 现象 | 先看这里 |
-| --- | --- |
+| :--- | :--- |
 | 提示找不到 ffmpeg | [排障：ffmpeg](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md#找不到-ffmpeg) |
 | 有声音，但没有台词 | [排障：没有台词](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md#有声音但没有台词) |
 | 下载模型失败或很慢 | [排障：下载失败](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md#下载失败) |
@@ -148,10 +171,12 @@ Audio @Packet #42: [12.1s-12.9s] "这件事我们准备了三年" | [13.0s-13.4s
 
 ## 文档
 
-- [使用指南](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/使用指南.md)：用法、参数、返回内容、计费、全部配置项
-- [排障](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md)：按现象查原因
-- [开发者指南](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/开发者指南.md)：架构、宿主契约、测试与发布
-- [Usage Guide](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/usage-guide.md)（English）
+| 文档 | 内容 |
+| :--- | :--- |
+| [使用指南](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/使用指南.md) | 用法、参数、返回内容、计费、全部配置项 |
+| [排障](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/排障.md) | 按现象查原因 |
+| [开发者指南](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/开发者指南.md) | 架构、宿主契约、测试与发布 |
+| [Usage Guide](https://github.com/Weilv-D/dsh-pf-stream/blob/main/docs/usage-guide.md) | 英文使用指南 |
 
 ## 本地开发
 

package/client.js

@@ -23,6 +23,8 @@ window.__ModuleLoader__.load({
       panelSubtitle:
         '以下设置用于启用语音识别与转写。未配置时不影响视频播放，但不会生成转写文本；完成配置后，可对含有效音轨的视频进行转写。',
       refresh: '刷新',
+      github: '在 GitHub 上点个 Star',
+      githubAria: '在 GitHub 上打开项目仓库',
       checking: '正在读取状态…',
       ffmpeg: '视频解码',
       ffmpegOk: '已就绪',
@@ -89,6 +91,17 @@ window.__ModuleLoader__.load({
       loadFailed: '读取状态失败',
       installStarted: '下载已开始',
       waitDownload: '下载在后台进行，画面处理照常。',
+      engineLegacy: '旧版 provider 直连（0.2.x 配置）',
+      presetCustom: '自定义 OpenAI 兼容端点',
+      errInvalidField: '字段值不合法，请检查输入',
+      errJsonRequired: '请求必须是 JSON 格式',
+      errCrossOrigin: '跨站请求被拒绝',
+      errCredentialRejected: '凭据服务拒绝',
+      errKeyTooLong: '密钥过长',
+      errUnknownPreset: '未知服务商',
+      errNotFound: '接口不存在',
+      errMethodNotAllowed: '请求方法不被允许',
+      errInternal: '服务内部错误',
     };
 
     const EN = {
@@ -96,6 +109,8 @@ window.__ModuleLoader__.load({
       panelSubtitle:
         'These settings enable speech recognition and transcription. Without them, video playback is unaffected, but no transcript is generated. Once configured, videos with a usable audio track can be transcribed.',
       refresh: 'Refresh',
+      github: 'Star this project on GitHub',
+      githubAria: 'Open the project repository on GitHub',
       checking: 'Reading status…',
       ffmpeg: 'Video decoding',
       ffmpegOk: 'Ready',
@@ -162,6 +177,17 @@ window.__ModuleLoader__.load({
       loadFailed: 'Failed to read status',
       installStarted: 'Download started',
       waitDownload: 'The download runs in the background; video processing continues.',
+      engineLegacy: 'Legacy provider passthrough (0.2.x config)',
+      presetCustom: 'Custom OpenAI-compatible endpoint',
+      errInvalidField: 'Invalid field value; check the input',
+      errJsonRequired: 'The request must be JSON',
+      errCrossOrigin: 'Cross-origin request rejected',
+      errCredentialRejected: 'Credential store rejected the request',
+      errKeyTooLong: 'The key is too long',
+      errUnknownPreset: 'Unknown provider',
+      errNotFound: 'Endpoint not found',
+      errMethodNotAllowed: 'HTTP method not allowed',
+      errInternal: 'Internal server error',
     };
 
     function detectLang() {
@@ -172,6 +198,29 @@ window.__ModuleLoader__.load({
       }
     }
 
+    /** 服务端错误码 → 词典键（call() 抛出的 error.code；未知码回退原始消息）。 */
+    const ERROR_KEYS = {
+      invalid_field: 'errInvalidField',
+      json_required: 'errJsonRequired',
+      cross_origin: 'errCrossOrigin',
+      credential_rejected: 'errCredentialRejected',
+      key_too_long: 'errKeyTooLong',
+      unknown_preset: 'errUnknownPreset',
+      not_found: 'errNotFound',
+      method_not_allowed: 'errMethodNotAllowed',
+      internal_error: 'errInternal',
+    };
+
+    function translateError(t, cause) {
+      const code = cause && cause.code;
+      const key = ERROR_KEYS[code];
+      if (!key) return cause instanceof Error ? cause.message : String(cause);
+      const prefix = t(key);
+      // credential_rejected 服务端附带原因：拼在翻译后
+      const detail = cause instanceof Error ? cause.message : String(cause);
+      return code === 'credential_rejected' && detail ? prefix + '：' + detail : prefix;
+    }
+
     function makeTranslator(locale) {
       const lang = detectLang();
       const own = lang === 'zh' ? ZH : EN;
@@ -298,6 +347,21 @@ window.__ModuleLoader__.load({
         lineHeight: 1.2,
         whiteSpace: 'nowrap',
       },
+      iconButton: {
+        appearance: 'none',
+        border: '.5px solid ' + PALETTE.hairline,
+        background: PALETTE.glassStrong,
+        color: PALETTE.sub,
+        borderRadius: 9,
+        width: 30,
+        height: 30,
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        cursor: 'pointer',
+        textDecoration: 'none',
+        flex: 'none',
+      },
       primary: {
         appearance: 'none',
         border: '.5px solid color-mix(in srgb, var(--dsw-alias-brand-primary) 45%, transparent)',
@@ -610,9 +674,13 @@ window.__ModuleLoader__.load({
     function useStatus() {
       const [status, setStatus] = React.useState(null);
       const [error, setError] = React.useState('');
+      // 安装相位经 ref 传递：tick 闭包不能读 state（闭包捕获的是挂载帧的 null，
+      // 曾使安装期间的 1s 快刷永不生效）
+      const installPhaseRef = React.useRef(null);
       const load = React.useCallback(async function () {
         try {
           const data = await call('/status');
+          installPhaseRef.current = data && data.install ? data.install.phase : null;
           setStatus(data);
           setError('');
         } catch (cause) {
@@ -626,8 +694,8 @@ window.__ModuleLoader__.load({
           if (!alive) return;
           await load();
           if (!alive) return;
-          const busy = status && status.install &&
-            ['preparing', 'downloading', 'verifying', 'extracting'].indexOf(status.install.phase) >= 0;
+          const phase = installPhaseRef.current;
+          const busy = phase && ['preparing', 'downloading', 'verifying', 'extracting'].indexOf(phase) >= 0;
           timer = setTimeout(tick, busy ? 1000 : 6000);
         }
         void tick();
@@ -654,8 +722,11 @@ window.__ModuleLoader__.load({
 
       React.useEffect(function () {
         if (!status) return;
-        setCustomBase(status.cloud.baseUrl || '');
-        setCustomModel(status.cloud.model || '');
+        // 回填仅覆盖未被聚焦编辑的输入（请求在途时用户已开始输入的场景）
+        const active = typeof document !== 'undefined' && document.activeElement;
+        const activeField = active && active.getAttribute ? active.getAttribute('data-field') : null;
+        if (activeField !== 'baseUrl') setCustomBase(status.cloud.baseUrl || '');
+        if (activeField !== 'model') setCustomModel(status.cloud.model || '');
       }, [status && status.cloud && status.cloud.preset]);
 
       function run(name, action) {
@@ -669,7 +740,7 @@ window.__ModuleLoader__.load({
             return state.reload();
           })
           .catch(function (cause) {
-            setFailure(cause instanceof Error ? cause.message : String(cause));
+            setFailure(translateError(t, cause));
           })
           .then(function () {
             setBusy('');
@@ -687,12 +758,16 @@ window.__ModuleLoader__.load({
       const ffmpeg = status.ffmpeg || {};
       const localReady = status.engine && status.engine.ready;
       const cloudReady = status.cloud && status.cloud.keyConfigured && status.cloud.baseUrl && status.cloud.model;
-      const ready = ffmpeg.available && (localReady || cloudReady);
+      // 徽标口径取服务端权威结论（engine=off / audio.mode=off 时 ready=false），
+      // 本地自算会出现「转写可用 · 未启用」的自相矛盾徽标
+      const ready = status.ready === true;
       const job = status.install;
       const installing =
         job && ['preparing', 'downloading', 'verifying', 'extracting'].indexOf(job.phase) >= 0;
       const preset = status.cloud.preset;
       const custom = status.cloud.editable;
+      const presetInfo = (status.presets || []).find(function (item) { return item.id === preset; });
+      const keyUrl = presetInfo ? presetInfo.keyUrl : '';
       const activeKind = status.active
         ? status.active.kind
         : status.mode === 'local'
@@ -712,6 +787,7 @@ window.__ModuleLoader__.load({
         ['local', t('engineLocal')],
         ['cloud', t('engineCloud')],
         ['off', t('engineOff')],
+        ['legacy', t('engineLegacy')],
       ];
 
       return h(
@@ -723,6 +799,24 @@ window.__ModuleLoader__.load({
           h('h3', { style: styles.title }, t('panelTitle')),
           h('span', { style: styles.badge }, ready ? t('badgeReady') + ' · ' + activeLabel : t('badgePending')),
           h('span', { style: { flex: '1 1 auto' } }),
+          h(
+            'a',
+            {
+              href: 'https://github.com/Weilv-D/dsh-pf-stream',
+              target: '_blank',
+              rel: 'noreferrer',
+              title: t('github'),
+              'aria-label': t('githubAria'),
+              style: styles.iconButton,
+            },
+            h(
+              'svg',
+              { viewBox: '0 0 16 16', width: 16, height: 16, fill: 'currentColor', 'aria-hidden': 'true' },
+              h('path', {
+                d: 'M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z',
+              }),
+            ),
+          ),
           h(
             'button',
             { type: 'button', style: styles.button, onClick: function () { void state.reload(); } },
@@ -825,9 +919,16 @@ window.__ModuleLoader__.load({
               h(SelectField, {
                 value: preset,
                 options: (status.presets || []).map(function (item) {
-                  return { value: item.id, label: item.label };
+                  // custom 的服务端 label 是中文兜底，英文界面走本地词典
+                  return {
+                    value: item.id,
+                    label: item.id === 'custom' ? t('presetCustom') : item.label,
+                  };
                 }),
                 onChange: function (value) {
+                  // 切换服务商时清空未保存的密钥草稿：
+                  // 密钥按服务商独立存储（keyRef 各自独立），跨服务商误存会双向错乱
+                  setKeyDraft('');
                   void run('preset', function () {
                     return call('/config', { field: 'preset', value: value });
                   });
@@ -841,6 +942,7 @@ window.__ModuleLoader__.load({
                     style: styles.input,
                     value: customBase,
                     placeholder: 'https://api.example.com',
+                    'data-field': 'baseUrl',
                     onChange: function (event) { setCustomBase(event.target.value); },
                     onBlur: function () {
                       void run('baseUrl', function () {
@@ -857,6 +959,7 @@ window.__ModuleLoader__.load({
                     style: styles.input,
                     value: customModel,
                     placeholder: 'whisper-1',
+                    'data-field': 'model',
                     onChange: function (event) { setCustomModel(event.target.value); },
                     onBlur: function () {
                       void run('model', function () {
@@ -918,9 +1021,9 @@ window.__ModuleLoader__.load({
               },
               t('clear'),
             ),
-            status.cloud.keyUrl
+            keyUrl
               ? h('a', {
-                  href: status.cloud.keyUrl,
+                  href: keyUrl,
                   target: '_blank',
                   rel: 'noreferrer',
                   style: { fontSize: 12, color: PALETTE.brand, textDecoration: 'none', paddingBottom: 8 },
@@ -961,6 +1064,7 @@ window.__ModuleLoader__.load({
               h('input', {
                 style: styles.input,
                 defaultValue: (status.config && status.config.language) || '',
+                key: 'language-' + ((status.config && status.config.language) || ''),
                 placeholder: t('languageAuto'),
                 onBlur: function (event) {
                   const value = event.target.value;
@@ -993,7 +1097,8 @@ window.__ModuleLoader__.load({
                 style: styles.input,
                 type: 'number',
                 min: 0,
-                max: 32,
+                max: 16,
+                key: 'threads-' + ((status.config && status.config.threads) || 0),
                 defaultValue: (status.config && status.config.threads) || 0,
                 onBlur: function (event) {
                   const value = Number(event.target.value || 0);

package/lib/asr/catalog.js

@@ -139,8 +139,8 @@ export function buildLocalArgs(engine, ctx) {
             return [
                 '--model',
                 ctx.modelName,
-                '--language',
-                lang === 'auto' ? 'auto' : lang,
+                // Python 系 CLI 的 --language 不接受 'auto' 字面量：省略即自动检测
+                ...(lang === 'auto' ? [] : ['--language', lang]),
                 '--task',
                 'transcribe',
                 '--output_format',
@@ -156,8 +156,7 @@ export function buildLocalArgs(engine, ctx) {
             return [
                 '--model',
                 ctx.modelName,
-                '--language',
-                lang,
+                ...(lang === 'auto' ? [] : ['--language', lang]),
                 '--output_format',
                 'srt',
                 '--output_dir',