dsh-voice 0.7.0 → 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/tools.js CHANGED
@@ -5,14 +5,14 @@
5
5
  */
6
6
  import { openAsBlob, readFileSync, statSync } from 'node:fs';
7
7
  import { basename, extname, join } from 'node:path';
8
- import { isLoopbackBaseUrl, isValidProsody } from './config.js';
9
- import { synthesizeSpeech, synthesizeSpeechWithMetadata } from './edge-tts.js';
8
+ import { isLoopbackBaseUrl, isValidProsody, resolveCustomVoice } from './config.js';
9
+ import { fetchEdgeVoices, synthesizeSpeech, synthesizeSpeechWithMetadata } from './edge-tts.js';
10
10
  import { rateToSpeed, synthesizeOpenAiSpeech } from './openai-tts.js';
11
11
  import { assertAudioFile, assertWorkspaceFile, ensureWorkspaceDirectory, resolveOutputPath, writeWorkspaceFile } from './paths.js';
12
12
  import { createProxyFetch } from './proxy-fetch.js';
13
13
  import { assertAudioSize, formatSttSubtitles, hasFfmpeg, prepareAudioForAsr, transcribe } from './stt.js';
14
- import { cleanMarkdownForSpeech, concatMp3Buffers, createSilenceMp3, estimateMp3DurationMs, formatSubtitles, offsetCues, renderPreviewHtml, splitTextIntoChunks, } from './tts-text.js';
15
- import { filterVoices, isValidVoiceId, VOICES } from './voices.js';
14
+ import { cleanMarkdownForSpeech, concatMp3Buffers, createSilenceMp3, estimateMp3DurationMs, formatSubtitles, normalizeAudioLoudness, offsetCues, renderPreviewHtml, splitTextIntoChunks, } from './tts-text.js';
15
+ import { filterVoices, isValidVoiceId, resolvePersona, VOICE_PERSONAS, VOICES } from './voices.js';
16
16
  function compileParameters(spec) {
17
17
  const properties = {};
18
18
  const required = [];
@@ -124,7 +124,14 @@ const voiceItemSchema = {
124
124
  };
125
125
  const listSchema = {
126
126
  type: 'object',
127
- properties: { count: { type: 'integer' }, voices: { type: 'array', items: voiceItemSchema } },
127
+ properties: {
128
+ count: { type: 'integer' },
129
+ voices: { type: 'array', items: voiceItemSchema },
130
+ source: { type: 'string' },
131
+ personas: { type: 'array', items: { type: 'object', additionalProperties: true } },
132
+ customVoices: { type: 'array', items: { type: 'object', additionalProperties: true } },
133
+ fallbackReason: { type: 'string' },
134
+ },
128
135
  additionalProperties: true,
129
136
  };
130
137
  const ttsSchema = {
@@ -174,6 +181,8 @@ const MAX_TTS_SEGMENTS = 50;
174
181
  const FALLBACK_TTS_MODEL = 'gpt-4o-mini-tts';
175
182
  /** ASR 直传上限(25MB)。 */
176
183
  const MAX_ASR_BYTES = 25 * 1024 * 1024;
184
+ /** 零样本克隆参考音频上限(10MB)。 */
185
+ const MAX_REFERENCE_AUDIO_BYTES = 10 * 1024 * 1024;
177
186
  /** 默认试听文本(中英混合,便于感知发音差异)。 */
178
187
  export const DEFAULT_PREVIEW_TEXT = '你好,这是音色试听。Hello, this is a voice preview.';
179
188
  /** voice_preview 同时合成的音色数上限:有界并发,避免 8 个音色串行把最坏等待拖成 8 倍超时。 */
@@ -212,17 +221,113 @@ export function buildVoiceTools(config, deps = {}) {
212
221
  throw new Error('未配置 TTS 密钥:请在 DSH「设置 → 插件 → 语音」配置 ttsApiKey,或设置环境变量 DSH_VOICE_TTS_KEY。');
213
222
  }
214
223
  };
215
- const assertTtsVoice = (voice, useEdge) => {
224
+ const assertTtsVoice = (voice, useEdge, hasReferences = false) => {
216
225
  if (useEdge) {
217
226
  if (!isValidVoiceId(voice)) {
218
227
  throw new Error('音色 id 不合法:' + voice + '。请用 voice_list 查看常用音色,或在 DSH「设置 → 插件 → 语音」修改 ttsVoice(合法格式如 zh-CN-XiaoxiaoNeural)。');
219
228
  }
220
229
  return;
221
230
  }
222
- if (voice.trim() === '')
231
+ if (voice.trim() === '' && !hasReferences)
223
232
  throw new Error('音色 id 不合法:不能为空。');
224
233
  };
225
- const synthesizeChunk = async (cfg, useEdge, chunkText, voice, rate, pitch, needSubtitles, signal) => {
234
+ const resolveUseEdge = (cfg, hasReferenceAudio) => {
235
+ if (deps.tts !== undefined || deps.ttsWithMeta !== undefined)
236
+ return true;
237
+ if (deps.openaiTts !== undefined && (cfg.ttsEngine !== 'edge' || hasReferenceAudio))
238
+ return false;
239
+ return cfg.ttsEngine === 'edge';
240
+ };
241
+ const resolveEffectiveVoiceSpec = (cfg, cwd, input) => {
242
+ let customAlias;
243
+ let voiceConsumedAsAlias = false;
244
+ let personaConsumedAsAlias = false;
245
+ if (input.persona !== undefined) {
246
+ customAlias = resolveCustomVoice(cfg.customVoices, input.persona);
247
+ if (customAlias !== undefined)
248
+ personaConsumedAsAlias = true;
249
+ }
250
+ if (customAlias === undefined && input.voice !== undefined) {
251
+ customAlias = resolveCustomVoice(cfg.customVoices, input.voice);
252
+ if (customAlias !== undefined)
253
+ voiceConsumedAsAlias = true;
254
+ }
255
+ let defaultAlias;
256
+ if (input.voice === undefined && input.persona === undefined) {
257
+ defaultAlias = resolveCustomVoice(cfg.customVoices, cfg.ttsVoice);
258
+ }
259
+ const activeAlias = customAlias ?? defaultAlias;
260
+ let voiceConsumedAsPersona = false;
261
+ let personaSpec = !personaConsumedAsAlias && input.persona !== undefined
262
+ ? resolvePersona(input.persona)
263
+ : undefined;
264
+ if (personaSpec === undefined && activeAlias?.persona !== undefined) {
265
+ personaSpec = resolvePersona(activeAlias.persona);
266
+ }
267
+ if (personaSpec === undefined && !voiceConsumedAsAlias && input.voice !== undefined && !isValidVoiceId(input.voice)) {
268
+ personaSpec = resolvePersona(input.voice);
269
+ if (personaSpec !== undefined)
270
+ voiceConsumedAsPersona = true;
271
+ }
272
+ let defaultPersona;
273
+ if (input.voice === undefined && input.persona === undefined && activeAlias === undefined && !isValidVoiceId(cfg.ttsVoice)) {
274
+ defaultPersona = resolvePersona(cfg.ttsVoice);
275
+ }
276
+ const activePersona = personaSpec ?? defaultPersona;
277
+ const explicitRawVoice = !voiceConsumedAsAlias && !voiceConsumedAsPersona ? input.voice : undefined;
278
+ const effectiveInstructions = input.instructions ?? activeAlias?.instructions;
279
+ const effectiveReferenceAudio = input.referenceAudio ?? activeAlias?.referenceAudio;
280
+ const effectiveReferenceText = input.referenceText ?? activeAlias?.referenceText;
281
+ let references;
282
+ const hasReferenceAudio = effectiveReferenceAudio !== undefined && effectiveReferenceAudio.trim() !== '';
283
+ if (hasReferenceAudio) {
284
+ const refPath = assertAudioFile(effectiveReferenceAudio, cwd);
285
+ const size = statSync(refPath).size;
286
+ if (size <= 0) {
287
+ throw new Error('参考音频文件为空,无法用于音色克隆:' + effectiveReferenceAudio);
288
+ }
289
+ if (size > MAX_REFERENCE_AUDIO_BYTES) {
290
+ throw new Error('参考音频超过 10MB 上限(当前 ' + size + ' 字节),请裁剪为 5–10 秒人声片段:' + effectiveReferenceAudio);
291
+ }
292
+ const buf = readFileSync(refPath);
293
+ if (buf.length === 0 || buf.length > MAX_REFERENCE_AUDIO_BYTES) {
294
+ throw new Error('参考音频大小异常(必须为 1 字节至 10MB):' + effectiveReferenceAudio);
295
+ }
296
+ if (resolveUseEdge(cfg, true)) {
297
+ throw new Error('零样本参考音频克隆(referenceAudio)需要兼容克隆的 TTS 引擎:请在 DSH「设置 → 插件 → 语音」将 ttsEngine 切换为 siliconflow(CosyVoice2-0.5B)或 custom(如本地 GPT-SoVITS / IndexTTS)。');
298
+ }
299
+ references = [{
300
+ audioDataUri: 'data:' + mimeFromPath(refPath) + ';base64,' + buf.toString('base64'),
301
+ ...(effectiveReferenceText !== undefined && effectiveReferenceText.trim() !== '' ? { text: effectiveReferenceText.trim() } : {}),
302
+ }];
303
+ }
304
+ const effectiveVoice = references !== undefined && explicitRawVoice === undefined
305
+ ? (activeAlias?.voice ?? '')
306
+ : (explicitRawVoice ?? activeAlias?.voice ?? activePersona?.voice ?? cfg.ttsVoice);
307
+ const effectiveRate = input.rate ?? activeAlias?.rate ?? activePersona?.rate ?? cfg.ttsRate;
308
+ const effectivePitch = input.pitch ?? activeAlias?.pitch ?? activePersona?.pitch ?? cfg.ttsPitch;
309
+ const effectivePauseMs = input.pauseMs ?? activePersona?.pauseMs ?? 300;
310
+ return {
311
+ voice: effectiveVoice,
312
+ rate: effectiveRate,
313
+ pitch: effectivePitch,
314
+ pauseMs: effectivePauseMs,
315
+ ...(effectiveInstructions !== undefined ? { instructions: effectiveInstructions } : {}),
316
+ ...(references !== undefined ? { references } : {}),
317
+ hasReferenceAudio,
318
+ };
319
+ };
320
+ const maybeNormalizeAudio = async (shouldNormalize, audio, signal) => {
321
+ if (!shouldNormalize)
322
+ return audio;
323
+ if (deps.normalizeAudio === undefined && !hasFfmpeg()) {
324
+ throw new Error('开启 normalizeLoudness 需要本机安装 ffmpeg(或使用 dsh-ffmpeg)。');
325
+ }
326
+ const normalized = await raceAbort((deps.normalizeAudio ?? normalizeAudioLoudness)(audio, signal), signal);
327
+ throwIfAborted(signal);
328
+ return normalized;
329
+ };
330
+ const synthesizeChunk = async (cfg, useEdge, chunkText, voice, rate, pitch, needSubtitles, signal, instructions, references) => {
226
331
  if (useEdge) {
227
332
  if (!needSubtitles) {
228
333
  const ttsFn = deps.tts ?? (deps.ttsWithMeta !== undefined
@@ -251,6 +356,8 @@ export function buildVoiceTools(config, deps = {}) {
251
356
  voice,
252
357
  model: cfg.ttsModel !== '' ? cfg.ttsModel : FALLBACK_TTS_MODEL,
253
358
  speed: rateToSpeed(rate),
359
+ ...(instructions !== undefined ? { instructions } : {}),
360
+ ...(references !== undefined && references.length > 0 ? { references } : {}),
254
361
  signal,
255
362
  }, getProxyFetch(cfg.proxyUrl) ?? globalThis.fetch, cfg.timeoutMs, signal), signal);
256
363
  return {
@@ -263,62 +370,140 @@ export function buildVoiceTools(config, deps = {}) {
263
370
  const voiceList = {
264
371
  name: 'voice_list',
265
372
  isConcurrencySafe: () => true,
266
- description: '列出常用语音合成音色(edge-tts 微软神经语音,免费)。含普通话/方言/粤语/英/日/韩/法/德/俄/西及多语种音色,支持按 locale/gender/tag 筛选。voice_tts 的 voice 参数也接受清单外的合法 edge 音色 id。',
373
+ description: '列出语音合成音色与角色人设配方:默认返回内置 45+ 精选音色(涵盖童声、少年、成熟/纪录片、老年、多语种与方言),设 online=true 可实时拉取微软 Edge 全量 300+ 音色目录(失败自动回退)。同时返回内置角色人设配方(personas)与自定义音色别名(customVoices),支持按 locale/gender/tag 筛选。',
267
374
  parameters: compileParameters({
268
375
  locale: { type: 'string', description: '按语言/地区或名称关键字筛选(可选,如 zh-CN、en-US、粤语)。' },
269
376
  gender: { type: 'string', enum: ['Female', 'Male'], description: '按性别筛选(可选:Female 或 Male)。' },
270
- tag: { type: 'string', description: '按场景标签筛选(可选,如 podcast、multilingual、news、dialect)。' },
377
+ tag: { type: 'string', description: '按场景标签筛选(可选,如 podcast、multilingual、news、dialect、child、teen、mature、elder、anime、cartoon)。' },
378
+ online: { type: 'boolean', description: '是否联网拉取微软 Edge 全量 300+ 实时音色目录(可选,默认 false 使用内置精选目录;联网失败自动回退内置目录)。' },
379
+ includePersonas: { type: 'boolean', description: '是否同时返回内置角色人设配方(personas)与自定义音色别名(默认 true)。' },
271
380
  }),
272
381
  output: {
273
382
  schema: listSchema,
274
383
  render: (_args, value) => {
275
384
  const rec = asRecord(value);
276
385
  const voices = Array.isArray(rec.voices) ? rec.voices : [];
277
- const lines = ['共 ' + voices.length + ' 个常用音色:'];
386
+ const source = typeof rec.source === 'string' ? rec.source : 'builtin';
387
+ const fallbackReason = typeof rec.fallbackReason === 'string' ? rec.fallbackReason : '';
388
+ const header = source === 'edge-online'
389
+ ? '共 ' + voices.length + ' 个在线 Edge 音色:'
390
+ : source === 'builtin-fallback'
391
+ ? '在线目录拉取失败(' + fallbackReason + '),已回退内置目录,共 ' + voices.length + ' 个常用音色:'
392
+ : '共 ' + voices.length + ' 个常用音色:';
393
+ const lines = [header];
278
394
  for (const voice of voices) {
279
395
  const v = asRecord(voice);
280
396
  const tags = Array.isArray(v.tags) && v.tags.length > 0 ? ' [' + v.tags.join(', ') + ']' : '';
281
397
  lines.push('- ' + v.id + '(' + v.locale + ')' + tags);
282
398
  }
399
+ const personas = Array.isArray(rec.personas) ? rec.personas : [];
400
+ if (personas.length > 0) {
401
+ const summary = personas.map((p) => {
402
+ const item = asRecord(p);
403
+ return String(item.id ?? '') + '(' + String(item.label ?? '') + ')';
404
+ }).join('、');
405
+ lines.push('', '可用人设配方(persona):' + summary);
406
+ }
407
+ const customVoices = Array.isArray(rec.customVoices) ? rec.customVoices : [];
408
+ if (customVoices.length > 0) {
409
+ const summary = customVoices.map((c) => {
410
+ const item = asRecord(c);
411
+ const extras = [
412
+ typeof item.persona === 'string' && item.persona !== '' ? 'persona=' + item.persona : '',
413
+ typeof item.voice === 'string' && item.voice !== '' ? 'voice=' + item.voice : '',
414
+ item.hasReferenceAudio === true ? '含参考音频' : '',
415
+ ].filter(Boolean).join(', ');
416
+ return String(item.name ?? '') + (extras !== '' ? '(' + extras + ')' : '');
417
+ }).join('、');
418
+ lines.push('自定义音色别名(customVoices):' + summary);
419
+ }
283
420
  return [{ type: 'text', text: lines.join('\n') }];
284
421
  },
285
422
  },
286
- async execute(rawArgs) {
423
+ async execute(rawArgs, exec) {
424
+ const cfg = getCfg();
425
+ const signal = execSignal(exec);
426
+ throwIfAborted(signal);
287
427
  const args = asRecord(rawArgs);
288
428
  const locale = optionalString(args, 'locale');
289
429
  const gender = optionalString(args, 'gender');
290
430
  const tag = optionalString(args, 'tag');
291
431
  const hasFilter = locale !== undefined || gender !== undefined || tag !== undefined;
292
- const voices = hasFilter ? filterVoices({ locale, gender, tag }) : VOICES;
293
- return { count: voices.length, voices };
432
+ let sourceVoices = VOICES;
433
+ let source = 'builtin';
434
+ let fallbackReason = '';
435
+ if (args.online === true) {
436
+ try {
437
+ const fetched = await raceAbort((deps.fetchVoices ?? fetchEdgeVoices)({ fetchImpl: getProxyFetch(cfg.proxyUrl) ?? globalThis.fetch, signal }, cfg.timeoutMs), signal);
438
+ throwIfAborted(signal);
439
+ if (Array.isArray(fetched) && fetched.length > 0) {
440
+ sourceVoices = fetched;
441
+ source = 'edge-online';
442
+ }
443
+ else {
444
+ source = 'builtin-fallback';
445
+ fallbackReason = '在线音色目录返回为空';
446
+ }
447
+ }
448
+ catch (error) {
449
+ throwIfAborted(signal);
450
+ source = 'builtin-fallback';
451
+ fallbackReason = error instanceof Error ? error.message : String(error);
452
+ }
453
+ }
454
+ const voices = hasFilter ? filterVoices({ locale, gender, tag }, sourceVoices) : sourceVoices;
455
+ const personas = args.includePersonas === false ? [] : VOICE_PERSONAS;
456
+ const customVoices = cfg.customVoices.map((c) => ({
457
+ name: c.name,
458
+ voice: c.voice ?? '',
459
+ persona: c.persona ?? '',
460
+ hasReferenceAudio: Boolean(c.referenceAudio),
461
+ }));
462
+ return {
463
+ count: voices.length,
464
+ voices,
465
+ source,
466
+ personas,
467
+ customVoices,
468
+ ...(fallbackReason !== '' ? { fallbackReason } : {}),
469
+ };
294
470
  },
295
471
  };
296
472
  const voiceTts = {
297
473
  name: 'voice_tts',
298
474
  isConcurrencySafe: () => !getCfg().overwrite,
299
- description: '文字转语音:默认调用 edge-tts(微软 Edge 朗读服务,免费)合成 MP3,也可在设置中切换 OpenAI/SiliconFlow/自定义 TTS 引擎。支持直接传 text(自动分段支持至 100000 字符)、读取工作区 inputFile(自动清理 Markdown)、多角色播客 segments 及导出 .srt/.vtt 字幕;输出默认 voice_output.mp3(同名自动加序号)。',
475
+ description: '文字转语音:默认调用 edge-tts(微软 Edge 朗读服务,免费)合成 MP3,也可在设置中切换 OpenAI/SiliconFlow/自定义 TTS 引擎。支持内置角色人设 persona、自然语言情绪指令 instructions、5–10 秒参考音频零样本克隆 referenceAudio、多角色播客 segments、读取工作区 inputFile(自动清理 Markdown)、长文自动分段(≤100000 字符)、导出 .srt/.vtt 字幕与 -16 LUFS 响度均衡 normalizeLoudness;输出默认 voice_output.mp3。',
300
476
  parameters: compileParameters({
301
477
  text: { type: 'string', description: '要合成的文本(若提供 inputFile 或 segments 则可选;支持长文本自动分段,≤100000 字符)。' },
302
478
  inputFile: { type: 'string', description: '工作区内文稿文件路径(可选,如 article.md;指定时直接从文件读取)。' },
303
479
  cleanMarkdown: { type: 'boolean', description: '是否清理 Markdown 语法以便朗读(可选;inputFile 为 .md/.markdown 时默认 true)。' },
304
480
  segments: {
305
481
  type: 'array',
306
- description: '多角色对话/播客分段(可选,最多 50 段):每段可独立指定 voice/text/rate/pitch/pauseMs。',
482
+ description: '多角色对话/播客分段(可选,最多 50 段):每段可独立指定 voice/persona/text/rate/pitch/pauseMs/instructions/referenceAudio/referenceText。',
307
483
  items: {
308
484
  type: 'object',
309
485
  properties: {
310
486
  voice: { type: 'string' },
487
+ persona: { type: 'string' },
311
488
  text: { type: 'string' },
312
489
  rate: { type: 'string' },
313
490
  pitch: { type: 'string' },
314
491
  pauseMs: { type: 'number' },
492
+ instructions: { type: 'string' },
493
+ referenceAudio: { type: 'string' },
494
+ referenceText: { type: 'string' },
315
495
  },
316
496
  required: ['text'],
317
497
  },
318
498
  },
319
- voice: { type: 'string', description: '音色 id(可选,默认配置的 ttsVoice)。' },
499
+ voice: { type: 'string', description: '音色 id 或自定义音色别名(可选,默认配置的 ttsVoice)。' },
500
+ persona: { type: 'string', description: '内置角色人设 ID/标签(如 late-night-radio、anime-boy)或自定义音色别名(可选)。' },
320
501
  rate: { type: 'string', description: '语速,如 +20% 或 -10%(可选)。' },
321
502
  pitch: { type: 'string', description: '音调,如 +2Hz 或 -1Hz(可选)。' },
503
+ instructions: { type: 'string', description: '自然语言情绪/语气指令(可选,OpenAI gpt-4o-mini-tts 与 SiliconFlow CosyVoice2 可用,如“用开心轻快的语气说”,支持 [laughter] / [breath])。' },
504
+ referenceAudio: { type: 'string', description: '零样本克隆参考音频路径(可选,会话工作区内 5–10 秒干净人声,≤10MB;需 siliconflow 或 custom 引擎)。' },
505
+ referenceText: { type: 'string', description: '参考音频对应的原始台词文本(可选,零样本克隆推荐填写)。' },
506
+ normalizeLoudness: { type: 'boolean', default: false, description: '是否在合成后通过 ffmpeg 执行 -16 LUFS 播客响度均衡(可选,默认 false)。' },
322
507
  output: { type: 'string', description: '输出 MP3 路径(可选,相对路径按会话工作目录解析)。' },
323
508
  subtitleOutput: { type: 'string', description: '导出同步字幕文件路径(可选,.srt 或 .vtt,相对路径按会话工作目录解析)。' },
324
509
  }),
@@ -327,7 +512,8 @@ export function buildVoiceTools(config, deps = {}) {
327
512
  render: (_args, value) => {
328
513
  const rec = asRecord(value);
329
514
  const chunksInfo = typeof rec.chunks === 'number' && rec.chunks > 1 ? ',共 ' + rec.chunks + ' 段' : '';
330
- const lines = ['语音合成完成:' + rec.output + '(' + rec.bytes + ' 字节,音色 ' + rec.voice + chunksInfo + ')'];
515
+ const voiceLabel = typeof rec.voice === 'string' && rec.voice !== '' ? rec.voice : '参考音频克隆';
516
+ const lines = ['语音合成完成:' + rec.output + '(' + rec.bytes + ' 字节,音色 ' + voiceLabel + chunksInfo + ')'];
331
517
  const subtitleFile = typeof rec.subtitleFile === 'string' ? rec.subtitleFile : '';
332
518
  if (subtitleFile !== '')
333
519
  lines.push('字幕文件已写入:' + subtitleFile);
@@ -340,10 +526,14 @@ export function buildVoiceTools(config, deps = {}) {
340
526
  throwIfAborted(signal);
341
527
  const args = asRecord(rawArgs);
342
528
  const cwd = sessionCwd(exec);
343
- const useEdge = cfg.ttsEngine === 'edge' || deps.tts !== undefined || deps.ttsWithMeta !== undefined;
344
- const defaultVoice = optionalString(args, 'voice') ?? cfg.ttsVoice;
345
- const defaultRate = optionalString(args, 'rate') ?? cfg.ttsRate;
346
- const defaultPitch = optionalString(args, 'pitch') ?? cfg.ttsPitch;
529
+ const topVoice = optionalString(args, 'voice');
530
+ const topPersona = optionalString(args, 'persona');
531
+ const topRate = optionalString(args, 'rate');
532
+ const topPitch = optionalString(args, 'pitch');
533
+ const topInstructions = optionalString(args, 'instructions');
534
+ const topReferenceAudio = optionalString(args, 'referenceAudio');
535
+ const topReferenceText = optionalString(args, 'referenceText');
536
+ const normalizeLoudness = args.normalizeLoudness === true;
347
537
  const requested = optionalString(args, 'output');
348
538
  const subtitleOutput = optionalString(args, 'subtitleOutput');
349
539
  const needSubtitles = subtitleOutput !== undefined;
@@ -352,7 +542,15 @@ export function buildVoiceTools(config, deps = {}) {
352
542
  if (rawSegments.length > MAX_TTS_SEGMENTS) {
353
543
  throw new Error('segments 最多 ' + MAX_TTS_SEGMENTS + ' 段(当前 ' + rawSegments.length + ' 段)。');
354
544
  }
355
- assertTtsEngineReady(cfg, useEdge);
545
+ const topSpec = resolveEffectiveVoiceSpec(cfg, cwd, {
546
+ voice: topVoice,
547
+ persona: topPersona,
548
+ rate: topRate,
549
+ pitch: topPitch,
550
+ instructions: topInstructions,
551
+ referenceAudio: topReferenceAudio,
552
+ referenceText: topReferenceText,
553
+ });
356
554
  const parsedSegments = [];
357
555
  let totalChars = 0;
358
556
  for (let i = 0; i < rawSegments.length; i++) {
@@ -364,16 +562,72 @@ export function buildVoiceTools(config, deps = {}) {
364
562
  if (segText === '')
365
563
  throw new Error('第 ' + (i + 1) + ' 段清理 Markdown 后文本为空。');
366
564
  totalChars += segText.length;
367
- const segVoice = optionalString(seg, 'voice') ?? defaultVoice;
368
- const segRate = optionalString(seg, 'rate') ?? defaultRate;
369
- const segPitch = optionalString(seg, 'pitch') ?? defaultPitch;
370
- assertTtsVoice(segVoice, useEdge);
371
- assertProsody(segRate, segPitch);
372
- const pauseMs = typeof seg.pauseMs === 'number' && Number.isFinite(seg.pauseMs) && seg.pauseMs >= 0
565
+ const segVoice = optionalString(seg, 'voice');
566
+ const segPersona = optionalString(seg, 'persona');
567
+ const segRate = optionalString(seg, 'rate');
568
+ const segPitch = optionalString(seg, 'pitch');
569
+ const segPauseMs = typeof seg.pauseMs === 'number' && Number.isFinite(seg.pauseMs) && seg.pauseMs >= 0
373
570
  ? Math.min(10000, Math.round(seg.pauseMs))
374
- : 300;
571
+ : undefined;
572
+ const segInstructions = optionalString(seg, 'instructions');
573
+ const segReferenceAudio = optionalString(seg, 'referenceAudio');
574
+ const segReferenceText = optionalString(seg, 'referenceText');
575
+ let segSpec;
576
+ if (segVoice !== undefined || segPersona !== undefined) {
577
+ segSpec = resolveEffectiveVoiceSpec(cfg, cwd, {
578
+ voice: segVoice,
579
+ persona: segPersona,
580
+ rate: segRate ?? topRate,
581
+ pitch: segPitch ?? topPitch,
582
+ pauseMs: segPauseMs,
583
+ instructions: segInstructions ?? topInstructions,
584
+ referenceAudio: segReferenceAudio ?? topReferenceAudio,
585
+ referenceText: segReferenceText ?? topReferenceText,
586
+ });
587
+ }
588
+ else if (segReferenceAudio !== undefined) {
589
+ segSpec = resolveEffectiveVoiceSpec(cfg, cwd, {
590
+ voice: topVoice,
591
+ persona: topPersona,
592
+ rate: segRate ?? topRate,
593
+ pitch: segPitch ?? topPitch,
594
+ pauseMs: segPauseMs,
595
+ instructions: segInstructions ?? topInstructions,
596
+ referenceAudio: segReferenceAudio,
597
+ referenceText: segReferenceText ?? topReferenceText,
598
+ });
599
+ }
600
+ else {
601
+ const reusedRefs = topSpec.references !== undefined && segReferenceText !== undefined
602
+ ? topSpec.references.map((r) => ({ audioDataUri: r.audioDataUri, text: segReferenceText }))
603
+ : topSpec.references;
604
+ segSpec = {
605
+ voice: topSpec.voice,
606
+ rate: segRate ?? topSpec.rate,
607
+ pitch: segPitch ?? topSpec.pitch,
608
+ pauseMs: segPauseMs ?? topSpec.pauseMs,
609
+ ...(segInstructions !== undefined || topSpec.instructions !== undefined
610
+ ? { instructions: segInstructions ?? topSpec.instructions }
611
+ : {}),
612
+ ...(reusedRefs !== undefined ? { references: reusedRefs } : {}),
613
+ hasReferenceAudio: topSpec.hasReferenceAudio,
614
+ };
615
+ }
616
+ const segUseEdge = resolveUseEdge(cfg, segSpec.hasReferenceAudio);
617
+ assertTtsEngineReady(cfg, segUseEdge);
618
+ assertTtsVoice(segSpec.voice, segUseEdge, segSpec.references !== undefined);
619
+ assertProsody(segSpec.rate, segSpec.pitch);
375
620
  const chunks = segText.length > 4000 ? splitTextIntoChunks(segText, 2800) : [segText];
376
- parsedSegments.push({ chunks, voice: segVoice, rate: segRate, pitch: segPitch, pauseMs });
621
+ parsedSegments.push({
622
+ chunks,
623
+ voice: segSpec.voice,
624
+ rate: segSpec.rate,
625
+ pitch: segSpec.pitch,
626
+ pauseMs: segSpec.pauseMs,
627
+ useEdge: segUseEdge,
628
+ instructions: segSpec.instructions,
629
+ references: segSpec.references,
630
+ });
377
631
  }
378
632
  if (totalChars > MAX_TTS_CHARS) {
379
633
  throw new Error('segments 总文本超过 ' + MAX_TTS_CHARS + ' 字符上限(当前 ' + totalChars + ' 字符)。');
@@ -385,10 +639,19 @@ export function buildVoiceTools(config, deps = {}) {
385
639
  for (let s = 0; s < parsedSegments.length; s++) {
386
640
  const seg = parsedSegments[s];
387
641
  for (const chunkText of seg.chunks) {
388
- tasks.push({ segIndex: s, text: chunkText, voice: seg.voice, rate: seg.rate, pitch: seg.pitch });
642
+ tasks.push({
643
+ segIndex: s,
644
+ text: chunkText,
645
+ voice: seg.voice,
646
+ rate: seg.rate,
647
+ pitch: seg.pitch,
648
+ useEdge: seg.useEdge,
649
+ instructions: seg.instructions,
650
+ references: seg.references,
651
+ });
389
652
  }
390
653
  }
391
- const chunkResults = await mapLimit(tasks, TTS_CHUNK_CONCURRENCY, signal, (task) => synthesizeChunk(cfg, useEdge, task.text, task.voice, task.rate, task.pitch, needSubtitles, signal));
654
+ const chunkResults = await mapLimit(tasks, TTS_CHUNK_CONCURRENCY, signal, (task) => synthesizeChunk(cfg, task.useEdge, task.text, task.voice, task.rate, task.pitch, needSubtitles, signal, task.instructions, task.references));
392
655
  throwIfAborted(signal);
393
656
  const buffers = [];
394
657
  const allCues = [];
@@ -417,14 +680,15 @@ export function buildVoiceTools(config, deps = {}) {
417
680
  }
418
681
  }
419
682
  }
420
- const audio = buffers.length === 1 ? buffers[0] : concatMp3Buffers(buffers);
683
+ let audio = buffers.length === 1 ? buffers[0] : concatMp3Buffers(buffers);
684
+ audio = await maybeNormalizeAudio(normalizeLoudness, audio, signal);
421
685
  const output = writeWorkspaceFile(resolveOutputPath(requested, 'voice_output.mp3', cfg.overwrite, cwd), audio, cwd, undefined, cfg.overwrite);
422
686
  let subtitleFile = '';
423
687
  if (subtitleOutput !== undefined) {
424
688
  const formatted = formatSubtitles(allCues, subtitleFormatOf(subtitleOutput));
425
689
  subtitleFile = writeWorkspaceFile(resolveOutputPath(subtitleOutput, '', cfg.overwrite, cwd), formatted, cwd, undefined, cfg.overwrite);
426
690
  }
427
- return { output, bytes: audio.length, voice: defaultVoice, rate: defaultRate, pitch: defaultPitch, textLength: totalChars, chunks: tasks.length, subtitleFile };
691
+ return { output, bytes: audio.length, voice: topSpec.voice, rate: topSpec.rate, pitch: topSpec.pitch, textLength: totalChars, chunks: tasks.length, subtitleFile };
428
692
  }
429
693
  const inputFile = optionalString(args, 'inputFile');
430
694
  let finalText;
@@ -448,9 +712,19 @@ export function buildVoiceTools(config, deps = {}) {
448
712
  if (finalText.length > MAX_TTS_CHARS) {
449
713
  throw new Error('文本超过 ' + MAX_TTS_CHARS + ' 字符上限(当前 ' + finalText.length + ' 字符),请拆分处理。');
450
714
  }
715
+ const spec = resolveEffectiveVoiceSpec(cfg, cwd, {
716
+ voice: topVoice,
717
+ persona: topPersona,
718
+ rate: topRate,
719
+ pitch: topPitch,
720
+ instructions: topInstructions,
721
+ referenceAudio: topReferenceAudio,
722
+ referenceText: topReferenceText,
723
+ });
724
+ const useEdge = resolveUseEdge(cfg, spec.hasReferenceAudio);
451
725
  assertTtsEngineReady(cfg, useEdge);
452
- assertTtsVoice(defaultVoice, useEdge);
453
- assertProsody(defaultRate, defaultPitch);
726
+ assertTtsVoice(spec.voice, useEdge, spec.references !== undefined);
727
+ assertProsody(spec.rate, spec.pitch);
454
728
  resolveOutputPath(requested, 'voice_output.mp3', cfg.overwrite, cwd);
455
729
  if (subtitleOutput !== undefined)
456
730
  resolveOutputPath(subtitleOutput, '', cfg.overwrite, cwd);
@@ -458,13 +732,13 @@ export function buildVoiceTools(config, deps = {}) {
458
732
  let chunkCount = 1;
459
733
  let subtitleFile = '';
460
734
  if (finalText.length <= 5000 && !needSubtitles && useEdge) {
461
- const res = await synthesizeChunk(cfg, true, finalText, defaultVoice, defaultRate, defaultPitch, false, signal);
735
+ const res = await synthesizeChunk(cfg, true, finalText, spec.voice, spec.rate, spec.pitch, false, signal, spec.instructions, spec.references);
462
736
  audio = res.audio;
463
737
  }
464
738
  else {
465
739
  const chunks = splitTextIntoChunks(finalText, 2800);
466
740
  chunkCount = chunks.length;
467
- const results = await mapLimit(chunks, TTS_CHUNK_CONCURRENCY, signal, (chunk) => synthesizeChunk(cfg, useEdge, chunk, defaultVoice, defaultRate, defaultPitch, needSubtitles, signal));
741
+ const results = await mapLimit(chunks, TTS_CHUNK_CONCURRENCY, signal, (chunk) => synthesizeChunk(cfg, useEdge, chunk, spec.voice, spec.rate, spec.pitch, needSubtitles, signal, spec.instructions, spec.references));
468
742
  throwIfAborted(signal);
469
743
  audio = results.length === 1 ? results[0].audio : concatMp3Buffers(results.map((r) => r.audio));
470
744
  if (subtitleOutput !== undefined) {
@@ -484,8 +758,9 @@ export function buildVoiceTools(config, deps = {}) {
484
758
  }
485
759
  }
486
760
  throwIfAborted(signal);
761
+ audio = await maybeNormalizeAudio(normalizeLoudness, audio, signal);
487
762
  const output = writeWorkspaceFile(resolveOutputPath(requested, 'voice_output.mp3', cfg.overwrite, cwd), audio, cwd, undefined, cfg.overwrite);
488
- return { output, bytes: audio.length, voice: defaultVoice, rate: defaultRate, pitch: defaultPitch, textLength: finalText.length, chunks: chunkCount, subtitleFile };
763
+ return { output, bytes: audio.length, voice: spec.voice, rate: spec.rate, pitch: spec.pitch, textLength: finalText.length, chunks: chunkCount, subtitleFile };
489
764
  },
490
765
  get timeoutMs() { return getCfg().timeoutMs + 10000; },
491
766
  };
@@ -669,9 +944,9 @@ export function buildVoiceTools(config, deps = {}) {
669
944
  const voicePreview = {
670
945
  name: 'voice_preview',
671
946
  isConcurrencySafe: () => !getCfg().overwrite,
672
- description: '音色试听:用一段固定试听文本批量生成短样例 MP3,并默认生成可直接在浏览器试听对比的 index.html。voices 为音色 id 数组(可选,缺省 voice_list 前 4 个,最多 8 个);text 可自定义(≤200 字符);样例文件写入输出目录(默认会话工作目录 voice_previews)。单个音色失败不阻断其他。',
947
+ description: '音色试听:用一段固定试听文本批量生成短样例 MP3,并默认生成可直接在浏览器试听对比的 index.html。voices 支持音色 id、内置角色人设(persona)或自定义音色别名(customVoices)数组(可选,缺省 voice_list 前 4 个,最多 8 个);text 可自定义(≤200 字符);样例文件写入输出目录(默认会话工作目录 voice_previews)。单个音色失败不阻断其他。',
673
948
  parameters: compileParameters({
674
- voices: { type: 'array', items: { type: 'string' }, description: '音色 id 数组(可选,缺省 voice_list 前 4 个,最多 8 个)。' },
949
+ voices: { type: 'array', items: { type: 'string' }, description: '音色 id、内置人设 ID/标签(如 late-night-radio、anime-boy)或自定义音色别名数组(可选,缺省 voice_list 前 4 个,最多 8 个)。' },
675
950
  text: { type: 'string', description: '试听文本(可选,默认中英混合试听句,≤200 字符)。' },
676
951
  outputDir: { type: 'string', description: '输出目录(可选,默认会话工作目录下 voice_previews)。' },
677
952
  htmlIndex: { type: 'boolean', default: true, description: '是否在输出目录生成可试听的 index.html 试听页(默认 true)。' },
@@ -711,30 +986,33 @@ export function buildVoiceTools(config, deps = {}) {
711
986
  const text = optionalString(args, 'text') ?? DEFAULT_PREVIEW_TEXT;
712
987
  if (text.length > 200)
713
988
  throw new Error('试听文本请控制在 200 字以内(试听要短平快)。');
714
- const useEdge = cfg.ttsEngine === 'edge' || deps.tts !== undefined;
715
- assertTtsEngineReady(cfg, useEdge);
989
+ assertTtsEngineReady(cfg, resolveUseEdge(cfg, false));
716
990
  const cwd = sessionCwd(exec);
717
991
  const outDir = ensureWorkspaceDirectory(optionalString(args, 'outputDir') ?? 'voice_previews', cwd);
718
- const outcomes = await mapLimit(targets, PREVIEW_CONCURRENCY, signal, async (voice) => {
992
+ const outcomes = await mapLimit(targets, PREVIEW_CONCURRENCY, signal, async (target) => {
719
993
  throwIfAborted(signal);
720
- if (useEdge && !isValidVoiceId(voice)) {
721
- return { voice, error: '音色 id 不合法(应为 zh-CN-XXXNeural 形式的 edge 音色)' };
722
- }
723
- if (!useEdge && voice.trim() === '') {
724
- return { voice, error: '音色 id 不合法:不能为空' };
725
- }
726
994
  try {
727
- const { audio } = await synthesizeChunk(cfg, useEdge, text, voice, cfg.ttsRate, cfg.ttsPitch, false, signal);
995
+ const spec = resolveEffectiveVoiceSpec(cfg, cwd, { voice: target });
996
+ const targetUseEdge = resolveUseEdge(cfg, spec.hasReferenceAudio);
997
+ assertTtsEngineReady(cfg, targetUseEdge);
998
+ if (targetUseEdge && !isValidVoiceId(spec.voice)) {
999
+ return { voice: target, error: '音色 id 不合法(应为 zh-CN-XXXNeural 形式的 edge 音色)' };
1000
+ }
1001
+ if (!targetUseEdge && spec.voice.trim() === '' && (spec.references === undefined || spec.references.length === 0)) {
1002
+ return { voice: target, error: '音色 id 不合法:不能为空' };
1003
+ }
1004
+ assertProsody(spec.rate, spec.pitch);
1005
+ const { audio } = await synthesizeChunk(cfg, targetUseEdge, text, spec.voice, spec.rate, spec.pitch, false, signal, spec.instructions, spec.references);
728
1006
  throwIfAborted(signal);
729
- const name = 'voice-preview-' + voice.replace(/[^a-zA-Z0-9-]/g, '_') + '.mp3';
1007
+ const name = 'voice-preview-' + target.replace(/[^a-zA-Z0-9-\u4e00-\u9fa5]/g, '_') + '.mp3';
730
1008
  // 复用 resolveOutputPath:overwrite=false 时改名加序号,不再直接覆盖同名样例。
731
1009
  const file = resolveOutputPath(join(outDir, name), '', cfg.overwrite, cwd);
732
1010
  const output = writeWorkspaceFile(file, audio, cwd, undefined, cfg.overwrite);
733
- return { voice, output, bytes: audio.length };
1011
+ return { voice: target, output, bytes: audio.length };
734
1012
  }
735
1013
  catch (error) {
736
1014
  throwIfAborted(signal);
737
- return { voice, error: error instanceof Error ? error.message : String(error) };
1015
+ return { voice: target, error: error instanceof Error ? error.message : String(error) };
738
1016
  }
739
1017
  });
740
1018
  const samples = [];
@@ -751,11 +1029,33 @@ export function buildVoiceTools(config, deps = {}) {
751
1029
  const htmlSamples = samples.map((s) => {
752
1030
  const id = String(s.voice);
753
1031
  const meta = voiceMap.get(id);
1032
+ if (meta !== undefined) {
1033
+ return {
1034
+ voice: id,
1035
+ fileName: basename(String(s.output)),
1036
+ locale: meta.locale,
1037
+ gender: meta.gender,
1038
+ };
1039
+ }
1040
+ const persona = resolvePersona(id);
1041
+ if (persona !== undefined) {
1042
+ return {
1043
+ voice: id,
1044
+ fileName: basename(String(s.output)),
1045
+ locale: persona.label + '(' + persona.voice + ')',
1046
+ };
1047
+ }
1048
+ const alias = resolveCustomVoice(cfg.customVoices, id);
1049
+ if (alias !== undefined) {
1050
+ return {
1051
+ voice: id,
1052
+ fileName: basename(String(s.output)),
1053
+ locale: '自定义音色' + (alias.voice ? '(' + alias.voice + ')' : ''),
1054
+ };
1055
+ }
754
1056
  return {
755
1057
  voice: id,
756
1058
  fileName: basename(String(s.output)),
757
- locale: meta?.locale,
758
- gender: meta?.gender,
759
1059
  };
760
1060
  });
761
1061
  const html = renderPreviewHtml(htmlSamples, text);
@@ -809,7 +1109,11 @@ export function buildVoiceTools(config, deps = {}) {
809
1109
  const ttsHints = [];
810
1110
  const sttHints = [];
811
1111
  // 1. TTS 音色(保持 checks[0] 以兼容既有测试对 checks[0].detail 的断言)
812
- const voiceOk = cfg.ttsEngine === 'edge' ? isValidVoiceId(cfg.ttsVoice) : cfg.ttsVoice.trim() !== '';
1112
+ const matchedAlias = resolveCustomVoice(cfg.customVoices, cfg.ttsVoice);
1113
+ const matchedPersona = resolvePersona(cfg.ttsVoice);
1114
+ const voiceOk = cfg.ttsEngine === 'edge'
1115
+ ? (isValidVoiceId(cfg.ttsVoice) || matchedAlias !== undefined || matchedPersona !== undefined)
1116
+ : cfg.ttsVoice.trim() !== '';
813
1117
  checks.push({
814
1118
  name: 'TTS 音色',
815
1119
  ok: voiceOk,