dsh-voice 0.8.1 → 0.9.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/tts-text.d.ts CHANGED
@@ -12,16 +12,31 @@ export declare function splitTextIntoChunks(text: string, maxChars?: number): st
12
12
  * 若 MP3 缓冲以 ID3v2 标签头开头,剥离其标签头(及可选 footer),避免多段拼接后在流中残留 ID3 头。
13
13
  */
14
14
  export declare function stripId3v2(mp3: Buffer): Buffer;
15
+ /** MP3 音频元信息(由帧头 / Xing / Info / VBRI 解析得出)。 */
16
+ export interface Mp3AudioInfo {
17
+ durationMs: number;
18
+ sampleRate: number;
19
+ channels: 1 | 2;
20
+ bitrateKbps: number;
21
+ isVbr: boolean;
22
+ frameCount: number;
23
+ }
15
24
  /**
16
- * 生成合法的 MPEG-2 Layer III(24kHz 48kbps 单声道)静音 MP3 帧,每帧 144 字节 / 24ms。
25
+ * 精确解析 MP3 缓冲的采样率、声道、比特率、帧数与时长;
26
+ * 支持 ID3v2 / ID3v1 剥离、Xing / Info / VBRI VBR 头与逐帧扫描;
27
+ * 对非真实 MP3 帧的测试占位缓冲按 48kbps 估算兜底。
17
28
  */
18
- export declare function createSilenceMp3(durationMs: number): Buffer;
29
+ export declare function inspectMp3Buffer(mp3: Buffer): Mp3AudioInfo;
30
+ /**
31
+ * 生成匹配目标采样率的合法单声道静音 MP3 帧(默认 24000Hz MPEG-2 48kbps 144B/24ms)。
32
+ */
33
+ export declare function createSilenceMp3(durationMs: number, sampleRate?: number): Buffer;
19
34
  /**
20
35
  * 拼接多段 MP3:保留首段完整头部,后续段剥离 ID3v2 后拼接。
21
36
  */
22
37
  export declare function concatMp3Buffers(buffers: Buffer[]): Buffer;
23
38
  /**
24
- * 按 48kbps(6 字节/毫秒)估算 MP3 音频时长(毫秒)。
39
+ * 精确计算 MP3 音频时长(毫秒);非真实 MP3 帧的占位缓冲回退按 48kbps 估算。
25
40
  */
26
41
  export declare function estimateMp3DurationMs(mp3: Buffer): number;
27
42
  /**
@@ -41,8 +56,36 @@ export declare function renderPreviewHtml(samples: Array<{
41
56
  locale?: string;
42
57
  gender?: string;
43
58
  }>, text: string): string;
59
+ /**
60
+ * 解析 SRT 或 WebVTT 字幕文件为按开始时间排序的 SubtitleCue 数组(1-based 索引)。
61
+ */
62
+ export declare function parseSubtitleFile(content: string): SubtitleCue[];
63
+ /**
64
+ * 将基础语速百分比(如 `+10%`)乘以缩放因子并钳制在 `[0.7, 1.85]`(`-30%` 至 `+85%`),返回 `'+25%'` / `'-10%'` 格式。
65
+ */
66
+ export declare function scaleRatePercent(baseRate: string, factor: number): string;
67
+ /**
68
+ * 纯文本单遍发音词典替换(用于不支持 SSML `<sub alias>` 的 OpenAI / SiliconFlow 引擎)。
69
+ * 按原词长度降序构造单次正则同步替换,保证替读结果不会递归触发其它规则。
70
+ */
71
+ export declare function applyPronunciationsPlain(text: string, rules: ReadonlyArray<{
72
+ word: string;
73
+ alias: string;
74
+ }>): string;
44
75
  /**
45
76
  * 使用本地 ffmpeg 对 MP3 音频执行播客级响度均衡(-16 LUFS / TP -1.5 dBTP / LRA 11)。
46
77
  * @throws 取消时抛出 signal.reason,ffmpeg 失败时抛中文错误。
47
78
  */
48
79
  export declare function normalizeAudioLoudness(mp3: Buffer, signal?: AbortSignal): Promise<Buffer>;
