verbalcoding 0.2.0

package/app-node/tts_backends.test.mjs

@@ -0,0 +1,400 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+
+import { createTtsBackend } from './tts_backends.mjs';
+
+function baseSettings() {
+  return {
+    backend: 'edge',
+    edge: { voice: 'ko-KR-InJoonNeural', rate: '+10%' },
+    openvoice: {
+      dir: '/project/vendor/OpenVoice',
+      venv: '/project/.venv-openvoice',
+      refAudio: '/project/voice-samples/me.wav',
+      language: 'KR',
+      style: 'default',
+      timeoutMs: 90000,
+      useForProgress: false,
+    },
+    speechswift: {
+      command: 'audio',
+      engine: 'cosyvoice',
+      language: 'korean',
+      refAudio: '/project/voice-samples/me.wav',
+      modelId: 'aufklarer/CosyVoice3-0.5B-MLX-4bit',
+      model: 'base',
+      speaker: '',
+      instruct: '',
+      timeoutMs: 120000,
+      stream: true,
+      useForProgress: false,
+      mode: 'cli',
+      serverUrl: 'http://127.0.0.1:18080',
+    },
+    supertonic: {
+      command: 'supertonic',
+      voice: 'M1',
+      language: 'ko',
+      steps: 2,
+      speed: 1.08,
+      maxChunkLength: 300,
+      silenceDuration: 0.15,
+      customStylePath: '',
+      timeoutMs: 60000,
+      useForProgress: false,
+      cacheDir: '',
+      intraOpThreads: '',
+      interOpThreads: '',
+    },
+  };
+}
+
+test('Edge backend calls edge-tts with voice, rate, text, and output path', async () => {
+  const calls = [];
+  const backend = createTtsBackend(baseSettings(), {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    execFileAsync: async (cmd, args, options) => {
+      calls.push({ cmd, args, options });
+    },
+  });
+
+  const out = await backend.synthesize('안녕하세요', { kind: 'final' });
+
+  assert.equal(calls[0].cmd, 'edge-tts');
+  assert.deepEqual(calls[0].args.slice(0, 5), ['-v', 'ko-KR-InJoonNeural', '--rate', '+10%', '-t']);
+  assert.equal(calls[0].args[5], '안녕하세요');
+  assert.equal(calls[0].args[6], '--write-media');
+  assert.match(out, /^\/tmp\/verbalcoding-edge-/);
+  assert.equal(calls[0].options.timeout, 60000);
+  assert.deepEqual(backend.cacheKeyParts(), ['edge', 'ko-KR-InJoonNeural', '+10%']);
+});
+
+test('Edge backend reads dynamic voice before each TTS request', async () => {
+  const calls = [];
+  const backend = createTtsBackend(baseSettings(), {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    voiceProvider: () => 'en-US-GuyNeural',
+    execFileAsync: async (cmd, args, options) => {
+      calls.push({ cmd, args, options });
+    },
+  });
+
+  await backend.synthesize('hello', { kind: 'final' });
+
+  assert.deepEqual(calls[0].args.slice(0, 2), ['-v', 'en-US-GuyNeural']);
+  assert.deepEqual(backend.cacheKeyParts(), ['edge', 'en-US-GuyNeural', '+10%']);
+});
+
+test('Edge backend honors configurable command path', async () => {
+  const calls = [];
+  const settings = baseSettings();
+  settings.edge.command = '/project/.venv/bin/edge-tts';
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    execFileAsync: async (cmd, args, options) => {
+      calls.push({ cmd, args, options });
+    },
+  });
+
+  await backend.synthesize('안녕하세요', { kind: 'final' });
+
+  assert.equal(calls[0].cmd, '/project/.venv/bin/edge-tts');
+});
+
+test('OpenVoice final synthesis calls Python wrapper with reference audio and output path', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'openvoice' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: file => file.endsWith('python') || file.endsWith('.wav'),
+    statSync: () => ({ size: 999 }),
+    execFileAsync: async (cmd, args, options) => calls.push({ cmd, args, options }),
+  });
+
+  const out = await backend.synthesize('복제 음성 테스트', { kind: 'final' });
+
+  assert.equal(calls[0].cmd, path.join('/project/.venv-openvoice', 'bin', 'python'));
+  assert.ok(calls[0].args.some(arg => String(arg).endsWith('scripts/openvoice_synth.py')));
+  assert.ok(calls[0].args.includes('--ref-audio'));
+  assert.ok(calls[0].args.includes('/project/voice-samples/me.wav'));
+  assert.ok(calls[0].args.includes('--text'));
+  assert.ok(calls[0].args.includes('복제 음성 테스트'));
+  assert.equal(calls[0].options.timeout, 90000);
+  assert.match(out, /^\/tmp\/verbalcoding-openvoice-/);
+  assert.deepEqual(backend.cacheKeyParts(), ['openvoice', '/project/voice-samples/me.wav', 'KR', 'default']);
+});
+
+test('OpenVoice progress uses Edge fallback unless explicitly enabled', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'openvoice' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    execFileAsync: async (cmd, args) => calls.push({ cmd, args }),
+  });
+
+  await backend.synthesize('파일 읽기', { kind: 'progress' });
+
+  assert.equal(calls[0].cmd, 'edge-tts');
+});
+
+test('OpenVoice final synthesis falls back to Edge when wrapper fails', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'openvoice' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    warn: (...args) => calls.push({ warn: args.join(' ') }),
+    execFileAsync: async (cmd, args) => {
+      calls.push({ cmd, args });
+      if (cmd.includes('.venv-openvoice')) throw new Error('openvoice missing');
+    },
+  });
+
+  await backend.synthesize('fallback', { kind: 'final' });
+
+  assert.ok(calls.some(call => call.cmd?.includes('.venv-openvoice')));
+  assert.ok(calls.some(call => call.cmd === 'edge-tts'));
+  assert.ok(calls.some(call => /falling back to edge/i.test(call.warn || '')));
+});
+
+
+test('OpenVoice backend falls back to python3 when configured venv python is missing', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'openvoice' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: file => file.endsWith('.wav'),
+    statSync: () => ({ size: 999 }),
+    execFileAsync: async (cmd, args, options) => calls.push({ cmd, args, options }),
+  });
+
+  await backend.synthesize('복제 음성 테스트', { kind: 'final' });
+
+  assert.equal(calls[0].cmd, 'python3');
+});
+
+test('SpeechSwift CosyVoice backend calls audio CLI with reference sample and output path', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'speechswift' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 999 }),
+    execFileAsync: async (cmd, args, options) => calls.push({ cmd, args, options }),
+  });
+
+  const out = await backend.synthesize('복제 음성 테스트', { kind: 'final' });
+
+  assert.equal(calls[0].cmd, 'audio');
+  assert.deepEqual(calls[0].args.slice(0, 4), ['speak', '복제 음성 테스트', '--engine', 'cosyvoice']);
+  assert.ok(calls[0].args.includes('--voice-sample'));
+  assert.ok(calls[0].args.includes('/project/voice-samples/me.wav'));
+  assert.ok(calls[0].args.includes('--stream'));
+  assert.ok(calls[0].args.includes('--model-id'));
+  assert.equal(calls[0].options.timeout, 120000);
+  assert.match(out, /^\/tmp\/verbalcoding-speechswift-/);
+  assert.deepEqual(backend.cacheKeyParts(), ['speechswift', 'cli', 'http://127.0.0.1:18080', 'cosyvoice', '/project/voice-samples/me.wav', 'korean', 'aufklarer/CosyVoice3-0.5B-MLX-4bit', 'base', '', '']);
+});
+
+test('SpeechSwift progress uses Edge fallback unless explicitly enabled', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'speechswift' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    execFileAsync: async (cmd, args) => calls.push({ cmd, args }),
+  });
+
+  await backend.synthesize('진행 안내', { kind: 'progress' });
+
+  assert.equal(calls[0].cmd, 'edge-tts');
+});
+
+test('SpeechSwift falls back to Edge when audio CLI fails', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'speechswift' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    warn: (...args) => calls.push({ warn: args.join(' ') }),
+    execFileAsync: async (cmd, args) => {
+      calls.push({ cmd, args });
+      if (cmd === 'audio') throw new Error('speech-swift missing');
+    },
+  });
+
+  await backend.synthesize('fallback', { kind: 'final' });
+
+  assert.ok(calls.some(call => call.cmd === 'audio'));
+  assert.ok(calls.some(call => call.cmd === 'edge-tts'));
+  assert.ok(calls.some(call => /speech-swift failed; falling back to edge/i.test(call.warn || '')));
+});
+
+test('SpeechSwift server mode passes an AbortSignal timeout to audio-server fetch', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'speechswift', speechswift: { ...baseSettings().speechswift, mode: 'server', serverUrl: 'http://127.0.0.1:18080', timeoutMs: 50 } };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 999 }),
+    writeFileAsync: async () => {},
+    execFileAsync: async () => {},
+    fetch: async (url, options) => {
+      calls.push({ url, options });
+      return {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        arrayBuffer: async () => new Uint8Array([1, 2, 3, 4]).buffer,
+      };
+    },
+  });
+
+  await backend.synthesize('서버 음성 테스트', { kind: 'final' });
+
+  assert.equal(calls[0].url, 'http://127.0.0.1:18080/speak');
+  assert.ok(calls[0].options.signal instanceof AbortSignal);
+  assert.equal(calls[0].options.signal.aborted, false);
+});
+
+test('SpeechSwift server mode posts to audio-server and writes returned WAV', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'speechswift', speechswift: { ...baseSettings().speechswift, mode: 'server', serverUrl: 'http://127.0.0.1:18080' } };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 999 }),
+    writeFileAsync: async (file, bytes) => calls.push({ write: file, bytes: bytes.length }),
+    execFileAsync: async (cmd, args) => calls.push({ cmd, args }),
+    fetch: async (url, options) => {
+      calls.push({ url, options });
+      return {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        arrayBuffer: async () => new Uint8Array([1, 2, 3, 4]).buffer,
+      };
+    },
+  });
+
+  const out = await backend.synthesize('서버 음성 테스트', { kind: 'final' });
+
+  assert.equal(calls[0].url, 'http://127.0.0.1:18080/speak');
+  assert.equal(calls[0].options.method, 'POST');
+  assert.equal(calls[0].options.headers['content-type'], 'application/json');
+  assert.deepEqual(JSON.parse(calls[0].options.body), {
+    text: '서버 음성 테스트',
+    engine: 'cosyvoice',
+    language: 'korean',
+  });
+  assert.match(calls[1].write, /^\/tmp\/verbalcoding-speechswift-server-/);
+  assert.equal(calls[1].bytes, 4);
+  assert.match(out, /^\/tmp\/verbalcoding-speechswift-server-/);
+});
+
+test('SpeechSwift server mode falls back to Edge when audio-server fails', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'speechswift', speechswift: { ...baseSettings().speechswift, mode: 'server' } };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    warn: (...args) => calls.push({ warn: args.join(' ') }),
+    writeFileAsync: async () => {},
+    fetch: async () => ({ ok: false, status: 503, statusText: 'Unavailable', text: async () => 'loading' }),
+    execFileAsync: async (cmd, args) => calls.push({ cmd, args }),
+  });
+
+  await backend.synthesize('fallback', { kind: 'final' });
+
+  assert.ok(calls.some(call => call.cmd === 'edge-tts'));
+  assert.ok(calls.some(call => /speech-swift failed; falling back to edge/i.test(call.warn || '')));
+});
+
+test('Supertonic backend calls local supertonic CLI with Korean low-latency options', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'supertonic' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 999 }),
+    execFileAsync: async (cmd, args, options) => calls.push({ cmd, args, options }),
+  });
+
+  const out = await backend.synthesize('수퍼토닉 테스트', { kind: 'final' });
+
+  assert.equal(calls[0].cmd, 'supertonic');
+  assert.deepEqual(calls[0].args.slice(0, 6), ['tts', '수퍼토닉 테스트', '-o', calls[0].args[3], '--lang', 'ko']);
+  assert.ok(calls[0].args.includes('--voice'));
+  assert.ok(calls[0].args.includes('M1'));
+  assert.ok(calls[0].args.includes('--steps'));
+  assert.ok(calls[0].args.includes('2'));
+  assert.ok(calls[0].args.includes('--speed'));
+  assert.ok(calls[0].args.includes('1.08'));
+  assert.equal(calls[0].options.timeout, 60000);
+  assert.match(out, /^\/tmp\/verbalcoding-supertonic-/);
+  assert.deepEqual(backend.cacheKeyParts(), ['supertonic', 'supertonic', 'M1', 'ko', 2, 1.08, 300, 0.15, '']);
+});
+
+test('Supertonic progress uses Edge fallback unless explicitly enabled', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'supertonic' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    execFileAsync: async (cmd, args) => calls.push({ cmd, args }),
+  });
+
+  await backend.synthesize('진행 안내', { kind: 'progress' });
+
+  assert.equal(calls[0].cmd, 'edge-tts');
+});
+
+test('Supertonic falls back to Edge when local CLI fails', async () => {
+  const calls = [];
+  const settings = { ...baseSettings(), backend: 'supertonic' };
+  const backend = createTtsBackend(settings, {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    warn: (...args) => calls.push({ warn: args.join(' ') }),
+    execFileAsync: async (cmd, args) => {
+      calls.push({ cmd, args });
+      if (cmd === 'supertonic') throw new Error('supertonic missing');
+    },
+  });
+
+  await backend.synthesize('fallback', { kind: 'final' });
+
+  assert.ok(calls.some(call => call.cmd === 'supertonic'));
+  assert.ok(calls.some(call => call.cmd === 'edge-tts'));
+  assert.ok(calls.some(call => /supertonic failed; falling back to edge/i.test(call.warn || '')));
+});
+
+test('TTS backends omit signal option when no AbortSignal is provided', async () => {
+  const calls = [];
+  const backend = createTtsBackend(baseSettings(), {
+    tmpdir: '/tmp',
+    existsSync: () => true,
+    statSync: () => ({ size: 123 }),
+    execFileAsync: async (cmd, args, options) => calls.push({ cmd, args, options }),
+  });
+
+  await backend.synthesize('신호 없는 음성 테스트', { signal: null, kind: 'final' });
+
+  assert.equal(calls[0].cmd, 'edge-tts');
+  assert.equal(Object.hasOwn(calls[0].options, 'signal'), false);
+});

