@siduri-x/voice 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { VoiceOrgan, AudioEvent, ExperienceAdapter, ExperienceEvent, ExperienceAdapterResult } from '@siduri-x/core';
+export interface VoicevoxConfig {
+    baseUrl: string;
+    speakerId: number;
+    maxQueueDepth?: number;
+    timeoutMs?: number;
+    maxTextLength?: number;
+}
+export declare class VoicevoxAdapter implements VoiceOrgan, ExperienceAdapter {
+    private config;
+    readonly kind: "voice";
+    private queue;
+    private sequenceCounter;
+    private currentJob;
+    private isProcessing;
+    private callbacks;
+    private readonly maxQueueDepth;
+    private readonly timeoutMs;
+    private readonly maxTextLength;
+    constructor(config: VoicevoxConfig);
+    handleEvent(event: ExperienceEvent): Promise<ExperienceAdapterResult>;
+    enqueueSpeech(text: string, language: string, priority?: number): string;
+    onLifecycleEvent(callback: (event: AudioEvent) => void): void;
+    getQueueStatus(): {
+        pending: number;
+        current?: string;
+    };
+    private emit;
+    private processQueue;
+    synthesize(text: string): Promise<Uint8Array>;
+}

package/dist/index.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoicevoxAdapter = void 0;
+const core_1 = require("@siduri-x/core");
+class VoicevoxAdapter {
+    config;
+    kind = 'voice';
+    queue = [];
+    sequenceCounter = 0;
+    currentJob;
+    isProcessing = false;
+    callbacks = [];
+    maxQueueDepth;
+    timeoutMs;
+    maxTextLength;
+    constructor(config) {
+        this.config = config;
+        this.maxQueueDepth = config.maxQueueDepth ?? 50;
+        this.timeoutMs = config.timeoutMs ?? 10_000;
+        this.maxTextLength = config.maxTextLength ?? 4000;
+    }
+    async handleEvent(event) {
+        const validation = (0, core_1.validateExperienceEvent)(event);
+        if (!validation.valid) {
+            return {
+                accepted: false,
+                eventId: event?.eventId || '',
+                lifecycle: 'FAILED',
+                error: validation.error,
+                reason: 'INVALID_EVENT_ENVELOPE',
+            };
+        }
+        if (event.kind !== 'voice') {
+            return {
+                accepted: false,
+                eventId: event.eventId,
+                lifecycle: 'FAILED',
+                error: `Voice adapter received incompatible event kind: ${event.kind}`,
+                reason: 'INCOMPATIBLE_EVENT_KIND',
+            };
+        }
+        if (event.approval !== 'APPROVED') {
+            return {
+                accepted: false,
+                eventId: event.eventId,
+                lifecycle: 'FAILED',
+                error: 'Event is not APPROVED',
+                reason: 'APPROVAL_REQUIRED',
+            };
+        }
+        if (this.queue.length >= this.maxQueueDepth) {
+            return {
+                accepted: false,
+                eventId: event.eventId,
+                lifecycle: 'FAILED',
+                error: `Voice queue capacity exceeded (current depth: ${this.queue.length}, max: ${this.maxQueueDepth})`,
+                reason: 'QUEUE_CAPACITY_EXCEEDED',
+            };
+        }
+        const text = (event.text ?? '').slice(0, this.maxTextLength);
+        const language = event.language ?? 'ja';
+        const speechId = this.enqueueSpeech(text, language, 1);
+        return {
+            accepted: true,
+            eventId: event.eventId,
+            lifecycle: 'STARTED',
+            metadata: {
+                speechId,
+                companionId: event.companionId,
+                correlationId: event.correlationId,
+            },
+        };
+    }
+    enqueueSpeech(text, language, priority = 0) {
+        if (this.queue.length >= this.maxQueueDepth) {
+            throw new Error(`Voice queue capacity exceeded (current depth: ${this.queue.length}, max: ${this.maxQueueDepth})`);
+        }
+        const boundedText = (text || '').slice(0, this.maxTextLength);
+        const id = `job_${Math.random().toString(36).substr(2, 9)}`;
+        this.queue.push({
+            id,
+            text: boundedText,
+            language,
+            priority,
+            sequence: this.sequenceCounter++
+        });
+        // Sort: highest priority first, then lowest sequence
+        this.queue.sort((a, b) => {
+            if (a.priority !== b.priority) {
+                return b.priority - a.priority;
+            }
+            return a.sequence - b.sequence;
+        });
+        this.processQueue();
+        return id;
+    }
+    onLifecycleEvent(callback) {
+        this.callbacks.push(callback);
+    }
+    getQueueStatus() {
+        return {
+            pending: this.queue.length,
+            current: this.currentJob
+        };
+    }
+    emit(event) {
+        for (const cb of this.callbacks) {
+            try {
+                cb(event);
+            }
+            catch (e) { }
+        }
+    }
+    async processQueue() {
+        if (this.isProcessing || this.queue.length === 0)
+            return;
+        this.isProcessing = true;
+        while (this.queue.length > 0) {
+            const job = this.queue.shift();
+            this.currentJob = job.id;
+            this.emit({ type: 'STARTED', speechId: job.id, text: job.text, language: job.language });
+            try {
+                const audioBuffer = await this.synthesize(job.text);
+                this.emit({ type: 'COMPLETED', speechId: job.id, text: job.text, language: job.language, audioBuffer });
+            }
+            catch (error) {
+                this.emit({ type: 'FAILED', speechId: job.id, text: job.text, language: job.language });
+            }
+            this.currentJob = undefined;
+        }
+        this.isProcessing = false;
+    }
+    async synthesize(text) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            // 1. /audio_query
+            const queryUrl = new URL('/audio_query', this.config.baseUrl);
+            queryUrl.searchParams.set('text', text);
+            queryUrl.searchParams.set('speaker', this.config.speakerId.toString());
+            const queryResponse = await fetch(queryUrl.toString(), {
+                method: 'POST',
+                headers: { 'Accept': 'application/json' },
+                signal: controller.signal,
+            });
+            if (!queryResponse.ok) {
+                throw new Error(`Voicevox audio_query failed: ${queryResponse.statusText}`);
+            }
+            const queryJson = await queryResponse.json();
+            // 2. /synthesis
+            const synthUrl = new URL('/synthesis', this.config.baseUrl);
+            synthUrl.searchParams.set('speaker', this.config.speakerId.toString());
+            const synthResponse = await fetch(synthUrl.toString(), {
+                method: 'POST',
+                headers: {
+                    'Accept': 'audio/wav',
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(queryJson),
+                signal: controller.signal,
+            });
+            if (!synthResponse.ok) {
+                throw new Error(`Voicevox synthesis failed: ${synthResponse.statusText}`);
+            }
+            const buffer = await synthResponse.arrayBuffer();
+            return new Uint8Array(buffer);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.VoicevoxAdapter = VoicevoxAdapter;

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+// Mock fetch
+global.fetch = jest.fn();
+describe('VoicevoxAdapter Queue Semantics', () => {
+    let adapter;
+    beforeEach(() => {
+        adapter = new index_1.VoicevoxAdapter({ baseUrl: 'http://localhost:50021', speakerId: 1 });
+        global.fetch.mockClear();
+    });
+    test('queue preserves priority and sequence ordering', async () => {
+        // We want to stop processQueue from consuming everything instantly so we can inspect it.
+        // Let's mock synthesize to never resolve immediately, or just inspect the queue property.
+        adapter.isProcessing = true; // Block processing
+        adapter.enqueueSpeech("Low 1", "en", 0);
+        adapter.enqueueSpeech("High 1", "en", 100);
+        adapter.enqueueSpeech("Low 2", "en", 0);
+        adapter.enqueueSpeech("High 2", "en", 100);
+        const queue = adapter.queue;
+        // High priority first, preserving insertion order among same priority
+        expect(queue[0].text).toBe("High 1");
+        expect(queue[1].text).toBe("High 2");
+        expect(queue[2].text).toBe("Low 1");
+        expect(queue[3].text).toBe("Low 2");
+    });
+    test('synthesize calls /audio_query and /synthesis', async () => {
+        global.fetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ some: "query_data" })
+        });
+        global.fetch.mockResolvedValueOnce({
+            ok: true,
+            arrayBuffer: async () => new ArrayBuffer(8)
+        });
+        const audio = await adapter.synthesize("Hello");
+        expect(audio.length).toBe(8);
+        expect(global.fetch).toHaveBeenCalledTimes(2);
+        const [queryCall, synthCall] = global.fetch.mock.calls;
+        expect(queryCall[0]).toContain("/audio_query?text=Hello&speaker=1");
+        expect(synthCall[0]).toContain("/synthesis?speaker=1");
+        expect(JSON.parse(synthCall[1].body).some).toBe("query_data");
+    });
+});
+describe('VoicevoxAdapter T5 Experience Event Interface', () => {
+    let adapter;
+    beforeEach(() => {
+        adapter = new index_1.VoicevoxAdapter({ baseUrl: 'http://localhost:50021', speakerId: 1 });
+    });
+    test('handleEvent processes valid approved voice event', async () => {
+        adapter.isProcessing = true; // prevent live http calls
+        const res = await adapter.handleEvent({
+            eventId: 'evt-voice-1',
+            companionId: 'companion-a',
+            responseId: 'resp-1',
+            correlationId: 'corr-1',
+            channel: 'public',
+            audienceId: 'audience-public',
+            approval: 'APPROVED',
+            kind: 'voice',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            text: 'Hello T5 voice',
+            language: 'en',
+            createdAt: new Date().toISOString(),
+        });
+        expect(res.accepted).toBe(true);
+        expect(res.lifecycle).toBe('STARTED');
+        expect(res.metadata?.speechId).toBeDefined();
+    });
+    test('handleEvent rejects unapproved event or incompatible kind', async () => {
+        const unapprovedRes = await adapter.handleEvent({
+            eventId: 'evt-voice-2',
+            companionId: 'companion-a',
+            responseId: 'resp-1',
+            correlationId: 'corr-1',
+            channel: 'public',
+            audienceId: 'audience-public',
+            approval: 'STAGED',
+            kind: 'voice',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            createdAt: new Date().toISOString(),
+        });
+        expect(unapprovedRes.accepted).toBe(false);
+        const incompatibleRes = await adapter.handleEvent({
+            eventId: 'evt-voice-3',
+            companionId: 'companion-a',
+            responseId: 'resp-1',
+            correlationId: 'corr-1',
+            channel: 'public',
+            audienceId: 'audience-public',
+            approval: 'APPROVED',
+            kind: 'avatar',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            createdAt: new Date().toISOString(),
+        });
+        expect(incompatibleRes.accepted).toBe(false);
+        expect(incompatibleRes.reason).toBe('INCOMPATIBLE_EVENT_KIND');
+    });
+    test('handleEvent enforces queue depth limits and applies backpressure', async () => {
+        const smallQueueAdapter = new index_1.VoicevoxAdapter({
+            baseUrl: 'http://localhost:50021',
+            speakerId: 1,
+            maxQueueDepth: 2,
+        });
+        smallQueueAdapter.isProcessing = true; // hold queue
+        // Fill queue to capacity
+        smallQueueAdapter.enqueueSpeech('msg 1', 'en');
+        smallQueueAdapter.enqueueSpeech('msg 2', 'en');
+        // Attempting to enqueue when full via enqueueSpeech throws
+        expect(() => smallQueueAdapter.enqueueSpeech('msg 3', 'en')).toThrow(/Voice queue capacity exceeded/);
+        // Attempting via handleEvent returns structured failure with QUEUE_CAPACITY_EXCEEDED
+        const eventRes = await smallQueueAdapter.handleEvent({
+            eventId: 'evt-voice-overflow',
+            companionId: 'companion-a',
+            responseId: 'resp-1',
+            correlationId: 'corr-1',
+            channel: 'public',
+            audienceId: 'audience-public',
+            approval: 'APPROVED',
+            kind: 'voice',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            text: 'overflow text',
+            createdAt: new Date().toISOString(),
+        });
+        expect(eventRes.accepted).toBe(false);
+        expect(eventRes.reason).toBe('QUEUE_CAPACITY_EXCEEDED');
+    });
+});