80
+ /** 播客 BGM 混音与自动闪避选项。 */
81
+ export interface BgmMixOptions {
82
+ bgmPath: string;
83
+ bgmVolume?: number;
84
+ ducking?: boolean;
85
+ normalizeLoudness?: boolean;
86
+ }
87
+ /**
88
+ * 使用本地 ffmpeg 将人声 MP3 与背景音乐混音:
89
+ * 自动循环 BGM、按人声侧链压缩闪避(ducking)、在结尾 1.2s 平滑淡出(总长 > 3s),并可选联动响度均衡。
90
+ */
91
+ export declare function mixAudioWithBgm(voiceMp3: Buffer, opts: BgmMixOptions, signal?: AbortSignal): Promise<Buffer>;
package/lib/tts-text.js CHANGED
@@ -132,21 +132,187 @@ export function stripId3v2(mp3) {
132
132
  return mp3;
133
133
  return mp3.subarray(totalHeader);
134
134
  }
135
+ const MPEG1_BITRATES = [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320];
136
+ const MPEG2_BITRATES = [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160];
137
+ const SAMPLE_RATES_BY_VERSION = {
138
+ 3: [44100, 48000, 32000], // MPEG-1
139
+ 2: [22050, 24000, 16000], // MPEG-2
140
+ 0: [11025, 12000, 8000], // MPEG-2.5
141
+ };
142
+ function parseMp3FrameHeader(buf, offset) {
143
+ if (offset + 4 > buf.length)
144
+ return null;
145
+ if (buf[offset] !== 0xff || (buf[offset + 1] & 0xe0) !== 0xe0)
146
+ return null;
147
+ const b1 = buf[offset + 1];
148
+ const b2 = buf[offset + 2];
149
+ const b3 = buf[offset + 3];
150
+ const versionBits = (b1 >> 3) & 3;
151
+ if (versionBits === 1)
152
+ return null; // reserved
153
+ const layerBits = (b1 >> 1) & 3;
154
+ if (layerBits !== 1)
155
+ return null; // Layer III only
156
+ const bitrateIdx = (b2 >> 4) & 0x0f;
157
+ if (bitrateIdx === 0 || bitrateIdx === 15)
158
+ return null;
159
+ const sampleRateIdx = (b2 >> 2) & 3;
160
+ if (sampleRateIdx === 3)
161
+ return null;
162
+ const isMpeg1 = versionBits === 3;
163
+ const bitrateKbps = isMpeg1 ? MPEG1_BITRATES[bitrateIdx] : MPEG2_BITRATES[bitrateIdx];
164
+ const sampleRate = SAMPLE_RATES_BY_VERSION[versionBits][sampleRateIdx];
165
+ const padding = (b2 >> 1) & 1;
166
+ const channelMode = (b3 >> 6) & 3;
167
+ const channels = channelMode === 3 ? 1 : 2;
168
+ const samplesPerFrame = isMpeg1 ? 1152 : 576;
169
+ const frameSize = Math.floor(((isMpeg1 ? 144 : 72) * bitrateKbps * 1000) / sampleRate) + padding;
170
+ if (frameSize < 4 || offset + frameSize > buf.length)
171
+ return null;
172
+ const sideInfoSize = isMpeg1 ? (channels === 1 ? 17 : 32) : (channels === 1 ? 9 : 17);
173
+ return { versionBits, sampleRate, channels, bitrateKbps, samplesPerFrame, frameSize, sideInfoSize };
174
+ }
175
+ function stripId3v1(buf) {
176
+ if (buf.length >= 128 && buf[buf.length - 128] === 0x54 && buf[buf.length - 127] === 0x41 && buf[buf.length - 126] === 0x47) {
177
+ return buf.subarray(0, buf.length - 128);
178
+ }
179
+ return buf;
180
+ }
181
+ /**
182
+ * 精确解析 MP3 缓冲的采样率、声道、比特率、帧数与时长;
183
+ * 支持 ID3v2 / ID3v1 剥离、Xing / Info / VBRI VBR 头与逐帧扫描;
184
+ * 对非真实 MP3 帧的测试占位缓冲按 48kbps 估算兜底。
185
+ */
186
+ export function inspectMp3Buffer(mp3) {
187
+ const afterId3v2 = stripId3v2(mp3);
188
+ const data = stripId3v1(afterId3v2);
189
+ let offset = 0;
190
+ let frameCount = 0;
191
+ let totalDurationMs = 0;
192
+ let bitrateSum = 0;
193
+ let firstSampleRate = 24000;
194
+ let firstChannels = 1;
195
+ let firstBitrate = 48;
196
+ let isVbr = false;
197
+ while (offset + 4 <= data.length) {
198
+ // 跳过拼接流中可能残留的 ID3v2 标签头
199
+ if (data[offset] === 0x49 && data[offset + 1] === 0x44 && data[offset + 2] === 0x33 && offset + 10 <= data.length) {
200
+ const stripped = stripId3v2(data.subarray(offset));
201
+ const skipped = data.length - offset - stripped.length;
202
+ if (skipped > 0) {
203
+ offset += skipped;
204
+ continue;
205
+ }
206
+ }
207
+ const header = parseMp3FrameHeader(data, offset);
208
+ if (header === null) {
209
+ offset += 1;
210
+ continue;
211
+ }
212
+ if (frameCount === 0) {
213
+ firstSampleRate = header.sampleRate;
214
+ firstChannels = header.channels;
215
+ firstBitrate = header.bitrateKbps;
216
+ const xingOffset = offset + 4 + header.sideInfoSize;
217
+ if (xingOffset + 12 <= offset + header.frameSize) {
218
+ const tag = data.subarray(xingOffset, xingOffset + 4).toString('ascii');
219
+ if (tag === 'Xing' || tag === 'Info') {
220
+ const flags = data.readUInt32BE(xingOffset + 4);
221
+ if ((flags & 0x01) !== 0 && xingOffset + 12 <= data.length) {
222
+ const totalFrames = data.readUInt32BE(xingOffset + 8);
223
+ if (totalFrames > 0) {
224
+ const durationMs = Math.round((totalFrames * header.samplesPerFrame * 1000) / header.sampleRate);
225
+ let avgBitrate = header.bitrateKbps;
226
+ if ((flags & 0x02) !== 0 && xingOffset + 16 <= data.length && durationMs > 0) {
227
+ const totalBytes = data.readUInt32BE(xingOffset + 12);
228
+ if (totalBytes > 0)
229
+ avgBitrate = Math.round((totalBytes * 8) / durationMs);
230
+ }
231
+ return {
232
+ durationMs,
233
+ sampleRate: header.sampleRate,
234
+ channels: header.channels,
235
+ bitrateKbps: avgBitrate,
236
+ isVbr: tag === 'Xing',
237
+ frameCount: totalFrames,
238
+ };
239
+ }
240
+ }
241
+ }
242
+ }
243
+ const vbriOffset = offset + 36;
244
+ if (vbriOffset + 18 <= offset + header.frameSize && vbriOffset + 18 <= data.length) {
245
+ const vbriTag = data.subarray(vbriOffset, vbriOffset + 4).toString('ascii');
246
+ if (vbriTag === 'VBRI') {
247
+ const totalBytes = data.readUInt32BE(vbriOffset + 10);
248
+ const totalFrames = data.readUInt32BE(vbriOffset + 14);
249
+ if (totalFrames > 0) {
250
+ const durationMs = Math.round((totalFrames * header.samplesPerFrame * 1000) / header.sampleRate);
251
+ const avgBitrate = totalBytes > 0 && durationMs > 0
252
+ ? Math.round((totalBytes * 8) / durationMs)
253
+ : header.bitrateKbps;
254
+ return {
255
+ durationMs,
256
+ sampleRate: header.sampleRate,
257
+ channels: header.channels,
258
+ bitrateKbps: avgBitrate,
259
+ isVbr: true,
260
+ frameCount: totalFrames,
261
+ };
262
+ }
263
+ }
264
+ }
265
+ }
266
+ else if (header.bitrateKbps !== firstBitrate) {
267
+ isVbr = true;
268
+ }
269
+ frameCount += 1;
270
+ totalDurationMs += (header.samplesPerFrame * 1000) / header.sampleRate;
271
+ bitrateSum += header.bitrateKbps;
272
+ offset += header.frameSize;
273
+ }
274
+ if (frameCount === 0) {
275
+ return {
276
+ durationMs: Math.round((afterId3v2.length * 8) / 48),
277
+ sampleRate: 24000,
278
+ channels: 1,
279
+ bitrateKbps: 48,
280
+ isVbr: false,
281
+ frameCount: 0,
282
+ };
283
+ }
284
+ return {
285
+ durationMs: Math.round(totalDurationMs),
286
+ sampleRate: firstSampleRate,
287
+ channels: firstChannels,
288
+ bitrateKbps: Math.round(bitrateSum / frameCount),
289
+ isVbr,
290
+ frameCount,
291
+ };
292
+ }
293
+ const SILENCE_SPECS = {
294
+ 24000: { header: [0xff, 0xf3, 0x64, 0xc0], frameSize: 144, frameDurationMs: (576 * 1000) / 24000 },
295
+ 22050: { header: [0xff, 0xf3, 0x60, 0xc0], frameSize: 156, frameDurationMs: (576 * 1000) / 22050 },
296
+ 16000: { header: [0xff, 0xf3, 0x68, 0xc0], frameSize: 216, frameDurationMs: (576 * 1000) / 16000 },
297
+ 44100: { header: [0xff, 0xfb, 0x50, 0xc0], frameSize: 208, frameDurationMs: (1152 * 1000) / 44100 },
298
+ 48000: { header: [0xff, 0xfb, 0x54, 0xc0], frameSize: 192, frameDurationMs: (1152 * 1000) / 48000 },
299
+ 32000: { header: [0xff, 0xfb, 0x58, 0xc0], frameSize: 288, frameDurationMs: (1152 * 1000) / 32000 },
300
+ };
135
301
  /**
136
- * 生成合法的 MPEG-2 Layer III(24kHz 48kbps 单声道)静音 MP3 帧,每帧 144 字节 / 24ms。
302
+ * 生成匹配目标采样率的合法单声道静音 MP3 帧(默认 24000Hz MPEG-2 48kbps 144B/24ms)。
137
303
  */