package/app-node/tts_chunks.mjs

@@ -0,0 +1,57 @@
+const DEFAULT_MAX_CHARS = 450;
+
+function hasSpeakableText(text) {
+  return /[\p{L}\p{N}]/u.test(String(text || ''));
+}
+
+export function splitForTTS(text, maxChars = DEFAULT_MAX_CHARS) {
+  const normalized = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!normalized || !hasSpeakableText(normalized)) return [];
+  const limit = Math.max(1, Number(maxChars) || DEFAULT_MAX_CHARS);
+
+  const sentences = normalized.match(/[^.!?。！？…]+[.!?。！？…]*|.+$/gu) || [normalized];
+  const chunks = [];
+
+  for (const rawSentence of sentences) {
+    const sentence = rawSentence.trim();
+    if (!sentence || !hasSpeakableText(sentence)) continue;
+    if (sentence.length <= limit) {
+      chunks.push(sentence);
+    } else {
+      chunks.push(...splitLongSentence(sentence, limit).filter(hasSpeakableText));
+    }
+  }
+  return chunks;
+}
+
+function splitLongSentence(sentence, limit) {
+  const words = sentence.split(/\s+/).filter(Boolean);
+  if (words.length <= 1) return splitByLength(sentence, limit);
+
+  const chunks = [];
+  let current = '';
+  for (const word of words) {
+    if (word.length > limit) {
+      if (current) {
+        chunks.push(current);
+        current = '';
+      }
+      chunks.push(...splitByLength(word, limit));
+    } else if (!current) {
+      current = word;
+    } else if ((current + ' ' + word).length <= limit) {
+      current += ' ' + word;
+    } else {
+      chunks.push(current);
+      current = word;
+    }
+  }
+  if (current) chunks.push(current);
+  return chunks;
+}
+
+function splitByLength(text, limit) {
+  const chunks = [];
+  for (let i = 0; i < text.length; i += limit) chunks.push(text.slice(i, i + limit));
+  return chunks;
+}

