dsh-voice 0.5.11 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +10 -0
- package/README.en.md +28 -25
- package/README.md +28 -25
- package/docs/USAGE.en.md +73 -67
- package/docs/USAGE.md +72 -66
- package/lib/host-config.d.ts +111 -0
- package/lib/host-config.js +497 -0
- package/lib/index.d.ts +2 -0
- package/lib/index.js +16 -9
- package/lib/stt.js +3 -3
- package/lib/tools.d.ts +2 -2
- package/lib/tools.js +34 -20
- package/lib/update-client.js +145 -53
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# 更新记录
|
|
2
2
|
|
|
3
|
+
## 0.6.1 (2026-11-18)
|
|
4
|
+
|
|
5
|
+
- 同步 `@stardustlc/dsh-updates` 0.2.3:侧边栏工作台平时默认隐藏底部更新栏(零高度占用),仅在检测到兼容新版本或执行更新时浮现单行精简提示条;完整更新设置与检查入口统一保留在 DSH「插件」详情页底部。
|
|
6
|
+
- Sync `@stardustlc/dsh-updates` 0.2.3: keep the sidebar workbench update footer hidden by default when up-to-date, surfacing a single-line compact strip only for actionable updates or active jobs while retaining full controls in native Plugin Details.
|
|
7
|
+
|
|
8
|
+
## 0.6.0 (2026-11-18)
|
|
9
|
+
|
|
10
|
+
- 新增零外部依赖的宿主原生 `Config` 设置表单声明(`asrApiKey` 与 `proxyUrl` 自动脱敏并支持热更新生效),明确配音免密钥开箱即用与转写配置指引,并补齐日常配音/会议纪要使用流程。
|
|
11
|
+
- Export a zero-dependency native DSH `Config` schema with secret masking and live reload across all 10 voice/ASR settings, clearer zero-key TTS vs. ASR setup hints, and human-centric workflow docs.
|
|
12
|
+
|
|
3
13
|
## 0.5.11 (2026-11-18)
|
|
4
14
|
|
|
5
15
|
- 更新区底部新增克制、无打扰的 GitHub 点赞与问题反馈快捷链接,并完善中英文检索关键词。
|
package/README.en.md
CHANGED
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
# Voice
|
|
4
4
|
|
|
5
|
-
**Turn text into speech and recordings into
|
|
5
|
+
**Turn text into natural speech and recordings into clean transcripts.**
|
|
6
6
|
|
|
7
|
-
Voice plugin for DeepSeek Harness (`>=0.2.2-rc.3`): provides
|
|
7
|
+
Voice plugin for DeepSeek Harness (`>=0.2.2-rc.3`): provides zero-key Edge neural text-to-speech (TTS), batch voice previews, native live Settings forms with secret masking, and OpenAI/Groq-compatible speech-to-text (STT) strictly scoped to your session workspace.
|
|
8
8
|
|
|
9
9
|
[](https://www.npmjs.com/package/dsh-voice) [](https://www.npmjs.com/package/dsh-voice) [](https://www.npmjs.com/package/dsh-voice)
|
|
10
10
|
|
|
11
|
-
**[Install](#install) · [
|
|
11
|
+
**[Install](#install) · [Get Started in 3 Steps](#get-started-in-3-steps) · [Full Guide](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/USAGE.en.md)**
|
|
12
12
|
|
|
13
13
|
<picture>
|
|
14
14
|
<source media="(prefers-color-scheme: dark) and (max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/dsh-voice/master/docs/assets/intro/workflow-en-mobile-dark.svg">
|
|
@@ -17,52 +17,55 @@ Voice plugin for DeepSeek Harness (`>=0.2.2-rc.3`): provides keyless Edge neural
|
|
|
17
17
|
<img src="https://raw.githubusercontent.com/STARDUSTLC666/dsh-voice/master/docs/assets/intro/workflow-en-light.svg" alt="Turn text into speech and recordings into text. · workflow illustration" width="100%">
|
|
18
18
|
</picture>
|
|
19
19
|
|
|
20
|
-
## Features
|
|
21
|
-
|
|
22
|
-
- Choose a voice and speed with a short sample.
|
|
23
|
-
- Keep audio files you can play or deliver.
|
|
24
|
-
- Transcribe with your configured compatible ASR service.
|
|
25
|
-
|
|
26
20
|
## Install
|
|
27
21
|
|
|
28
|
-
Open **Plugins** in the DSH desktop app and install `dsh-voice
|
|
22
|
+
Open **Plugins** in the DSH desktop app and install `dsh-voice`, or use the CLI:
|
|
29
23
|
|
|
30
24
|
```bash
|
|
31
25
|
dsh plugin --profile desktop add dsh-voice
|
|
32
26
|
```
|
|
33
27
|
|
|
34
|
-
For the web profile, replace `desktop` with `web`. Restart
|
|
35
|
-
|
|
36
|
-
## Start using it
|
|
28
|
+
For the web profile, replace `desktop` with `web`. Restart DSH once after installing. Requires DSH `>=0.2.2-rc.3`.
|
|
37
29
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
3. Listen to the sample, generate the complete audio, then play or deliver the returned file.
|
|
41
|
-
4. For transcription, configure your own compatible ASR service, provide a local audio file, then review the transcript.
|
|
30
|
+
<a id="start-using-it"></a>
|
|
31
|
+
## Get Started in 3 Steps
|
|
42
32
|
|
|
43
|
-
|
|
33
|
+
1. **Read-aloud works out of the box (zero API keys)**: Open a DSH session in your target workspace and ask the assistant to preview voices or turn any script into an MP3 immediately.
|
|
34
|
+
2. **Add an ASR key when you need transcription (applies live)**: Open **DSH Settings → Plugins → Voice (`dsh-voice`)** and enter your Groq or OpenAI-compatible `asrApiKey` (masked and applied immediately without restarting; `DSH_VOICE_ASR_KEY` env var is also supported).
|
|
35
|
+
3. **Preview, synthesize, or transcribe inside your workspace**: Place recordings inside your session workspace; generated MP3s and `.txt` transcripts stay safely inside the workspace and auto-number instead of overwriting existing files.
|
|
44
36
|
|
|
45
|
-
|
|
37
|
+
## Copy-Ready Prompts for Everyday Work
|
|
46
38
|
|
|
47
|
-
|
|
39
|
+
- **Audition 3 voices first, then synthesize the full audio (zero config)**
|
|
40
|
+
> Generate short voice preview samples for 3 natural narration voices so I can listen first, then synthesize the full MP3 once I pick one.
|
|
41
|
+
- **Turn a written briefing into a ready-to-play MP3**
|
|
42
|
+
> Condense today's notes into a 2-minute spoken script and generate `morning-brief.mp3` at `+10%` speed.
|
|
43
|
+
- **Transcribe a meeting recording & extract action items**
|
|
44
|
+
> Transcribe `meeting.m4a` in this workspace, save the full transcript to `meeting.txt`, and list the action items.
|
|
48
45
|
|
|
49
|
-
|
|
46
|
+
## Quick Troubleshooting Checklist
|
|
50
47
|
|
|
51
|
-
|
|
48
|
+
| Symptom | Likely Cause | Fix |
|
|
49
|
+
| :--- | :--- | :--- |
|
|
50
|
+
| Health check says `asrApiKey` is missing, but you only want TTS | ASR key is only needed for audio-to-text transcription | **Keep using TTS directly** — no key is required for speech synthesis or previews |
|
|
51
|
+
| "Must stay inside the session workspace" error | Recording or output path points outside the workspace folder | Copy the audio file into the current DSH workspace folder first |
|
|
52
|
+
| Network / connection error | Corporate firewall or proxy required to reach Edge TTS / ASR | Set `proxyUrl` (e.g. `http://127.0.0.1:7890`) in **DSH Settings → Plugins → Voice** (applies live) |
|
|
53
|
+
| Audio exceeds 25 MB limit | Standard Whisper/ASR upload limit is 25 MB | Compress or split the audio with `dsh-ffmpeg` first, then transcribe |
|
|
52
54
|
|
|
53
55
|
## Plugin updates
|
|
54
56
|
|
|
55
|
-
Check updates at the bottom of
|
|
57
|
+
Check updates at the bottom of native plugin details. Automatic checks are on by default; **automatic installation is off**. Suite-managed components update with their bundle.
|
|
56
58
|
|
|
57
59
|
## Documentation
|
|
58
60
|
|
|
59
|
-
- [
|
|
61
|
+
- [Usage guide and configuration reference](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/USAGE.en.md)
|
|
62
|
+
- [Full reference](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.en.md)
|
|
60
63
|
- [Release notes](https://github.com/STARDUSTLC666/dsh-voice/blob/master/CHANGELOG.md)
|
|
61
64
|
- [Validation scope and history](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/VALIDATION.md)
|
|
62
65
|
|
|
63
66
|
## Feedback and contributions
|
|
64
67
|
|
|
65
|
-
If the plugin helps, a Star makes it easier for others to discover. Report
|
|
68
|
+
If the plugin helps, a Star makes it easier for others to discover. Report issues in [Issues](https://github.com/STARDUSTLC666/dsh-voice/issues) or open [PRs](https://github.com/STARDUSTLC666/dsh-voice/pulls) (please strip credentials).
|
|
66
69
|
|
|
67
70
|
## License
|
|
68
71
|
|
package/README.md
CHANGED
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
# Voice
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**把文字变成自然人声,把会议录音转成干净文字。**
|
|
6
6
|
|
|
7
|
-
DeepSeek Harness(`>=0.2.2-rc.3
|
|
7
|
+
DeepSeek Harness(`>=0.2.2-rc.3`)语音插件:内置零密钥 Edge 神经网络语音合成(TTS)与短试听音色挑选,支持原生设置表单与热生效、OpenAI / Groq 兼容语音转文字(STT),并严格将读写限制在当前会话工作区内。
|
|
8
8
|
|
|
9
9
|
[](https://www.npmjs.com/package/dsh-voice) [](https://www.npmjs.com/package/dsh-voice) [](https://www.npmjs.com/package/dsh-voice)
|
|
10
10
|
|
|
11
|
-
**[安装使用](#安装) · [
|
|
11
|
+
**[安装使用](#安装) · [最快 3 步用起来](#最快-3-步用起来) · [完整说明](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/USAGE.md)**
|
|
12
12
|
|
|
13
13
|
<picture>
|
|
14
14
|
<source media="(prefers-color-scheme: dark) and (max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/dsh-voice/master/docs/assets/intro/workflow-zh-mobile-dark.svg">
|
|
@@ -17,52 +17,55 @@ DeepSeek Harness(`>=0.2.2-rc.3`)语音插件:提供零密钥 Edge 神经
|
|
|
17
17
|
<img src="https://raw.githubusercontent.com/STARDUSTLC666/dsh-voice/master/docs/assets/intro/workflow-zh-light.svg" alt="把文字变成声音,把录音变成文字。 · 流程示意" width="100%">
|
|
18
18
|
</picture>
|
|
19
19
|
|
|
20
|
-
## 功能
|
|
21
|
-
|
|
22
|
-
- 短试听后再决定音色与语速。
|
|
23
|
-
- 保留可直接播放和交付的音频文件。
|
|
24
|
-
- 转写使用你配置的兼容 ASR 服务。
|
|
25
|
-
|
|
26
20
|
## 安装
|
|
27
21
|
|
|
28
|
-
在 DSH
|
|
22
|
+
在 DSH 桌面版「插件」面板搜索安装 `dsh-voice`,或使用命令行:
|
|
29
23
|
|
|
30
24
|
```bash
|
|
31
25
|
dsh plugin --profile desktop add dsh-voice
|
|
32
26
|
```
|
|
33
27
|
|
|
34
|
-
网页版把 `desktop` 改为 `web
|
|
35
|
-
|
|
36
|
-
## 开始使用
|
|
28
|
+
网页版把 `desktop` 改为 `web`;安装后重启一次 DSH。宿主要求 `>=0.2.2-rc.3`。
|
|
37
29
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
3. 试听后再生成完整音频,按工具返回的文件路径播放或交付。
|
|
41
|
-
4. 需要转写时先配置自己的兼容 ASR 服务,再提供本地音频文件;核对转写结果后使用。
|
|
30
|
+
<a id="开始使用"></a>
|
|
31
|
+
## 最快 3 步用起来
|
|
42
32
|
|
|
43
|
-
|
|
33
|
+
1. **文字转语音开箱即用(零 API 密钥)**:装好插件后无需填任何密钥,直接在工作区新建会话,就能让助手试听多种音色并把文章、播客稿或早报合成 MP3。
|
|
34
|
+
2. **录音转文字按需填密钥(保存即生效)**:需要把录音转文字时,打开 DSH「**设置 → 插件 → 语音(dsh-voice)**」填入 Groq 或 OpenAI 兼容的 `asrApiKey`(自动脱敏、保存即生效;也支持环境变量 `DSH_VOICE_ASR_KEY`)。
|
|
35
|
+
3. **试听选声 → 合成或转写交付**:把待转写录音放到当前会话工作区,合成出的 MP3 或 `.txt` 纪要也会安全落在工作区且同名自动编号不误盖。
|
|
44
36
|
|
|
45
|
-
|
|
37
|
+
## 平时怎么对助手说(可直接复制的自然语言示例)
|
|
46
38
|
|
|
47
|
-
|
|
39
|
+
- **先生成短试听挑音色,再合成完整配音(零配置)**
|
|
40
|
+
> 挑 3 个适合播客的中英文音色给我生成短试听样例,等我选好后再把这篇早报稿合成完整 MP3。
|
|
41
|
+
- **一步把总结变成可带走听的语音早报**
|
|
42
|
+
> 把今天的重点文档浓缩成 300 字口播稿,用温和自然的中文男声(语速 +10%)生成 `morning-brief.mp3`。
|
|
43
|
+
- **把工作区里的会议录音转成文字并提炼纪要**
|
|
44
|
+
> 把当前目录里的 `meeting.m4a` 转写成中文,原稿存到 `meeting.txt`,再帮我整理一份待办事项清单。
|
|
48
45
|
|
|
49
|
-
|
|
46
|
+
## 常见卡点自检
|
|
50
47
|
|
|
51
|
-
|
|
48
|
+
| 遇到的现象 | 10 秒定位原因 | 怎么修 |
|
|
49
|
+
| :--- | :--- | :--- |
|
|
50
|
+
| 自检提示「缺 ASR 密钥」但只想做朗读配音 | ASR 密钥仅录音转文字需要,不影响朗读 | **直接正常合成语音即可**;日后需要转写录音再去「设置 → 插件 → 语音」补填 `asrApiKey` |
|
|
51
|
+
| 提示「必须位于会话工作区内」 | 录音或输出路径指到了工作区文件夹外面 | 先把音频复制进当前会话工作区文件夹再让助手转写 |
|
|
52
|
+
| 合成或转写报网络连接失败 | 受限网络无法直连在线语音 / ASR 服务 | 在 DSH「设置 → 插件 → 语音」填入本地 HTTP 代理 `proxyUrl`(如 `http://127.0.0.1:7890`,保存即生效) |
|
|
53
|
+
| 音频超过 25MB 无法转写 | 在线 ASR 接口单文件体积上限为 25MB | 先让助手用 `dsh-ffmpeg` 压缩码率或按时间切段后再转写 |
|
|
52
54
|
|
|
53
55
|
## 插件更新
|
|
54
56
|
|
|
55
|
-
|
|
57
|
+
在原生插件详情页底部检查更新。默认自动检查,**默认不自动安装**;是否安装、何时重启由你决定。Suite 管理的组件随整包更新。
|
|
56
58
|
|
|
57
59
|
## 文档
|
|
58
60
|
|
|
59
|
-
- [
|
|
61
|
+
- [使用说明与参数参考](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/USAGE.md)
|
|
62
|
+
- [详细参考说明](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.zh.md)
|
|
60
63
|
- [更新记录](https://github.com/STARDUSTLC666/dsh-voice/blob/master/CHANGELOG.md)
|
|
61
64
|
- [验证范围与历史](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/VALIDATION.md)
|
|
62
65
|
|
|
63
66
|
## 反馈与贡献
|
|
64
67
|
|
|
65
|
-
如果插件帮到了你,欢迎 Star
|
|
68
|
+
如果插件帮到了你,欢迎 Star。问题和建议请提交 [Issues](https://github.com/STARDUSTLC666/dsh-voice/issues),也欢迎 [PR](https://github.com/STARDUSTLC666/dsh-voice/pulls)(反馈时请移除凭据)。
|
|
66
69
|
|
|
67
70
|
## License
|
|
68
71
|
|
package/docs/USAGE.en.md
CHANGED
|
@@ -1,94 +1,100 @@
|
|
|
1
|
-
# dsh-voice
|
|
1
|
+
# dsh-voice Usage Guide
|
|
2
2
|
|
|
3
3
|
[Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Get Started in 3 Steps
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
### Step 1: Know What Works Out of the Box vs. Optional ASR Setup
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
- **Text-to-speech (`voice_tts`, `voice_list`, `voice_preview`) works with zero config**: No API keys needed — install the plugin and synthesize speech or audition voices right away.
|
|
10
|
+
- **Speech-to-text (`voice_stt`) needs an ASR key when you want transcription**:
|
|
11
|
+
- **Recommended**: Open **DSH → Settings → Plugins → Voice (`dsh-voice`)**, pick `asrEngine` (`groq` by default, `openai`, or `custom`), and paste `asrApiKey` (masked and **applied live on save without restarting**);
|
|
12
|
+
- **CLI / Environment variable**: Set `DSH_VOICE_ASR_KEY` or configure `cordis.patch.yml`:
|
|
10
13
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
14
|
+
```yaml
|
|
15
|
+
- id: voice
|
|
16
|
+
name: 'dsh-voice'
|
|
17
|
+
config:
|
|
18
|
+
ttsVoice: zh-CN-XiaoxiaoNeural # default voice (applies live)
|
|
19
|
+
ttsRate: '+0%' # default speech rate, e.g. +15% or -10%
|
|
20
|
+
ttsPitch: '+0Hz' # default pitch, e.g. +2Hz or -1Hz
|
|
21
|
+
asrEngine: groq # groq | openai | custom
|
|
22
|
+
asrModel: whisper-large-v3-turbo # optional; defaults to engine preset
|
|
23
|
+
# asrApiKey: gsk_... # prefer DSH Settings or env var DSH_VOICE_ASR_KEY
|
|
24
|
+
# proxyUrl: http://127.0.0.1:7890 # optional HTTP(S) proxy URL
|
|
15
25
|
```
|
|
16
26
|
|
|
17
|
-
|
|
27
|
+
### Step 2: Keep Audio & Outputs Inside Your Session Workspace
|
|
18
28
|
|
|
19
|
-
|
|
20
|
-
dsh plugin --profile web remove dsh-voice
|
|
21
|
-
```
|
|
29
|
+
All input audio and output MP3 / `.txt` files must resolve under the active DSH session workspace (`session.header.cwd`) to protect host files. Copy outside recordings into the workspace first.
|
|
22
30
|
|
|
23
|
-
|
|
31
|
+
### Step 3: Audition Voices, Then Synthesize or Transcribe
|
|
24
32
|
|
|
25
|
-
|
|
33
|
+
Unsure which voice fits best? Ask the assistant to generate short preview samples in parallel before rendering your full script.
|
|
26
34
|
|
|
27
|
-
|
|
35
|
+
---
|
|
28
36
|
|
|
29
|
-
|
|
30
|
-
- id: voice
|
|
31
|
-
name: 'dsh-voice'
|
|
32
|
-
config:
|
|
33
|
-
asrEngine: groq # groq | openai | custom
|
|
34
|
-
asrModel: whisper-large-v3-turbo # Groq whisper model
|
|
35
|
-
# asrApiKey: gsk_... # prefer env var DSH_VOICE_ASR_KEY
|
|
36
|
-
ttsVoice: zh-CN-XiaoxiaoNeural # default voice
|
|
37
|
-
# proxyUrl: http://127.0.0.1:7890 # enable when the ASR endpoint needs a special proxy
|
|
38
|
-
```
|
|
37
|
+
## Copy-Ready Prompts for Everyday Work
|
|
39
38
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
voice_tts { text: hello, voice: en-US-AriaNeural } # English female voice
|
|
55
|
-
voice_stt { audio: meeting.mp3, language: zh } # transcribe a recording inside the session workspace
|
|
56
|
-
voice_list {}
|
|
57
|
-
voice_preview { voices: [zh-CN-XiaoxiaoNeural, en-US-AriaNeural] } # generate two preview samples
|
|
58
|
-
voice_health {} # self-check TTS / ASR / proxy config
|
|
59
|
-
```
|
|
39
|
+
- **Audition voices before committing to a full render**
|
|
40
|
+
> List the built-in voices and generate short preview MP3s for 4 distinct voices so I can choose my favorite.
|
|
41
|
+
- **Render a polished voiceover MP3**
|
|
42
|
+
> Synthesize this release summary into `release-note.mp3` using `en-US-AriaNeural` at `+10%` speed.
|
|
43
|
+
- **Transcribe a recording with domain terminology hints**
|
|
44
|
+
> Transcribe `interview.mp3` in this workspace (prompt hint: DeepSeek Harness, Cordis), save the full text to `interview.txt`, and list the 5 key takeaways.
|
|
45
|
+
- **Offline configuration self-check**
|
|
46
|
+
> Run a voice health check to verify my default TTS voice, proxy, and ASR key status.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Quick Troubleshooting Checklist
|
|
51
|
+
|
|
52
|
+
Run `voice_health` first (offline check with zero network traffic that clearly separates `voice_stt`-only issues from TTS):
|
|
60
53
|
|
|
61
|
-
|
|
54
|
+
| Symptom | Usual Cause | Quick Fix |
|
|
55
|
+
| :--- | :--- | :--- |
|
|
56
|
+
| Health check says `asrApiKey` is missing | `asrApiKey` and `DSH_VOICE_ASR_KEY` are both empty | Safe to ignore if you only need TTS (`voice_tts` needs no key); for transcription, fill `asrApiKey` in **DSH Settings → Plugins → Voice** (applies live) |
|
|
57
|
+
| Invalid voice ID error | `ttsVoice` does not match Edge neural voice format | Run `voice_list` to pick a valid ID (e.g. `zh-CN-XiaoxiaoNeural`) and update `ttsVoice` in Settings |
|
|
58
|
+
| Network error on TTS or STT | Direct connection blocked by corporate network | Enter an HTTP(S) `proxyUrl` (e.g. `http://127.0.0.1:7890`) in **DSH Settings → Plugins → Voice** (applies live) |
|
|
59
|
+
| Path outside session workspace error | Audio or output path resolves outside workspace | Copy the recording into the current session workspace folder first |
|
|
60
|
+
| Audio exceeds 25 MB limit | Standard Whisper / ASR multipart cap is 25 MB | Compress or split the recording with `dsh-ffmpeg` before transcribing |
|
|
61
|
+
| ASR refuses a 3xx redirect | Redirects are blocked so audio/keys never leak to another host | Set `asrBaseUrl` directly to the final non-redirecting `/v1` endpoint |
|
|
62
|
+
| Existing output file was not overwritten | `overwrite: false` (default) suffixes `_1`, `_2` safely | Use the exact path returned by the tool, or enable `overwrite` in Settings |
|
|
62
63
|
|
|
63
|
-
|
|
64
|
-
- **API configuration**: TTS needs no separate API key. STT uses your configured ASR service, whose pricing and limits apply.
|
|
65
|
-
- Up-front validation: text ≤ 5000 chars, audio ≤ 25MB (re-checked against the bytes actually read); same-name outputs auto-suffixed
|
|
66
|
-
- **Reads and writes stay inside the session workspace**: `audio`, `output` and `outputDir` must resolve (symlinks included) under `session.header.cwd`; anything outside is rejected. Copy the file in first.
|
|
67
|
-
- **Symlinks are never written through**: a target that is a symlink (including a dangling one) is refused, and new files are created with `O_EXCL`.
|
|
68
|
-
- **Transcripts are 0600**: the `.txt` written by `voice_stt` is owner-only (Windows does not enforce the mode bits).
|
|
69
|
-
- **The key only goes to the configured endpoint**: ASR always uses `asrBaseUrl` from config (the groq/openai presets are defaults only); an `engine` argument that differs from config is rejected instead of shipping the key to another vendor.
|
|
70
|
-
- Protocol aligned with current open-source edge-tts (7.x) — no reliance on the outdated token endpoint
|
|
64
|
+
---
|
|
71
65
|
|
|
72
|
-
##
|
|
66
|
+
## Tool & Safety Reference
|
|
73
67
|
|
|
74
|
-
|
|
68
|
+
### Registered Tools (All 5)
|
|
75
69
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
70
|
+
| Tool | Purpose | Key Parameters & Notes |
|
|
71
|
+
| :--- | :--- | :--- |
|
|
72
|
+
| `voice_tts` | Synthesize MP3 from text (keyless Edge neural TTS) | `text` required (≤5000 chars); optional `voice`, `rate`, `pitch`, `output` |
|
|
73
|
+
| `voice_stt` | Transcribe audio to text (Groq / OpenAI / custom) | `audio` required (≤25 MB); optional `model`, `language`, `prompt`, `output` |
|
|
74
|
+
| `voice_list` | Browse curated multilingual & dialect voice catalog | No parameters |
|
|
75
|
+
| `voice_preview` | Bounded-concurrency (≤3) batch voice preview MP3s | Optional `voices` (≤8), `text` (≤200 chars), `outputDir` |
|
|
76
|
+
| `voice_health` | Offline configuration self-check | Checks TTS voice, proxy, and ASR engine/endpoint/key |
|
|
83
77
|
|
|
84
|
-
|
|
78
|
+
### Workspace & Credential Guardrails
|
|
79
|
+
|
|
80
|
+
- **Workspace confinement & symlink protection**: All reads and writes stay under `session.header.cwd`, symlinks are never written through, new files use `O_EXCL`, and `.txt` transcripts use `0600` permissions on POSIX.
|
|
81
|
+
- **Pinned endpoint & redirect block**: ASR requests only go to the configured `asrBaseUrl`, mismatched `engine` overrides are rejected, and `3xx` redirects abort immediately before sending audio.
|
|
82
|
+
- **Instant cancellation**: `voice_tts`, `voice_preview`, and `voice_stt` propagate `exec.signal` to close WebSockets and abort uploads immediately on cancel.
|
|
83
|
+
|
|
84
|
+
## Install, Uninstall & Development
|
|
85
85
|
|
|
86
86
|
```bash
|
|
87
|
+
# Install (use desktop instead of web for DSH Desktop)
|
|
88
|
+
dsh plugin --profile web add dsh-voice
|
|
89
|
+
|
|
90
|
+
# Uninstall
|
|
91
|
+
dsh plugin --profile web remove dsh-voice
|
|
92
|
+
|
|
93
|
+
# Build & run offline unit tests
|
|
87
94
|
pnpm install
|
|
88
|
-
pnpm test
|
|
89
|
-
pnpm test:integration # opt-in real edge-tts request; network and assertion errors fail
|
|
95
|
+
pnpm test
|
|
90
96
|
```
|
|
91
97
|
|
|
92
98
|
## License
|
|
93
99
|
|
|
94
|
-
Original code MIT; separate Edge v2 token module
|
|
100
|
+
Original code MIT; separate Edge v2 token module LGPL-3.0-only. See [third-party notices](../THIRD_PARTY_NOTICES.md).
|
package/docs/USAGE.md
CHANGED
|
@@ -2,93 +2,99 @@
|
|
|
2
2
|
|
|
3
3
|
[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 最快 3 步用起来
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
### 第 1 步:了解零配置范围与可选 ASR 配置
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
- **文字转语音(`voice_tts` / `voice_list` / `voice_preview`)零配置即用**:无需申请任何 API 密钥,安装后联网即可试听音色与合成 MP3。
|
|
10
|
+
- **录音转文字(`voice_stt`)按需填密钥**:
|
|
11
|
+
- **推荐方式**:打开 **DSH → 设置 → 插件 → 语音(`dsh-voice`)**,选择 `asrEngine`(默认 `groq`,也可选 `openai` 或 `custom`),填入 `asrApiKey`(自动脱敏,**保存立即生效、无需重启**);
|
|
12
|
+
- **命令行 / 环境变量方式**:设置环境变量 `DSH_VOICE_ASR_KEY`,或在 `cordis.patch.yml` 中配置:
|
|
10
13
|
|
|
11
|
-
```
|
|
12
|
-
|
|
14
|
+
```yaml
|
|
15
|
+
- id: voice
|
|
16
|
+
name: 'dsh-voice'
|
|
17
|
+
config:
|
|
18
|
+
ttsVoice: zh-CN-XiaoxiaoNeural # 默认朗读音色(保存即生效)
|
|
19
|
+
ttsRate: '+0%' # 默认语速,如 +15% 或 -10%
|
|
20
|
+
ttsPitch: '+0Hz' # 默认音调,如 +2Hz 或 -1Hz
|
|
21
|
+
asrEngine: groq # groq | openai | custom
|
|
22
|
+
asrModel: whisper-large-v3-turbo # 可选;留空按引擎预设自动填入
|
|
23
|
+
# asrApiKey: gsk_... # 推荐在 DSH 设置页填写或用环境变量 DSH_VOICE_ASR_KEY
|
|
24
|
+
# proxyUrl: http://127.0.0.1:7890 # 网络需要 HTTP(S) 代理时填写
|
|
13
25
|
```
|
|
14
26
|
|
|
15
|
-
|
|
27
|
+
### 第 2 步:在工作区内准备文稿或录音
|
|
16
28
|
|
|
17
|
-
|
|
18
|
-
dsh plugin --profile web remove dsh-voice
|
|
19
|
-
```
|
|
29
|
+
为了防止路径越界读取隐私文件,所有待转写音频与生成的 MP3 / `.txt` 都严格限制在**当前会话工作区**内;外部录音请先复制进工作区目录。
|
|
20
30
|
|
|
21
|
-
|
|
31
|
+
### 第 3 步:试听选定音色,合成配音或转写纪要
|
|
22
32
|
|
|
23
|
-
|
|
33
|
+
不确定哪个声音好听时,先让助手生成几段 3 秒短试听样例对比,再一键合成正式音频。
|
|
24
34
|
|
|
25
|
-
|
|
35
|
+
---
|
|
26
36
|
|
|
27
|
-
|
|
28
|
-
- id: voice
|
|
29
|
-
name: 'dsh-voice'
|
|
30
|
-
config:
|
|
31
|
-
asrEngine: groq # groq | openai | custom
|
|
32
|
-
asrModel: whisper-large-v3-turbo # groq 的 whisper 模型
|
|
33
|
-
# asrApiKey: gsk_... # 推荐改用环境变量 DSH_VOICE_ASR_KEY
|
|
34
|
-
ttsVoice: zh-CN-XiaoxiaoNeural # 默认音色
|
|
35
|
-
# proxyUrl: http://127.0.0.1:7890 # ASR 接口需要特殊代理时启用
|
|
36
|
-
```
|
|
37
|
+
## 平时怎么对助手说(可直接复制的自然语言示例)
|
|
37
38
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
voice_tts { text: hello, voice: en-US-AriaNeural } # 英文女声
|
|
53
|
-
voice_stt { audio: meeting.mp3, language: zh } # 转写会话工作区里的录音
|
|
54
|
-
voice_list {}
|
|
55
|
-
voice_preview { voices: [zh-CN-XiaoxiaoNeural, en-US-AriaNeural] } # 生成两个试听样例
|
|
56
|
-
voice_health {} # 自检 TTS / ASR / 代理配置
|
|
57
|
-
```
|
|
39
|
+
- **批量短试听挑选音色(不盲猜 ID)**
|
|
40
|
+
> 先帮我看看常用中英文音色清单,挑 4 个风格不同的音色生成一段短试听 MP3 让我选。
|
|
41
|
+
- **把文章或报告合成可播放的语音文件**
|
|
42
|
+
> 用 `zh-CN-YunxiNeural` 男声(语速 `+10%`)把这段产品更新说明合成到 `update-audio.mp3`。
|
|
43
|
+
- **录音转写 + 专有名词纠偏 + 落盘存档**
|
|
44
|
+
> 把工作区里的 `interview.mp3` 转写成中文(提示词加上专有名词:DeepSeek Harness、Cordis),完整转写存进 `interview.txt`,并总结 5 条核心结论。
|
|
45
|
+
- **不确定代理或密钥是否就绪时先自检**
|
|
46
|
+
> 跑一下语音插件自检,看看当前默认音色、代理和语音转文字密钥状态。
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 常见卡点自检
|
|
51
|
+
|
|
52
|
+
遇到问题先让助手执行 `voice_health`(纯本地检查,不发起网络请求,并明确区分哪些问题只影响 `voice_stt`):
|
|
58
53
|
|
|
59
|
-
|
|
54
|
+
| 现象 | 常见原因 | 一步修复 |
|
|
55
|
+
| :--- | :--- | :--- |
|
|
56
|
+
| 自检提示「缺 ASR 密钥」 | 尚未填写 `asrApiKey` 且未设 `DSH_VOICE_ASR_KEY` | 若只需朗读配音可忽略(`voice_tts` 不需要密钥);若需转写录音,在 **DSH「设置 → 插件 → 语音」**填入 `asrApiKey` 保存即生效 |
|
|
57
|
+
| 提示音色 ID 不合法 | `ttsVoice` 拼写不符合 Edge 神经音色格式 | 让助手运行 `voice_list` 查看合法 ID(如 `zh-CN-XiaoxiaoNeural`),在设置页更新 `ttsVoice` |
|
|
58
|
+
| `voice_tts` 或 `voice_stt` 报网络失败 | 当前网络无法直连 Edge 朗读服务或外网 ASR 接口 | 在 **DSH「设置 → 插件 → 语音」**填写 `proxyUrl`(如 `http://127.0.0.1:7890`,保存即生效) |
|
|
59
|
+
| 提示文件必须位于会话工作区内 | 传入了工作区外部路径或越界符号链接 | 将录音复制到当前会话工作区文件夹内再执行 |
|
|
60
|
+
| 音频超过 25MB 报超限 | OpenAI / Groq 兼容 ASR 单文件上限 25MB | 先用 `dsh-ffmpeg` 压低码率或分段裁剪后再转写 |
|
|
61
|
+
| ASR 返回 3xx 重定向被拦截 | 为防音频与密钥被转发到第三方主机,插件拒绝自动跟随重定向 | 将 `asrBaseUrl` 直接改为服务商最终无跳转的 `/v1` 地址 |
|
|
62
|
+
| 同名文件没有覆盖旧文件 | 默认 `overwrite: false` 防误删,自动追加 `_1`、`_2` 序号 | 查看工具返回的实际落盘路径,或在设置中显式开启 `overwrite` |
|
|
60
63
|
|
|
61
|
-
|
|
62
|
-
- **接口配置**:TTS 无需另填 API Key;STT 使用你配置的 ASR 服务,其计费与额度由该服务决定。
|
|
63
|
-
- 文本 ≤5000 字符、音频 ≤25MB 前置校验(读入后再按实际字节数复查一次);输出同名自动加序号
|
|
64
|
-
- **读写都在会话工作区内**:`audio` 与 `output` / `outputDir` 解析后(含符号链接)必须落在 `session.header.cwd` 之下,越界直接报错。想转写工作区外的录音,先复制进来;输出同理
|
|
65
|
-
- **不跟随符号链接写文件**:目标是符号链接(含悬空链接)时拒绝写入,新建文件用 `O_EXCL`,避免检查完再被换成链接
|
|
66
|
-
- **转写文本 0600**:`voice_stt` 写出的 `.txt` 只给当前用户读写(Windows 不检查权限位)
|
|
67
|
-
- **密钥只发给配置的地址**:ASR 请求地址一律取配置 `asrBaseUrl`(groq/openai 的预设只是缺省值),模型传的 `engine` 与配置不一致会直接报错,避免把密钥发到另一家的主机
|
|
68
|
-
- **重定向需要用户确认地址**:接口返回 3xx 时停止,不向跳转地址发送音频。请检查服务文档,把 `asrBaseUrl` 设为可信的最终接口;这也适用于配置了插件代理的请求。
|
|
69
|
-
- **并发生成不覆盖**:`overwrite=false` 时即使两个任务同时写同名文件,或合成期间出现用户同名文件,也会另存并返回实际文件名。显式覆盖只接受没有硬链接的普通文件。
|
|
70
|
-
- Edge TTS 协议适配保留在插件实现中,不使用旧令牌端点。
|
|
64
|
+
---
|
|
71
65
|
|
|
72
|
-
##
|
|
66
|
+
## 工具与安全边界参考
|
|
73
67
|
|
|
74
|
-
|
|
68
|
+
### 注册工具清单(共 5 个)
|
|
75
69
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
70
|
+
| 工具 | 作用 | 关键参数与说明 |
|
|
71
|
+
| :--- | :--- | :--- |
|
|
72
|
+
| `voice_tts` | 文字合成 MP3(零密钥 Edge 在线神经语音) | `text` 必填(≤5000 字符);`voice` / `rate` / `pitch` / `output` 可选 |
|
|
73
|
+
| `voice_stt` | 音频转文字(Groq / OpenAI / 自定义兼容端点) | `audio` 必填(≤25MB);`model` / `language` / `prompt` / `output` 可选 |
|
|
74
|
+
| `voice_list` | 查看内置常用多语种与方言音色目录 | 无参数 |
|
|
75
|
+
| `voice_preview` | 有界并发(最多 3 路)批量生成短试听 MP3 | `voices`(最多 8 个)/ `text`(≤200 字)/ `outputDir` 可选 |
|
|
76
|
+
| `voice_health` | 本地配置自检(不触网) | 逐项检查默认音色、代理、ASR 引擎/地址/密钥与影响面 |
|
|
83
77
|
|
|
84
|
-
|
|
78
|
+
### 安全与文件保护细节
|
|
79
|
+
|
|
80
|
+
- **工作区沙箱与符号链接防护**:所有读写路径解析后必须位于 `session.header.cwd` 内;拒绝跟随符号链接覆写,新建文件使用 `O_EXCL` 防止并发竞态覆盖,转写 `.txt` 在类 Unix 系统以 `0600` 权限写入。
|
|
81
|
+
- **防凭据串台与防重定向泄露**:ASR 请求固定发往配置的 `asrBaseUrl`,拒绝模型调用时用 `engine` 临时切到其他厂商,且遇 `3xx` 重定向立即中止上传。
|
|
82
|
+
- **随时可取消**:`voice_tts`、`voice_preview` 与 `voice_stt` 全程透传 `exec.signal`,用户点击停止即刻关闭 WebSocket 或中止上传。
|
|
83
|
+
|
|
84
|
+
## 安装、卸载与开发
|
|
85
85
|
|
|
86
86
|
```bash
|
|
87
|
+
# 安装(桌面版把 web 换为 desktop)
|
|
88
|
+
dsh plugin --profile web add dsh-voice
|
|
89
|
+
|
|
90
|
+
# 卸载
|
|
91
|
+
dsh plugin --profile web remove dsh-voice
|
|
92
|
+
|
|
93
|
+
# 本地构建与离线单元测试
|
|
87
94
|
pnpm install
|
|
88
|
-
pnpm test
|
|
89
|
-
pnpm test:integration # 显式联网,调用真实 edge-tts;网络或断言失败均报错
|
|
95
|
+
pnpm test
|
|
90
96
|
```
|
|
91
97
|
|
|
92
98
|
## License
|
|
93
99
|
|
|
94
|
-
|
|
100
|
+
主体代码采用 MIT;独立的 Edge v2 令牌计算模块遵循 LGPL-3.0-only,详见 [第三方声明](../THIRD_PARTY_NOTICES.md)。
|