138
- export function createSilenceMp3(durationMs) {
304
+ export function createSilenceMp3(durationMs, sampleRate = 24000) {
139
305
  if (!Number.isFinite(durationMs) || durationMs <= 0)
140
306
  return Buffer.alloc(0);
141
- const frames = Math.max(1, Math.round(durationMs / 24));
142
- const frameSize = 144;
143
- const out = Buffer.alloc(frames * frameSize);
307
+ const spec = SILENCE_SPECS[sampleRate] ?? SILENCE_SPECS[24000];
308
+ const frames = Math.max(1, Math.round(durationMs / spec.frameDurationMs));
309
+ const out = Buffer.alloc(frames * spec.frameSize);
144
310
  for (let i = 0; i < frames; i++) {
145
- const offset = i * frameSize;
146
- out[offset] = 0xff;
147
- out[offset + 1] = 0xf3;
148
- out[offset + 2] = 0x64;
149
- out[offset + 3] = 0xc0;
311
+ const offset = i * spec.frameSize;
312
+ out[offset] = spec.header[0];
313
+ out[offset + 1] = spec.header[1];
314
+ out[offset + 2] = spec.header[2];
315
+ out[offset + 3] = spec.header[3];
150
316
  }
151
317
  return out;
152
318
  }
@@ -161,10 +327,10 @@ export function concatMp3Buffers(buffers) {
161
327
  return Buffer.concat(normalized);
162
328
  }
163
329
  /**
164
- * 按 48kbps(6 字节/毫秒)估算 MP3 音频时长(毫秒)。
330
+ * 精确计算 MP3 音频时长(毫秒);非真实 MP3 帧的占位缓冲回退按 48kbps 估算。
165
331
  */
166
332
  export function estimateMp3DurationMs(mp3) {
167
- return Math.round((stripId3v2(mp3).length * 8) / 48);
333
+ return inspectMp3Buffer(mp3).durationMs;
168
334
  }
169
335
  /**
170
336
  * 平移字幕时间轴并从 startIndex 起重新编号。
@@ -315,14 +481,115 @@ export function renderPreviewHtml(samples, text) {
315
481
  '</html>',
316
482
  ].join('\n') + '\n';
317
483
  }
484
+ /**
485
+ * 清洗并解析时间戳字符串(支持 HH:MM:SS,mmm / HH:MM:SS.mmm / MM:SS.mmm)。
486
+ */
487
+ function parseSubtitleTimestampMs(raw) {
488
+ const match = /^(?:(\d{1,3}):)?(\d{1,2}):(\d{2})[.,](\d{1,3})$/.exec(raw.trim());
489
+ if (!match)
490
+ return null;
491
+ const hours = match[1] !== undefined ? Number(match[1]) : 0;
492
+ const minutes = Number(match[2]);
493
+ const seconds = Number(match[3]);
494
+ const millis = Number(match[4].padEnd(3, '0'));
495
+ if (!Number.isFinite(hours) || !Number.isFinite(minutes) || !Number.isFinite(seconds) || !Number.isFinite(millis)) {
496
+ return null;
497
+ }
498
+ return ((hours * 60 + minutes) * 60 + seconds) * 1000 + millis;
499
+ }
500
+ function stripInlineSubtitleTags(text) {
501
+ return text
502
+ .replace(/<\/?(?:v|c|b|i|u|ruby|rt|lang|font)(?=[\s.>/]|$)[^>]*>/gi, '')
503
+ .replace(/<\d{1,2}:\d{2}(?::\d{2})?[.,]\d{1,3}>/g, '');
504
+ }
505
+ /**
506
+ * 解析 SRT 或 WebVTT 字幕文件为按开始时间排序的 SubtitleCue 数组(1-based 索引)。
507
+ */
508
+ export function parseSubtitleFile(content) {
509
+ const normalized = content.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n').trim();
510
+ if (normalized === '')
511
+ return [];
512
+ const blocks = normalized.split(/\n{2,}/);
513
+ const parsed = [];
514
+ for (const block of blocks) {
515
+ const lines = block.split('\n').map((line) => line.trimEnd());
516
+ const firstNonEmpty = lines.find((line) => line.trim() !== '')?.trim() ?? '';
517
+ if (firstNonEmpty === ''
518
+ || firstNonEmpty.startsWith('WEBVTT')
519
+ || firstNonEmpty.startsWith('NOTE')
520
+ || firstNonEmpty === 'STYLE'
521
+ || firstNonEmpty === 'REGION') {
522
+ continue;
523
+ }
524
+ const timingIdx = lines.findIndex((line) => line.includes('-->'));
525
+ if (timingIdx === -1)
526
+ continue;
527
+ const timingLine = lines[timingIdx];
528
+ const arrowPos = timingLine.indexOf('-->');
529
+ const leftPart = timingLine.slice(0, arrowPos).trim();
530
+ const rightPart = timingLine.slice(arrowPos + 3).trim();
531
+ const startToken = leftPart.split(/\s+/).pop() ?? '';
532
+ const endToken = rightPart.split(/\s+/)[0] ?? '';
533
+ const startMs = parseSubtitleTimestampMs(startToken);
534
+ const endMsRaw = parseSubtitleTimestampMs(endToken);
535
+ if (startMs === null || endMsRaw === null)
536
+ continue;
537
+ const endMs = Math.max(startMs, endMsRaw);
538
+ const text = stripInlineSubtitleTags(lines.slice(timingIdx + 1).join('\n')).trim();
539
+ if (text === '')
540
+ continue;
541
+ parsed.push({ startMs, endMs, text });
542
+ }
543
+ parsed.sort((a, b) => (a.startMs !== b.startMs ? a.startMs - b.startMs : a.endMs - b.endMs));
544
+ return parsed.map((cue, idx) => ({
545
+ index: idx + 1,
546
+ startMs: cue.startMs,
547
+ endMs: cue.endMs,
548
+ text: cue.text,
549
+ }));
550
+ }
551
+ /**
552
+ * 将基础语速百分比(如 `+10%`)乘以缩放因子并钳制在 `[0.7, 1.85]`(`-30%` 至 `+85%`),返回 `'+25%'` / `'-10%'` 格式。
553
+ */
554
+ export function scaleRatePercent(baseRate, factor) {
555
+ const match = /^([+-]?\d+(?:\.\d+)?)%$/.exec(baseRate.trim());
556
+ const baseMultiplier = match && Number.isFinite(Number(match[1])) ? 1 + Number(match[1]) / 100 : 1.0;
557
+ const safeFactor = Number.isFinite(factor) && factor > 0 ? factor : 1.0;
558
+ const combined = Math.min(1.85, Math.max(0.7, baseMultiplier * safeFactor));
559
+ const percent = Math.round((combined - 1) * 100);
560
+ return (percent >= 0 ? '+' : '') + String(percent) + '%';
561
+ }
562
+ /**
563
+ * 纯文本单遍发音词典替换(用于不支持 SSML `<sub alias>` 的 OpenAI / SiliconFlow 引擎)。
564
+ * 按原词长度降序构造单次正则同步替换,保证替读结果不会递归触发其它规则。
565
+ */
566
+ export function applyPronunciationsPlain(text, rules) {
567
+ if (text === '' || !Array.isArray(rules) || rules.length === 0)
568
+ return text;
569
+ const map = new Map();
570
+ for (const rule of rules) {
571
+ if (!rule || typeof rule.word !== 'string' || typeof rule.alias !== 'string')
572
+ continue;
573
+ const word = rule.word.trim();
574
+ const alias = rule.alias.trim();
575
+ if (word !== '' && alias !== '') {
576
+ map.set(word, alias);
577
+ }
578
+ }
579
+ if (map.size === 0)
580
+ return text;
581
+ const sortedWords = Array.from(map.keys()).sort((a, b) => b.length - a.length);
582
+ const regex = new RegExp(sortedWords.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g');
583
+ return text.replace(regex, (matched) => map.get(matched) ?? matched);
584
+ }
318
585
  function throwIfAborted(signal) {
319
586
  if (signal?.aborted === true)
320
587
  throw signal.reason;
321
588
  }
322
- function runFfmpegLoudnorm(inPath, outPath, signal) {
589
+ function runFfmpegArgs(args, errorPrefix, signal) {
323
590
  throwIfAborted(signal);
324
591
  return new Promise((resolvePromise, rejectPromise) => {
325
- execFile('ffmpeg', ['-y', '-i', inPath, '-af', 'loudnorm=I=-16:TP=-1.5:LRA=11', '-ar', '24000', '-ac', '1', '-b:a', '48k', outPath], { signal, maxBuffer: 4 * 1024 * 1024 }, (error, _stdout, stderr) => {
592
+ execFile('ffmpeg', args, { signal, maxBuffer: 4 * 1024 * 1024 }, (error, _stdout, stderr) => {
326
593
  if (signal?.aborted === true) {
327
594
  rejectPromise(signal.reason);
328
595
  return;
@@ -331,7 +598,7 @@ function runFfmpegLoudnorm(inPath, outPath, signal) {
331
598
  const detail = typeof stderr === 'string' && stderr.trim() !== ''
332
599
  ? stderr.trim().slice(-300)
333
600
  : error.message;
334
- rejectPromise(new Error('ffmpeg 响度均衡失败:' + detail));
601
+ rejectPromise(new Error(errorPrefix + detail));
335
602
  return;
336
603
  }
337
604
  resolvePromise();
@@ -349,7 +616,7 @@ export async function normalizeAudioLoudness(mp3, signal) {
349
616
  const inPath = join(tempDir, 'in.mp3');
350
617
  const outPath = join(tempDir, 'out.mp3');
351
618
  writeFileSync(inPath, mp3);
352
- await runFfmpegLoudnorm(inPath, outPath, signal);
619
+ await runFfmpegArgs(['-y', '-i', inPath, '-af', 'loudnorm=I=-16:TP=-1.5:LRA=11', '-ar', '24000', '-ac', '1', '-b:a', '48k', outPath], 'ffmpeg 响度均衡失败:', signal);
353
620
  throwIfAborted(signal);
354
621
  const normalized = readFileSync(outPath);
355
622
  if (normalized.length === 0) {
@@ -366,3 +633,65 @@ export async function normalizeAudioLoudness(mp3, signal) {
366
633
  }
367
634
  }
368
635
  }
636
+ /**
637
+ * 使用本地 ffmpeg 将人声 MP3 与背景音乐混音:
638
+ * 自动循环 BGM、按人声侧链压缩闪避(ducking)、在结尾 1.2s 平滑淡出(总长 > 3s),并可选联动响度均衡。
639
+ */
640
+ export async function mixAudioWithBgm(voiceMp3, opts, signal) {
641
+ throwIfAborted(signal);
642
+ if (voiceMp3.length === 0) {
643
+ throw new Error('人声音频为空,无法混入 BGM。');
644
+ }
645
+ if (typeof opts.bgmPath !== 'string' || opts.bgmPath.trim() === '') {
646
+ throw new Error('未提供有效的背景音乐路径(bgmPath)。');
647
+ }
648
+ const info = inspectMp3Buffer(voiceMp3);
649
+ const targetRate = [16000, 22050, 24000, 32000, 44100, 48000].includes(info.sampleRate) ? info.sampleRate : 24000;
650
+ const targetLayout = info.channels === 2 ? 'stereo' : 'mono';
651
+ const volume = Math.min(1.0, Math.max(0.02, Number.isFinite(opts.bgmVolume) ? opts.bgmVolume : 0.18));
652
+ const ducking = opts.ducking !== false;
653
+ const fadeFilter = info.durationMs > 3000
654
+ ? `,afade=t=out:st=${Math.max(0, (info.durationMs - 1200) / 1000).toFixed(3)}:d=1.2`
655
+ : '';
656
+ const loudnormFilter = opts.normalizeLoudness === true ? ',loudnorm=I=-16:TP=-1.5:LRA=11' : '';
657
+ const bitrateArg = String(Math.min(192, Math.max(48, info.bitrateKbps))) + 'k';
658
+ const filterGraph = ducking
659
+ ? `[0:a]aformat=sample_rates=${targetRate}:channel_layouts=${targetLayout},asplit=2[v_mix][v_sc];`
660
+ + `[1:a]aformat=sample_rates=${targetRate}:channel_layouts=${targetLayout},volume=${volume.toFixed(4)}${fadeFilter}[bgm];`
661
+ + `[bgm][v_sc]sidechaincompress=threshold=0.03:ratio=6:attack=40:release=450[bgm_ducked];`
662
+ + `[v_mix][bgm_ducked]amix=inputs=2:duration=first:dropout_transition=2:normalize=0${loudnormFilter}[out]`
663
+ : `[0:a]aformat=sample_rates=${targetRate}:channel_layouts=${targetLayout}[v_mix];`
664
+ + `[1:a]aformat=sample_rates=${targetRate}:channel_layouts=${targetLayout},volume=${volume.toFixed(4)}${fadeFilter}[bgm];`
665
+ + `[v_mix][bgm]amix=inputs=2:duration=first:dropout_transition=2:normalize=0${loudnormFilter}[out]`;
666
+ const tempDir = mkdtempSync(join(tmpdir(), 'dsh-voice-bgm-'));
667
+ try {
668
+ const voicePath = join(tempDir, 'voice.mp3');
669
+ const outPath = join(tempDir, 'out.mp3');
670
+ writeFileSync(voicePath, voiceMp3);
671
+ await runFfmpegArgs([
672
+ '-y',
673
+ '-i', voicePath,
674
+ '-stream_loop', '-1', '-i', opts.bgmPath,
675
+ '-filter_complex', filterGraph,
676
+ '-map', '[out]',
677
+ '-ar', String(targetRate),
678
+ '-ac', String(info.channels),
679
+ '-b:a', bitrateArg,
680
+ outPath,
681
+ ], 'ffmpeg BGM 混音失败:', signal);
682
+ throwIfAborted(signal);
683
+ const mixed = readFileSync(outPath);
684
+ if (mixed.length === 0) {
685
+ throw new Error('ffmpeg BGM 混音结果为空。');
686
+ }
687
+ return mixed;
688
+ }
689
+ finally {
690
+ try {
691
+ rmSync(tempDir, { recursive: true, force: true });
692
+ }
693
+ catch {
694
+ // 尽力清理临时目录
695
+ }
696
+ }
697
+ }
package/lib/web.d.ts ADDED
@@ -0,0 +1,66 @@
1
+ /**
2
+ * 本地受鉴权 Voice Studio 后端路由:复用宿主 connection/webServer 载体,提供音色列表、即时试听、麦克风转写与安全配置更新。
3
+ * 绝不向前端返回 asrApiKey / ttsApiKey / proxyUrl 等敏感凭据原文。
4
+ *
5
+ * @module dsh-voice/web
6
+ */
7
+ import type { IncomingMessage, ServerResponse } from 'node:http';
8
+ import { type AsrEngine, type CustomVoiceAlias, type ResolvedVoiceConfig, type TtsEngine } from './config.js';
9
+ import { fetchEdgeVoices, synthesizeSpeech } from './edge-tts.js';
10
+ import { synthesizeOpenAiSpeech } from './openai-tts.js';
11
+ import { transcribe } from './stt.js';
12
+ export declare const VOICE_STUDIO_SETTINGS_ROUTE = "/_dsh/dsh-voice/studio";
13
+ export declare const VOICE_STUDIO_API_ROUTE = "/api/dsh-voice/studio";
14
+ export declare class VoiceStudioError extends Error {
15
+ readonly status: number;
16
+ readonly code: string;
17
+ constructor(message: string, status?: number, code?: string);
18
+ }
19
+ export interface StudioPronunciationRule {
20
+ word: string;
21
+ alias: string;
22
+ }
23
+ export interface VoiceStudioBackendOptions {
24
+ updateSettings?: (patch: Record<string, unknown>) => Promise<void>;
25
+ writable?: () => boolean;
26
+ tts?: typeof synthesizeSpeech;
27
+ openaiTts?: typeof synthesizeOpenAiSpeech;
28
+ fetchVoices?: typeof fetchEdgeVoices;
29
+ stt?: typeof transcribe;
30
+ }
31
+ export declare function createVoiceStudioBackend(readCfg: () => ResolvedVoiceConfig, options?: VoiceStudioBackendOptions): {
32
+ snapshot: () => {
33
+ ttsEngine: TtsEngine;
34
+ ttsVoice: string;
35
+ ttsRate: string;
36
+ ttsPitch: string;
37
+ ttsModel: string;
38
+ hasTtsKey: boolean;
39
+ asrEngine: AsrEngine;
40
+ asrModel: string;
41
+ hasAsrKey: boolean;
42
+ hasProxy: boolean;
43
+ overwrite: boolean;
44
+ customVoices: CustomVoiceAlias[];
45
+ pronunciations: StudioPronunciationRule[];
46
+ voices: import("./voices.js").VoiceInfo[];
47
+ personas: import("./voices.js").VoicePersona[];
48
+ writable: boolean;
49
+ hasFfmpeg: boolean;
50
+ ttsReady: boolean;
51
+ sttReady: boolean;
52
+ };
53
+ /** 仅由宿主已鉴权的 connection.fetch 路由调用。 */
54
+ fetch(request: Request): Promise<Response>;
55
+ handle(req: IncomingMessage, res: ServerResponse, transport?: symbol): Promise<void>;
56
+ };
57
+ export declare function installVoiceStudioWeb(ctx: {
58
+ inject?: Function;
59
+ fiber?: {
60
+ entry?: {
61
+ options?: {
62
+ id?: string;
63
+ };
64
+ };
65
+ };
66
+ }, readCfg: () => ResolvedVoiceConfig, deps?: VoiceStudioBackendOptions): ReturnType<typeof createVoiceStudioBackend>;