package/organ-manifest.json

@@ -0,0 +1,55 @@
+{
+  "name": "@siduri-x/voice",
+  "organType": "voice",
+  "version": "1.0.0",
+  "displayName": "Voice (VOICEVOX Speech Synthesis)",
+  "description": "Queued speech synthesis and audio rendering lifecycle adapter",
+  "entrypoint": "./dist/index.js",
+  "factory": "VoicevoxAdapter",
+  "configKey": "voice",
+  "configSchema": {
+    "type": "object",
+    "required": [
+      "provider"
+    ],
+    "properties": {
+      "provider": {
+        "type": "string",
+        "enum": [
+          "voicevox",
+          "none"
+        ]
+      },
+      "speakerId": {
+        "type": "number",
+        "default": 1
+      },
+      "baseUrl": {
+        "type": "string",
+        "default": "http://localhost:50021"
+      },
+      "maxQueueDepth": {
+        "type": "number",
+        "default": 50
+      }
+    }
+  },
+  "environment": [
+    {
+      "name": "VOICEVOX_URL",
+      "required": false,
+      "secret": false,
+      "default": "http://localhost:50021",
+      "description": "Base URL of the running VOICEVOX engine"
+    }
+  ],
+  "services": [
+    {
+      "name": "VOICEVOX Engine",
+      "kind": "http_service",
+      "optional": false
+    }
+  ],
+  "database": null,
+  "healthCheck": null
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@siduri-x/voice",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "jest --config jest.config.json"
+  },
+  "dependencies": {
+    "@siduri-x/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^26.2.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.3.3"
+  },
+  "description": "Voice organ for speech synthesis, voice output queuing, and TTS provider integration",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vxnuslabs/siduri-y",
+    "directory": "packages/organs/voice"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "organ-manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./organ-manifest.json": "./organ-manifest.json"
+  }
+}