package/app-node/tts_chunks.test.mjs

@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { splitForTTS } from './tts_chunks.mjs';
+
+test('splitForTTS keeps short text as one chunk', () => {
+  assert.deepEqual(splitForTTS('짧은 답변이야.', 80), ['짧은 답변이야.']);
+});
+
+test('splitForTTS splits long Korean text on sentence boundaries without exceeding the limit', () => {
+  const text = '첫 번째 문장은 충분히 길지만 하나의 단위야. 두 번째 문장도 이어서 말해야 해. 세 번째 문장은 너무 길어지면 다음 조각으로 넘어가야 해.';
+  const chunks = splitForTTS(text, 45);
+
+  assert.deepEqual(chunks, [
+    '첫 번째 문장은 충분히 길지만 하나의 단위야.',
+    '두 번째 문장도 이어서 말해야 해.',
+    '세 번째 문장은 너무 길어지면 다음 조각으로 넘어가야 해.',
+  ]);
+  assert.ok(chunks.every(chunk => chunk.length <= 45));
+});
+
+test('splitForTTS falls back to whitespace splitting when a sentence is too long', () => {
+  const text = '하나 둘 셋 넷 다섯 여섯 일곱 여덟 아홉 열 열하나 열둘';
+  const chunks = splitForTTS(text, 12);
+
+  assert.ok(chunks.length > 1);
+  assert.equal(chunks.join(' '), text);
+  assert.ok(chunks.every(chunk => chunk.length <= 12));
+});
+
+test('splitForTTS drops punctuation-only chunks that make Edge TTS fail', () => {
+  assert.deepEqual(splitForTTS('”.', 80), []);
+  assert.deepEqual(splitForTTS('Done. ”.', 80), ['Done.']);
+  assert.deepEqual(splitForTTS('응답 완료. ”.', 80), ['응답 완료.']);
+});

