@gobing-ai/knowledge-kit 0.0.7 → 0.0.9

package/plugins/generations/voice-gen/src/index.ts

@@ -0,0 +1,228 @@
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Content, ContentSchema, type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+import { concatWavs } from './concat';
+import { isMp3Requested, type Mp3Transcoder, transcodeWavToMp3 } from './mp3';
+import { createVoiceboxClient, type VoiceboxClient, type VoiceboxGenerateBody } from './voicebox-client';
+import {
+    mergeVoiceScripts,
+    parseDocToVoiceScript,
+    VOICEBOX_CHUNK_CHARS_DEFAULT,
+    VOICEBOX_CHUNK_CHARS_MAX,
+    VOICEBOX_CHUNK_CHARS_MIN,
+    VOICEBOX_CROSSFADE_MS_DEFAULT,
+    VOICEBOX_CROSSFADE_MS_MAX,
+    VOICEBOX_CROSSFADE_MS_MIN,
+    validateVoiceScript,
+} from './voicescript';
+
+export * from './concat';
+export * from './mp3';
+export * from './voicebox-client';
+export * from './voicescript';
+
+const EMPTY_CONTENT: Content = {
+    title: 'Notice',
+    body: '# Notice\nNo documents provided for generation.',
+    format: 'markdown',
+    references: [],
+};
+
+/**
+ * Read validated Doc[] input, generate validated audio Content via Voicebox, and write output files.
+ */
+export async function processGeneratorIO(
+    inputPath: string,
+    outputPath: string,
+    clientOverride?: VoiceboxClient,
+    transcodeMp3?: Mp3Transcoder,
+): Promise<void> {
+    const fs = createNodeFileSystem();
+    const outDir = dirname(outputPath);
+    const outStem = basename(outputPath, extname(outputPath));
+    const audioPath = resolve(join(outDir, `${outStem}.wav`));
+    const mp3Path = resolve(join(outDir, `${outStem}.mp3`));
+    const wantMp3 = isMp3Requested();
+
+    // Delete existing output and sibling audio at start
+    await fs.deleteFile(outputPath);
+    await fs.deleteFile(audioPath);
+    await fs.deleteFile(mp3Path);
+
+    let docs: Doc[];
+    try {
+        const raw = await fs.readFile(inputPath);
+        docs = DocListSchema.parse(JSON.parse(raw));
+    } catch (err: unknown) {
+        throw new Error(`Invalid DocList input: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    if (docs.length === 0) {
+        await fs.ensureDir(outDir);
+        await fs.writeFile(outputPath, JSON.stringify(ContentSchema.parse(EMPTY_CONTENT), null, 2));
+        return;
+    }
+
+    const client = clientOverride ?? createVoiceboxClient();
+
+    try {
+        // 1. Health check
+        await client.health();
+
+        // 2. Parse docs to VoiceScript
+        const envDefaultProfile = process.env.VOICEBOX_DEFAULT_PROFILE;
+        const scripts = docs.map((doc) => parseDocToVoiceScript(doc, envDefaultProfile));
+        const combinedScript = mergeVoiceScripts(scripts, docs, envDefaultProfile);
+
+        // 3. Validate VoiceScript
+        validateVoiceScript(combinedScript);
+
+        // 4. Generate each segment
+        const segmentWavs: Uint8Array[] = [];
+        const segmentGaps: number[] = [];
+        const segmentMetadata: Array<{ generationId: string; profile: string; duration: number }> = [];
+        let totalDuration = 0;
+
+        for (const segment of combinedScript.segments) {
+            const speakerConfig = segment.speaker ? combinedScript.speakers?.[segment.speaker] : undefined;
+            const profileTarget =
+                segment.profile ??
+                speakerConfig?.profile ??
+                combinedScript.default_profile ??
+                envDefaultProfile ??
+                (typeof docs[0]?.metadata?.voiceProfile === 'string' ? docs[0].metadata.voiceProfile : undefined);
+
+            if (!profileTarget) {
+                throw new Error(
+                    'No voice profile specified for segment (set profile, speaker profile, default_profile, or VOICEBOX_DEFAULT_PROFILE)',
+                );
+            }
+
+            const resolvedProfile = await client.resolveProfile(profileTarget);
+
+            const engine = segment.engine ?? speakerConfig?.engine ?? combinedScript.default_engine;
+            const language = segment.language ?? speakerConfig?.language ?? combinedScript.language ?? 'en';
+            const instruct = segment.instruct ?? speakerConfig?.instruct;
+
+            const envChunk = process.env.VOICEBOX_MAX_CHUNK_CHARS
+                ? parseInt(process.env.VOICEBOX_MAX_CHUNK_CHARS, 10)
+                : undefined;
+            const envCrossfade = process.env.VOICEBOX_CROSSFADE_MS
+                ? parseInt(process.env.VOICEBOX_CROSSFADE_MS, 10)
+                : undefined;
+
+            const max_chunk_chars =
+                segment.max_chunk_chars ?? combinedScript.max_chunk_chars ?? envChunk ?? VOICEBOX_CHUNK_CHARS_DEFAULT;
+            const crossfade_ms =
+                segment.crossfade_ms ?? combinedScript.crossfade_ms ?? envCrossfade ?? VOICEBOX_CROSSFADE_MS_DEFAULT;
+
+            if (max_chunk_chars < VOICEBOX_CHUNK_CHARS_MIN || max_chunk_chars > VOICEBOX_CHUNK_CHARS_MAX) {
+                throw new Error(
+                    `max_chunk_chars must be between ${VOICEBOX_CHUNK_CHARS_MIN} and ${VOICEBOX_CHUNK_CHARS_MAX}`,
+                );
+            }
+            if (crossfade_ms < VOICEBOX_CROSSFADE_MS_MIN || crossfade_ms > VOICEBOX_CROSSFADE_MS_MAX) {
+                throw new Error(
+                    `crossfade_ms must be between ${VOICEBOX_CROSSFADE_MS_MIN} and ${VOICEBOX_CROSSFADE_MS_MAX}`,
+                );
+            }
+
+            const generateBody: VoiceboxGenerateBody = {
+                profile_id: resolvedProfile.id,
+                text: segment.text,
+                language,
+                engine,
+                instruct,
+                max_chunk_chars,
+                crossfade_ms,
+                personality: false,
+                normalize: true,
+            };
+
+            const { id } = await client.generate(generateBody);
+            const history = await client.waitUntilDone(id);
+            if (history.status === 'failed') {
+                throw new Error(
+                    `Voicebox generation failed for profile "${resolvedProfile.name}": ${history.error || 'status failed'}`,
+                );
+            }
+
+            const wavBytes = await client.downloadAudio(id);
+            const gap = segment.gap_ms ?? 0;
+
+            segmentWavs.push(wavBytes);
+            segmentGaps.push(gap);
+
+            const segDuration = history.duration ?? 0;
+            totalDuration += segDuration + gap / 1000;
+            segmentMetadata.push({
+                generationId: id,
+                profile: resolvedProfile.name,
+                duration: segDuration,
+            });
+        }
+
+        // 5. Concatenate audio
+        const concatenatedWav = concatWavs(segmentWavs, segmentGaps);
+        await fs.ensureDir(outDir);
+        await Bun.write(audioPath, concatenatedWav);
+
+        const metadata: Record<string, unknown> = {
+            generator: 'kk:voice-gen',
+            audioPath,
+            duration: totalDuration,
+            segments: segmentMetadata,
+        };
+
+        if (wantMp3) {
+            const transcode = transcodeMp3 ?? transcodeWavToMp3;
+            await transcode(audioPath, mp3Path);
+            metadata.mp3Path = mp3Path;
+        }
+
+        // 6. Build Content
+        const content: Content = {
+            title: combinedScript.title || docs[0]?.title || 'Generated voice',
+            body: Bun.YAML.stringify(combinedScript),
+            format: 'audio',
+            references: [],
+            metadata,
+        };
+
+        const validatedContent = ContentSchema.parse(content);
+        await fs.writeFile(outputPath, JSON.stringify(validatedContent, null, 2));
+    } catch (err: unknown) {
+        await fs.deleteFile(outputPath);
+        await fs.deleteFile(audioPath);
+        await fs.deleteFile(mp3Path);
+        throw err;
+    }
+}
+
+export async function main(): Promise<number> {
+    const { values } = parseArgs({
+        options: {
+            in: { type: 'string' },
+            out: { type: 'string' },
+        },
+    });
+
+    if (!values.in || !values.out) {
+        echoError('voice-gen failed: Missing required arguments: --in and --out');
+        return 1;
+    }
+
+    try {
+        await processGeneratorIO(values.in, values.out);
+        return 0;
+    } catch (err: unknown) {
+        echoError(`voice-gen failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

package/plugins/generations/voice-gen/src/mp3.ts

@@ -0,0 +1,65 @@
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+
+const MP3_TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+/** True when the operator asked for a sibling MP3 (`VOICE_GEN_MP3=true|1|yes|on`). */
+export function isMp3Requested(env: NodeJS.ProcessEnv = process.env): boolean {
+    const raw = env.VOICE_GEN_MP3;
+    if (raw === undefined || raw === '') {
+        return false;
+    }
+    return MP3_TRUTHY.has(raw.trim().toLowerCase());
+}
+
+/** WAV → MP3. Injected in tests so CI does not need ffmpeg. */
+export type Mp3Transcoder = (wavPath: string, mp3Path: string) => Promise<void>;
+
+/**
+ * Convert a workspace WAV to MP3 with ffmpeg + libmp3lame (VBR `-qscale:a 2`).
+ * Fail-loud if ffmpeg is missing, exits non-zero, or writes no file.
+ */
+export async function transcodeWavToMp3(wavPath: string, mp3Path: string, ffmpegBin = 'ffmpeg'): Promise<void> {
+    const fs = createNodeFileSystem();
+    if (!(await fs.exists(wavPath))) {
+        throw new Error(`ffmpeg mp3 transcode failed: WAV input not found: ${wavPath}`);
+    }
+
+    let proc: ReturnType<typeof Bun.spawnSync>;
+    try {
+        proc = Bun.spawnSync(
+            [
+                ffmpegBin,
+                '-y',
+                '-hide_banner',
+                '-loglevel',
+                'error',
+                '-i',
+                wavPath,
+                '-codec:a',
+                'libmp3lame',
+                '-qscale:a',
+                '2',
+                mp3Path,
+            ],
+            { stdout: 'pipe', stderr: 'pipe' },
+        );
+    } catch (err: unknown) {
+        throw new Error(
+            `ffmpeg is required for MP3 output (VOICE_GEN_MP3=true) but was not found on PATH (${err instanceof Error ? err.message : String(err)})`,
+        );
+    }
+
+    if (proc.exitCode !== 0) {
+        const detail = (proc.stderr?.toString() ?? '').trim() || (proc.stdout?.toString() ?? '').trim();
+        if (proc.exitCode === null || /not found|ENOENT/i.test(detail)) {
+            throw new Error(
+                `ffmpeg is required for MP3 output (VOICE_GEN_MP3=true) but was not found on PATH${detail ? `: ${detail}` : ''}`,
+            );
+        }
+        throw new Error(`ffmpeg mp3 transcode failed (exit ${proc.exitCode}): ${detail || 'no stderr'}`);
+    }
+
+    if (!(await fs.exists(mp3Path))) {
+        throw new Error(`ffmpeg mp3 transcode produced no file: ${mp3Path}`);
+    }
+}

package/plugins/generations/voice-gen/src/voicebox-client.ts

@@ -0,0 +1,223 @@
+export interface VoiceboxGenerateBody {
+    profile_id: string;
+    text: string;
+    language: string;
+    engine?: string;
+    instruct?: string;
+    max_chunk_chars: number;
+    crossfade_ms: number;
+    personality: false;
+    normalize: true;
+}
+
+export interface VoiceboxProfile {
+    id: string;
+    name: string;
+    description?: string;
+    engine?: string;
+    language?: string;
+}
+
+export interface VoiceboxHistory {
+    id: string;
+    status: 'pending' | 'generating' | 'completed' | 'failed' | string;
+    duration?: number;
+    error?: string;
+}
+
+export interface VoiceboxClient {
+    readonly url: string;
+    health(): Promise<void>;
+    resolveProfile(nameOrId: string): Promise<VoiceboxProfile>;
+    generate(body: VoiceboxGenerateBody): Promise<{ id: string }>;
+    waitUntilDone(
+        id: string,
+        timeoutMs?: number,
+        pollMs?: number,
+    ): Promise<{ status: 'completed' | 'failed'; duration?: number; error?: string }>;
+    downloadAudio(id: string): Promise<Uint8Array>;
+}
+
+export interface VoiceboxClientOptions {
+    url?: string;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Creates a client for the Voicebox local REST API.
+ */
+export function createVoiceboxClient(options: VoiceboxClientOptions = {}): VoiceboxClient {
+    const rawUrl = options.url || process.env.VOICEBOX_URL || 'http://127.0.0.1:17493';
+    const url = rawUrl.replace(/\/+$/, '');
+    const customFetch = options.fetch ?? globalThis.fetch;
+    const sleep = options.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+
+    return {
+        url,
+
+        async health(): Promise<void> {
+            try {
+                const res = await customFetch(`${url}/health`);
+                if (!res.ok) {
+                    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+                }
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox health check failed at ${url}: ${reason}`);
+            }
+        },
+
+        async resolveProfile(nameOrId: string): Promise<VoiceboxProfile> {
+            let res: Response;
+            try {
+                res = await customFetch(`${url}/profiles`);
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /profiles request failed at ${url}: ${reason}`);
+            }
+
+            if (!res.ok) {
+                throw new Error(`Voicebox /profiles request failed at ${url}: HTTP ${res.status} ${res.statusText}`);
+            }
+
+            let profiles: VoiceboxProfile[];
+            try {
+                profiles = (await res.json()) as VoiceboxProfile[];
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /profiles returned invalid JSON at ${url}: ${reason}`);
+            }
+
+            if (!Array.isArray(profiles)) {
+                throw new Error(`Voicebox /profiles returned non-array at ${url}`);
+            }
+
+            const targetLower = nameOrId.toLowerCase();
+            const matched = profiles.find((p) => p.id === nameOrId || (p.name && p.name.toLowerCase() === targetLower));
+
+            if (!matched) {
+                throw new Error(`Voicebox profile "${nameOrId}" not found at ${url}`);
+            }
+
+            return matched;
+        },
+
+        async generate(body: VoiceboxGenerateBody): Promise<{ id: string }> {
+            let res: Response;
+            try {
+                res = await customFetch(`${url}/generate`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(body),
+                });
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /generate request failed at ${url}: ${reason}`);
+            }
+
+            if (!res.ok) {
+                let errorDetails = '';
+                try {
+                    errorDetails = await res.text();
+                } catch {
+                    // ignore
+                }
+                throw new Error(
+                    `Voicebox /generate failed at ${url}: HTTP ${res.status} ${res.statusText} ${errorDetails}`.trim(),
+                );
+            }
+
+            let data: { id: string };
+            try {
+                data = (await res.json()) as { id: string };
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /generate returned invalid JSON at ${url}: ${reason}`);
+            }
+
+            if (!data || typeof data.id !== 'string') {
+                throw new Error(`Voicebox /generate response missing id at ${url}`);
+            }
+
+            return { id: data.id };
+        },
+
+        async waitUntilDone(
+            id: string,
+            timeoutMs?: number,
+            pollMs?: number,
+        ): Promise<{ status: 'completed' | 'failed'; duration?: number; error?: string }> {
+            const timeout =
+                timeoutMs ?? (process.env.VOICEBOX_TIMEOUT_MS ? parseInt(process.env.VOICEBOX_TIMEOUT_MS, 10) : 600000);
+            const poll = pollMs ?? (process.env.VOICEBOX_POLL_MS ? parseInt(process.env.VOICEBOX_POLL_MS, 10) : 1000);
+
+            const startTime = Date.now();
+
+            while (true) {
+                let res: Response;
+                try {
+                    res = await customFetch(`${url}/history/${id}`);
+                } catch (err: unknown) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    throw new Error(`Voicebox /history/${id} request failed at ${url}: ${reason}`);
+                }
+
+                if (!res.ok) {
+                    throw new Error(
+                        `Voicebox /history/${id} request failed at ${url}: HTTP ${res.status} ${res.statusText}`,
+                    );
+                }
+
+                let history: VoiceboxHistory;
+                try {
+                    history = (await res.json()) as VoiceboxHistory;
+                } catch (err: unknown) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    throw new Error(`Voicebox /history/${id} returned invalid JSON at ${url}: ${reason}`);
+                }
+
+                if (history.status === 'completed') {
+                    return { status: 'completed', duration: history.duration };
+                }
+                if (history.status === 'failed') {
+                    return {
+                        status: 'failed',
+                        duration: history.duration,
+                        error: history.error || 'Generation status failed',
+                    };
+                }
+
+                if (Date.now() - startTime >= timeout) {
+                    throw new Error(`Voicebox generation timed out after ${timeout}ms for id: ${id} at ${url}`);
+                }
+
+                await sleep(poll);
+            }
+        },
+
+        async downloadAudio(id: string): Promise<Uint8Array> {
+            let res: Response;
+            try {
+                res = await customFetch(`${url}/audio/${id}`);
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /audio/${id} request failed at ${url}: ${reason}`);
+            }
+
+            if (!res.ok) {
+                throw new Error(`Voicebox /audio/${id} request failed at ${url}: HTTP ${res.status} ${res.statusText}`);
+            }
+
+            try {
+                const arrayBuf = await res.arrayBuffer();
+                return new Uint8Array(arrayBuf);
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /audio/${id} failed to read audio stream at ${url}: ${reason}`);
+            }
+        },
+    };
+}