dsh-voice 0.6.1 → 0.8.0

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/lib/config.d.ts CHANGED
@@ -1,36 +1,77 @@
1
1
  /**
2
- * dsh-voice 配置解析:TTS 默认音色与语速、ASR 引擎与密钥、代理。
2
+ * dsh-voice 配置解析:TTS 引擎与默认音色语速、ASR 引擎与密钥、代理。
3
3
  *
4
4
  * @module dsh-voice/config
5
5
  */
6
+ /** TTS 引擎类型。 */
7
+ export type TtsEngine = 'edge' | 'openai' | 'siliconflow' | 'custom';
8
+ /** ASR 引擎类型。 */
9
+ export type AsrEngine = 'groq' | 'openai' | 'siliconflow' | 'custom';
10
+ /** 自定义音色与零样本克隆别名。 */
11
+ export interface CustomVoiceAlias {
12
+ name: string;
13
+ voice?: string;
14
+ persona?: string;
15
+ rate?: string;
16
+ pitch?: string;
17
+ instructions?: string;
18
+ referenceAudio?: string;
19
+ referenceText?: string;
20
+ }
6
21
  /** 插件行配置(cordis.patch.yml 里的 config 段,可缺省)。 */
7
22
  export interface VoiceConfig {
23
+ ttsEngine?: TtsEngine;
24
+ ttsBaseUrl?: string;
25
+ ttsApiKey?: string;
26
+ ttsModel?: string;
8
27
  ttsVoice?: string;
9
28
  ttsRate?: string;
10
29
  ttsPitch?: string;
11
- asrEngine?: 'groq' | 'openai' | 'custom';
30
+ asrEngine?: AsrEngine;
12
31
  asrBaseUrl?: string;
13
32
  asrApiKey?: string;
14
33
  asrModel?: string;
15
34
  proxyUrl?: string;
16
35
  timeoutMs?: number;
17
36
  overwrite?: boolean;
37
+ customVoices?: CustomVoiceAlias[];
18
38
  }
19
39
  /** 解析后的配置。 */
20
40
  export interface ResolvedVoiceConfig {
41
+ ttsEngine: TtsEngine;
42
+ ttsBaseUrl: string;
43
+ ttsApiKey: string;
44
+ ttsModel: string;
21
45
  ttsVoice: string;
22
46
  ttsRate: string;
23
47
  ttsPitch: string;
24
- asrEngine: 'groq' | 'openai' | 'custom';
48
+ asrEngine: AsrEngine;
25
49
  asrBaseUrl: string;
26
50
  asrApiKey: string;
27
51
  asrModel: string;
28
52
  proxyUrl: string;
29
53
  timeoutMs: number;
30
54
  overwrite: boolean;
55
+ customVoices: CustomVoiceAlias[];
31
56
  }
57
+ export declare const ASR_PRESETS: Record<'groq' | 'openai' | 'siliconflow', {
58
+ baseUrl: string;
59
+ model: string;
60
+ }>;
61
+ export declare const TTS_PRESETS: Record<'openai' | 'siliconflow', {
62
+ baseUrl: string;
63
+ model: string;
64
+ }>;
65
+ /** 校验 SSML prosody 参数(语速 / 音调),如 +0%、-15%、+2Hz、-1st。 */
66
+ export declare function isValidProsody(value: string): boolean;
67
+ /** 判断 baseUrl 是否指向本机回环地址(用于允许本地无密钥服务)。 */
68
+ export declare function isLoopbackBaseUrl(url: string): boolean;
32
69
  /** ASR 密钥:配置优先,其次环境变量 DSH_VOICE_ASR_KEY。 */
33
70
  export declare function resolveAsrApiKey(config: VoiceConfig | undefined, env?: NodeJS.ProcessEnv): string;