package/app-node/tts_prefetch.mjs

@@ -0,0 +1,38 @@
+function isAbortError(e) {
+  return e?.name === 'AbortError' || e?.code === 'ABORT_ERR';
+}
+
+export async function playChunkedTTSWithPrefetch(chunks, { synth, play, cleanup, signal, log = () => {} }) {
+  if (!Array.isArray(chunks) || chunks.length === 0) return;
+
+  const startSynth = index => Promise.resolve()
+    .then(() => {
+      if (signal?.aborted) return null;
+      log('TTS chunk start', index + 1, '/', chunks.length, 'chars', String(chunks[index] || '').length);
+      return synth(chunks[index], index);
+    });
+
+  let currentPromise = startSynth(0);
+  for (let index = 0; index < chunks.length; index += 1) {
+    if (signal?.aborted) return;
+    const file = await currentPromise;
+    if (!file) return;
+
+    const nextPromise = index + 1 < chunks.length ? startSynth(index + 1) : null;
+
+    if (signal?.aborted) {
+      await cleanup?.(file).catch?.(() => {});
+      return;
+    }
+
+    try {
+      await play(file, index);
+    } catch (e) {
+      if (isAbortError(e) || signal?.aborted) return;
+      throw e;
+    }
+
+    if (signal?.aborted) return;
+    currentPromise = nextPromise;
+  }
+}

package/app-node/tts_prefetch.test.mjs

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { playChunkedTTSWithPrefetch } from './tts_prefetch.mjs';
+
+function deferred() {
+  let resolve;
+  const promise = new Promise(r => { resolve = r; });
+  return { promise, resolve };
+}
+
+test('playChunkedTTSWithPrefetch starts synthesizing the next chunk while current chunk is playing', async () => {
+  const events = [];
+  const firstPlayStarted = deferred();
+  const releaseFirstPlay = deferred();
+
+  async function synth(chunk, index) {
+    events.push(`synth-start-${index}:${chunk}`);
+    return `mp3-${index}`;
+  }
+
+  async function play(file, index) {
+    events.push(`play-start-${index}:${file}`);
+    if (index === 0) {
+      firstPlayStarted.resolve();
+      await releaseFirstPlay.promise;
+    }
+    events.push(`play-end-${index}:${file}`);
+  }
+
+  const run = playChunkedTTSWithPrefetch(['하나.', '둘.'], { synth, play });
+  await firstPlayStarted.promise;
+
+  assert.ok(events.includes('synth-start-1:둘.'), 'next chunk should begin synthesizing before first playback ends');
+  assert.equal(events.includes('play-end-0:mp3-0'), false, 'first playback should still be running');
+
+  releaseFirstPlay.resolve();
+  await run;
+});
+
+test('playChunkedTTSWithPrefetch preserves playback order', async () => {
+  const played = [];
+  await playChunkedTTSWithPrefetch(['하나.', '둘.', '셋.'], {
+    synth: async (_chunk, index) => `mp3-${index}`,
+    play: async file => { played.push(file); },
+  });
+
+  assert.deepEqual(played, ['mp3-0', 'mp3-1', 'mp3-2']);
+});

package/app-node/tts_settings.mjs