71
+ /** TTS 密钥:配置优先,其次环境变量 DSH_VOICE_TTS_KEY。 */
72
+ export declare function resolveTtsApiKey(config: VoiceConfig | undefined, env?: NodeJS.ProcessEnv): string;
73
+ /** 按别名(大小写不敏感)查找自定义音色配置。 */
74
+ export declare function resolveCustomVoice(customVoices: readonly CustomVoiceAlias[], nameOrId: string): CustomVoiceAlias | undefined;
34
75
  /**
35
76
  * 解析并校验配置:非法字段逐项回退到默认值,其余字段照常生效。
36
77
  * @param onWarning 非法字段的告警回调,默认打到 console.warn。
package/lib/config.js CHANGED
@@ -1,12 +1,34 @@
1
1
  /**
2
- * dsh-voice 配置解析:TTS 默认音色与语速、ASR 引擎与密钥、代理。
2
+ * dsh-voice 配置解析:TTS 引擎与默认音色语速、ASR 引擎与密钥、代理。
3
3
  *
4
4
  * @module dsh-voice/config
5
5
  */
6
- const ENGINE_PRESETS = {
6
+ export const ASR_PRESETS = {
7
7
  groq: { baseUrl: 'https://api.groq.com/openai/v1', model: 'whisper-large-v3-turbo' },
8
8
  openai: { baseUrl: 'https://api.openai.com/v1', model: 'whisper-1' },
9
+ siliconflow: { baseUrl: 'https://api.siliconflow.cn/v1', model: 'FunAudioLLM/SenseVoiceSmall' },
9
10
  };
11
+ export const TTS_PRESETS = {
12
+ openai: { baseUrl: 'https://api.openai.com/v1', model: 'gpt-4o-mini-tts' },
13
+ siliconflow: { baseUrl: 'https://api.siliconflow.cn/v1', model: 'FunAudioLLM/CosyVoice2-0.5B' },
14
+ };
15
+ /** 校验 SSML prosody 参数(语速 / 音调),如 +0%、-15%、+2Hz、-1st。 */
16
+ export function isValidProsody(value) {
17
+ return /^[+-]?\d+(\.\d+)?(%|Hz|st)$/.test(value);
18
+ }
19
+ /** 判断 baseUrl 是否指向本机回环地址(用于允许本地无密钥服务)。 */
20
+ export function isLoopbackBaseUrl(url) {
21
+ const trimmed = url.trim();
22
+ if (trimmed === '')
23
+ return false;
24
+ try {
25
+ const hostname = new URL(trimmed).hostname.toLowerCase();
26
+ return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
27
+ }
28
+ catch {
29
+ return false;
30
+ }
31
+ }
10
32
  /** ASR 密钥:配置优先,其次环境变量 DSH_VOICE_ASR_KEY。 */
11
33
  export function resolveAsrApiKey(config, env = process.env) {
12
34
  const cfg = config ?? {};
@@ -14,27 +36,117 @@ export function resolveAsrApiKey(config, env = process.env) {
14
36
  return cfg.asrApiKey.trim();
15
37
  return env.DSH_VOICE_ASR_KEY?.trim() ?? '';
16
38
  }
39
+ /** TTS 密钥:配置优先,其次环境变量 DSH_VOICE_TTS_KEY。 */
40
+ export function resolveTtsApiKey(config, env = process.env) {
41
+ const cfg = config ?? {};
42
+ if (typeof cfg.ttsApiKey === 'string' && cfg.ttsApiKey.trim() !== '')
43
+ return cfg.ttsApiKey.trim();
44
+ return env.DSH_VOICE_TTS_KEY?.trim() ?? '';
45
+ }
17
46
  /** 默认告警出口:非法字段逐项回退时点名,避免一个字段拖垮整份配置。 */
18
47
  function defaultWarn(message) {
19
48
  console.warn('[dsh-voice] ' + message);
20
49
  }
50
+ function isPlainObject(value) {
51
+ if (typeof value !== 'object' || value === null || Array.isArray(value))
52
+ return false;
53
+ const proto = Object.getPrototypeOf(value);
54
+ return proto === Object.prototype || proto === null;
55
+ }
56
+ function trimOptionalString(value) {
57
+ if (typeof value !== 'string')
58
+ return undefined;
59
+ const trimmed = value.trim();
60
+ return trimmed === '' ? undefined : trimmed;
61
+ }
62
+ function parseCustomVoices(raw, onWarning) {
63
+ if (raw === undefined)
64
+ return [];
65
+ if (!Array.isArray(raw)) {
66
+ onWarning('customVoices 配置不合法(必须是数组),已忽略该项。');
67
+ return [];
68
+ }
69
+ const result = [];
70
+ for (let i = 0; i < raw.length; i += 1) {
71
+ const item = raw[i];
72
+ if (!isPlainObject(item))
73
+ continue;
74
+ const name = trimOptionalString(item.name);
75
+ if (name === undefined)
76
+ continue;
77
+ const entry = { name };
78
+ const voice = trimOptionalString(item.voice);
79
+ if (voice !== undefined)
80
+ entry.voice = voice;
81
+ const persona = trimOptionalString(item.persona);
82
+ if (persona !== undefined)
83
+ entry.persona = persona;
84
+ const rate = trimOptionalString(item.rate);
85
+ if (rate !== undefined) {
86
+ if (isValidProsody(rate))
87
+ entry.rate = rate;
88
+ else
89
+ onWarning(`customVoices[${i}].rate 配置不合法(格式如 +0%、+15%、-10%),已忽略该字段,当前值:${rate}`);
90
+ }
91
+ const pitch = trimOptionalString(item.pitch);
92
+ if (pitch !== undefined) {
93
+ if (isValidProsody(pitch))
94
+ entry.pitch = pitch;
95
+ else
96
+ onWarning(`customVoices[${i}].pitch 配置不合法(格式如 +0Hz、+2Hz、-1st),已忽略该字段,当前值:${pitch}`);
97
+ }
98
+ const instructions = trimOptionalString(item.instructions);
99
+ if (instructions !== undefined)
100
+ entry.instructions = instructions;
101
+ const referenceAudio = trimOptionalString(item.referenceAudio);
102
+ if (referenceAudio !== undefined)
103
+ entry.referenceAudio = referenceAudio;
104
+ const referenceText = trimOptionalString(item.referenceText);
105
+ if (referenceText !== undefined)
106
+ entry.referenceText = referenceText;
107
+ result.push(entry);
108
+ }
109
+ return result;
110
+ }
111
+ /** 按别名(大小写不敏感)查找自定义音色配置。 */
112
+ export function resolveCustomVoice(customVoices, nameOrId) {
113
+ const target = (typeof nameOrId === 'string' ? nameOrId : '').trim().toLowerCase();
114
+ if (target === '')
115
+ return undefined;
116
+ return customVoices.find((alias) => alias.name.trim().toLowerCase() === target);
117
+ }
21
118
  /**
22
119
  * 解析并校验配置:非法字段逐项回退到默认值,其余字段照常生效。
23
120
  * @param onWarning 非法字段的告警回调,默认打到 console.warn。
24
121
  */
25
122
  export function resolveConfig(config, onWarning = defaultWarn) {
26
123
  const cfg = config ?? {};
124
+ const ttsEngine = cfg.ttsEngine === 'openai' || cfg.ttsEngine === 'siliconflow' || cfg.ttsEngine === 'custom'
125
+ ? cfg.ttsEngine
126
+ : 'edge';
127
+ const ttsPreset = ttsEngine === 'openai' || ttsEngine === 'siliconflow' ? TTS_PRESETS[ttsEngine] : undefined;
128
+ const ttsBaseUrl = (typeof cfg.ttsBaseUrl === 'string' && cfg.ttsBaseUrl.trim() !== '' ? cfg.ttsBaseUrl.trim() : ttsPreset?.baseUrl ?? '').replace(/\/$/, '');
129
+ const ttsModel = typeof cfg.ttsModel === 'string' && cfg.ttsModel.trim() !== '' ? cfg.ttsModel.trim() : ttsPreset?.model ?? '';
130
+ const ttsApiKey = resolveTtsApiKey(cfg);
27
131
  const ttsVoice = typeof cfg.ttsVoice === 'string' && cfg.ttsVoice.trim() !== '' ? cfg.ttsVoice.trim() : 'zh-CN-XiaoxiaoNeural';
28
132
  const ttsRate = typeof cfg.ttsRate === 'string' && cfg.ttsRate.trim() !== '' ? cfg.ttsRate.trim() : '+0%';
133
+ if (typeof cfg.ttsRate === 'string' && cfg.ttsRate.trim() !== '' && !isValidProsody(ttsRate)) {
134
+ onWarning('ttsRate 配置不合法(格式如 +0%、+15%、-10%),当前值:' + ttsRate);
135
+ }
29
136
  const ttsPitch = typeof cfg.ttsPitch === 'string' && cfg.ttsPitch.trim() !== '' ? cfg.ttsPitch.trim() : '+0Hz';
30
- const asrEngine = cfg.asrEngine === 'openai' ? 'openai' : cfg.asrEngine === 'custom' ? 'custom' : 'groq';
31
- const preset = asrEngine === 'custom' ? undefined : ENGINE_PRESETS[asrEngine];
32
- const asrBaseUrl = (typeof cfg.asrBaseUrl === 'string' && cfg.asrBaseUrl.trim() !== '' ? cfg.asrBaseUrl.trim() : preset?.baseUrl ?? '').replace(/\/$/, '');
33
- const asrModel = typeof cfg.asrModel === 'string' && cfg.asrModel.trim() !== '' ? cfg.asrModel.trim() : preset?.model ?? '';
137
+ if (typeof cfg.ttsPitch === 'string' && cfg.ttsPitch.trim() !== '' && !isValidProsody(ttsPitch)) {
138
+ onWarning('ttsPitch 配置不合法(格式如 +0Hz、+2Hz、-1st),当前值:' + ttsPitch);
139
+ }
140
+ const asrEngine = cfg.asrEngine === 'openai' || cfg.asrEngine === 'siliconflow' || cfg.asrEngine === 'custom'
141
+ ? cfg.asrEngine
142
+ : 'groq';
143
+ const asrPreset = asrEngine === 'custom' ? undefined : ASR_PRESETS[asrEngine];
144
+ const asrBaseUrl = (typeof cfg.asrBaseUrl === 'string' && cfg.asrBaseUrl.trim() !== '' ? cfg.asrBaseUrl.trim() : asrPreset?.baseUrl ?? '').replace(/\/$/, '');
145
+ const asrModel = typeof cfg.asrModel === 'string' && cfg.asrModel.trim() !== '' ? cfg.asrModel.trim() : asrPreset?.model ?? '';
34
146
  const asrApiKey = resolveAsrApiKey(cfg);
35
147
  let proxyUrl = typeof cfg.proxyUrl === 'string' && cfg.proxyUrl.trim() !== '' ? cfg.proxyUrl.trim() : '';
36
- if (proxyUrl !== '' && !/^https?:\/\//i.test(proxyUrl)) {
37
- onWarning('proxyUrl 配置不合法(必须以 http(s):// 开头,例如 http://127.0.0.1:7890),已忽略该项,其余配置继续生效:' + proxyUrl);
148
+ if (proxyUrl !== '' && !/^(https?|socks5h?):\/\//i.test(proxyUrl)) {
149
+ onWarning('proxyUrl 配置不合法(必须以 http(s):// 或 socks5(h):// 开头,例如 http://127.0.0.1:7890 或 socks5://127.0.0.1:7890),已忽略该项,其余配置继续生效:' + proxyUrl);
38
150
  proxyUrl = '';
39
151
  }
40
152
  let timeoutMs = 60000;
@@ -47,5 +159,22 @@ export function resolveConfig(config, onWarning = defaultWarn) {
47
159
  }
48
160
  }
49
161
  const overwrite = cfg.overwrite === true;
50
- return { ttsVoice, ttsRate, ttsPitch, asrEngine, asrBaseUrl, asrApiKey, asrModel, proxyUrl, timeoutMs, overwrite };
162
+ const customVoices = parseCustomVoices(cfg.customVoices, onWarning);
163
+ return {
164
+ ttsEngine,
165
+ ttsBaseUrl,
166
+ ttsApiKey,
167
+ ttsModel,
168
+ ttsVoice,
169
+ ttsRate,
170
+ ttsPitch,
171
+ asrEngine,
172
+ asrBaseUrl,
173
+ asrApiKey,
174
+ asrModel,
175
+ proxyUrl,
176
+ timeoutMs,
177
+ overwrite,
178
+ customVoices,
179
+ };
51
180
  }
package/lib/edge-tts.d.ts CHANGED
@@ -1,3 +1,8 @@
1
+ import { type VoiceInfo } from './voices.js';
2
+ /** 重置时钟偏差缓存(测试专用)。 */
3
+ export declare function resetClockSkewForTest(): void;
4
+ /** 读取当前时钟偏差(秒)。 */
5
+ export declare function getClockSkewSeconds(): number;
1
6
  /** 合成选项。 */
2
7
  export interface TtsOptions {
3
8
  text: string;
@@ -5,6 +10,13 @@ export interface TtsOptions {
5
10
  rate: string;
6
11
  pitch: string;
7
12
  }
13
+ /** 字幕时间轴条目(毫秒级)。 */
14
+ export interface SubtitleCue {
15
+ index: number;
16
+ startMs: number;
17
+ endMs: number;
18
+ text: string;
19
+ }
8
20
  /** 可注入依赖(测试用假实现)。 */
9
21
  export interface TtsDeps {
10
22
  webSocketFactory?: WebSocketFactory;
@@ -13,12 +25,19 @@ export interface TtsDeps {
13
25
  /** 取消信号(可选);也可通过 synthesizeSpeech 第 4 个参数传入。 */
14
26
  signal?: AbortSignal;
15
27
  }
28
+ /** unexpected-response 事件中的 HTTP 响应最小面。 */
29
+ export interface UnexpectedResponseInfo {
30
+ statusCode?: number;
31
+ headers?: Record<string, string | string[] | undefined>;
32
+ resume?: () => void;
33
+ }
16
34
  /** 最小的 WebSocket 面。 */
17
35
  export interface WebSocketLike {
18
36
  addEventListener(type: 'message', listener: (event: {
19
37
  data: unknown;
20
38
  }) => void): void;
21
39
  addEventListener(type: 'open' | 'close' | 'error', listener: (event?: unknown) => void): void;
40
+ on?(event: 'unexpected-response', listener: (req: unknown, res: UnexpectedResponseInfo) => void): void;
22
41
  send(data: string): void;
23
42
  close(): void;
24
43
  }
@@ -31,8 +50,33 @@ export type WebSocketFactory = (url: string, options: {
31
50
  export declare function generateSecMsGec(nowSeconds?: number): string;
32
51
  /** 生成 SSML。 */
33
52
  export declare function buildSsml(options: TtsOptions): string;
53
+ /**
54
+ * 合成语音并可选返回句/词级边界字幕时间轴。
55
+ * 收到 HTTP 403 且响应带有效 Date 头时自动校准时钟偏差并单次重试。
56
+ * @throws 文本为空/超长 / 连接失败 / 超时 / 无音频数据时抛中文错误。
57
+ */
58
+ export declare function synthesizeSpeechWithMetadata(options: TtsOptions & {
59
+ boundary?: 'sentence' | 'word' | false;
60
+ }, deps?: TtsDeps, timeoutMs?: number, signal?: AbortSignal): Promise<{
61
+ audio: Buffer;
62
+ cues: SubtitleCue[];
63
+ }>;
34
64
  /**
35
65
  * 合成语音,返回 MP3 字节。
36
66
  * @throws 文本为空/超长 / 连接失败 / 超时 / 无音频数据时抛中文错误。
37
67
  */
38
68
  export declare function synthesizeSpeech(options: TtsOptions, deps?: TtsDeps, timeoutMs?: number, signal?: AbortSignal): Promise<Buffer>;
69
+ /** 在线音色列表拉取的可注入依赖。 */
70
+ export interface FetchEdgeVoicesDeps {
71
+ fetchImpl?: typeof fetch;
72
+ nowSeconds?: () => number;
73
+ signal?: AbortSignal;
74
+ forceRefresh?: boolean;
75
+ }
76
+ /** 重置 Edge 在线音色内存缓存(测试专用)。 */
77
+ export declare function resetEdgeVoicesCacheForTest(): void;
78
+ /**
79
+ * 动态拉取微软 Edge 在线全量(300+)音色目录并缓存 24 小时。
80
+ * @throws 请求失败 / 重定向 / 响应异常 / 超时时抛中文错误。
81
+ */
82
+ export declare function fetchEdgeVoices(deps?: FetchEdgeVoicesDeps, timeoutMs?: number): Promise<VoiceInfo[]>;