@@ -0,0 +1,72 @@
+import path from 'node:path';
+
+function boolEnv(value, fallback = false) {
+  if (value == null || value === '') return fallback;
+  return ['1', 'true', 'yes', 'on'].includes(String(value).toLowerCase());
+}
+
+function positiveNumber(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function resolveUnderRoot(root, value, fallback) {
+  const raw = value == null || value === '' ? fallback : String(value);
+  return path.isAbsolute(raw) ? raw : path.join(root, raw);
+}
+
+export function buildTtsSettings(env = process.env, root = process.cwd()) {
+  const requestedBackend = String(env.TTS_BACKEND || 'edge').trim().toLowerCase();
+  const supportedBackends = new Set(['edge', 'openvoice', 'speechswift', 'supertonic']);
+  const backend = supportedBackends.has(requestedBackend) ? requestedBackend : 'edge';
+  return {
+    backend,
+    maxChars: positiveNumber(env.TTS_MAX_CHARS, 495),
+    volume: positiveNumber(env.TTS_VOLUME, 1.0),
+    progressCacheDir: resolveUnderRoot(root, env.PROGRESS_TTS_CACHE_DIR, path.join('.cache', 'progress-tts')),
+    edge: {
+      command: env.EDGE_TTS_COMMAND || env.TTS_EDGE_COMMAND || 'edge-tts',
+      voice: env.TTS_VOICE || 'ko-KR-SunHiNeural',
+      rate: env.TTS_RATE || '+10%',
+    },
+    openvoice: {
+      dir: resolveUnderRoot(root, env.OPENVOICE_DIR, path.join('vendor', 'OpenVoice')),
+      venv: resolveUnderRoot(root, env.OPENVOICE_VENV, '.venv-openvoice'),
+      refAudio: resolveUnderRoot(root, env.OPENVOICE_REF_AUDIO, path.join('voice-samples', 'user-reference.wav')),
+      language: env.OPENVOICE_LANGUAGE || 'KR',
+      style: env.OPENVOICE_STYLE || 'default',
+      timeoutMs: positiveNumber(env.OPENVOICE_TIMEOUT_MS, 90000),
+      useForProgress: boolEnv(env.OPENVOICE_PROGRESS, false),
+    },
+    speechswift: {
+      command: env.SPEECHSWIFT_COMMAND || 'audio',
+      engine: env.SPEECHSWIFT_ENGINE || 'cosyvoice',
+      language: env.SPEECHSWIFT_LANGUAGE || 'korean',
+      refAudio: resolveUnderRoot(root, env.SPEECHSWIFT_REF_AUDIO || env.OPENVOICE_REF_AUDIO, path.join('voice-samples', 'user-reference.wav')),
+      modelId: env.SPEECHSWIFT_MODEL_ID || 'aufklarer/CosyVoice3-0.5B-MLX-4bit',
+      model: env.SPEECHSWIFT_MODEL || 'base',
+      speaker: env.SPEECHSWIFT_SPEAKER || '',
+      instruct: env.SPEECHSWIFT_INSTRUCT || '',
+      timeoutMs: positiveNumber(env.SPEECHSWIFT_TIMEOUT_MS, 120000),
+      stream: boolEnv(env.SPEECHSWIFT_STREAM, true),
+      useForProgress: boolEnv(env.SPEECHSWIFT_PROGRESS, false),
+      mode: String(env.SPEECHSWIFT_MODE || 'cli').trim().toLowerCase() === 'server' ? 'server' : 'cli',
+      serverUrl: String(env.SPEECHSWIFT_SERVER_URL || 'http://127.0.0.1:18080').replace(/\/+$/, ''),
+    },
+    supertonic: {
+      command: env.SUPERTONIC_COMMAND || 'supertonic',
+      voice: env.SUPERTONIC_VOICE || 'M1',
+      language: env.SUPERTONIC_LANGUAGE || 'ko',
+      steps: positiveNumber(env.SUPERTONIC_STEPS, 2),
+      speed: positiveNumber(env.SUPERTONIC_SPEED, 1.08),
+      maxChunkLength: positiveNumber(env.SUPERTONIC_MAX_CHUNK_LENGTH, 300),
+      silenceDuration: positiveNumber(env.SUPERTONIC_SILENCE_DURATION, 0.15),
+      customStylePath: env.SUPERTONIC_CUSTOM_STYLE_PATH ? resolveUnderRoot(root, env.SUPERTONIC_CUSTOM_STYLE_PATH, '') : '',
+      timeoutMs: positiveNumber(env.SUPERTONIC_TIMEOUT_MS, 60000),
+      useForProgress: boolEnv(env.SUPERTONIC_PROGRESS, false),
+      cacheDir: env.SUPERTONIC_CACHE_DIR ? resolveUnderRoot(root, env.SUPERTONIC_CACHE_DIR, '') : '',
+      intraOpThreads: env.SUPERTONIC_INTRA_OP_THREADS || '',
+      interOpThreads: env.SUPERTONIC_INTER_OP_THREADS || '',
+    },
+  };
+}