@moxxy/plugin-tts-gemini 0.0.0-stage → 0.42.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { type Plugin, type SynthesizeOptions, type SynthesisResult, type Synthesizer, type SynthesizerCreateContext } from '@moxxy/sdk';
+export declare const GEMINI_TTS_SYNTHESIZER_NAME = "gemini-tts";
+export declare const GEMINI_TTS_MODEL = "gemini-3.8-flash-lite-tts";
+export declare const GEMINI_API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
+export declare const GEMINI_TTS_API_KEY_NAME = "GEMINI_API_KEY";
+declare const DEFAULT_VOICE = "Fola";
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface GeminiTtsOptions {
+    readonly apiKey?: string;
+    readonly getSecret?: (name: string) => Promise<string | null>;
+    readonly voice?: string;
+    readonly baseURL?: string;
+    readonly fetchImpl?: FetchLike;
+}
+export interface GeminiVoice {
+    readonly id: string;
+    readonly displayName: string;
+    readonly languageCode?: string;
+    readonly description?: string;
+}
+export declare class GeminiTtsSynthesizer implements Synthesizer {
+    readonly name = "gemini-tts";
+    private readonly explicitKey;
+    private readonly getSecret;
+    private readonly defaultVoice;
+    private readonly baseURL;
+    private readonly fetchImpl;
+    constructor(options?: GeminiTtsOptions);
+    synthesize(text: string, opts?: SynthesizeOptions): Promise<SynthesisResult>;
+    private resolveKey;
+}
+export declare function listGeminiVoices(apiKey: string, options?: {
+    readonly baseURL?: string;
+    readonly fetchImpl?: FetchLike;
+    readonly signal?: AbortSignal;
+}): Promise<ReadonlyArray<GeminiVoice>>;
+export declare function listGeminiVoicesWithSecret(getSecret: (name: string) => Promise<string | null>, options?: {
+    readonly fetchImpl?: FetchLike;
+    readonly signal?: AbortSignal;
+}): Promise<ReadonlyArray<GeminiVoice>>;
+export declare function buildGeminiTtsPlugin(options?: {
+    readonly defaults?: GeminiTtsOptions;
+}): Plugin;
+export { DEFAULT_VOICE };
+export { type SynthesizerCreateContext };
+declare const _default: Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,MAAM,EACX,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,wBAAwB,EAC9B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,2BAA2B,eAAe,CAAC;AACxD,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAC5D,eAAO,MAAM,mBAAmB,qDAAqD,CAAC;AACtF,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AAExD,QAAA,MAAM,aAAa,SAAS,CAAC;AAI7B,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,oBAAqB,YAAW,WAAW;IACtD,QAAQ,CAAC,IAAI,gBAA+B;IAE5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyD;IACnF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,OAAO,GAAE,gBAAqB;IAQpC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;YAyExE,UAAU;CAYzB;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACzG,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAwDrC;AAED,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EACnD,OAAO,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC9E,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAWrC;AA2CD,wBAAgB,oBAAoB,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAAO,GAAG,MAAM,CAiBnG;AAkCD,OAAO,EAAE,aAAa,EAAE,CAAC;AACzB,OAAO,EAAE,KAAK,wBAAwB,EAAE,CAAC;;AAEzC,wBAAsC"}

package/dist/index.js

@@ -0,0 +1,253 @@
+import { classifyHttpStatus, classifyNetworkError, MoxxyError, definePlugin, defineSynthesizer, } from '@moxxy/sdk';
+export const GEMINI_TTS_SYNTHESIZER_NAME = 'gemini-tts';
+export const GEMINI_TTS_MODEL = 'gemini-3.8-flash-lite-tts';
+export const GEMINI_API_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
+export const GEMINI_TTS_API_KEY_NAME = 'GEMINI_API_KEY';
+const DEFAULT_VOICE = 'Fola';
+const VOICE_PAGE_SIZE = 1000;
+const MAX_VOICE_PAGES = 20;
+export class GeminiTtsSynthesizer {
+    name = GEMINI_TTS_SYNTHESIZER_NAME;
+    explicitKey;
+    getSecret;
+    defaultVoice;
+    baseURL;
+    fetchImpl;
+    constructor(options = {}) {
+        this.explicitKey = options.apiKey;
+        this.getSecret = options.getSecret;
+        this.defaultVoice = options.voice ?? DEFAULT_VOICE;
+        this.baseURL = trimTrailingSlashes(options.baseURL ?? GEMINI_API_BASE_URL);
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async synthesize(text, opts = {}) {
+        opts.signal?.throwIfAborted();
+        const apiKey = await this.resolveKey();
+        opts.signal?.throwIfAborted();
+        const url = `${this.baseURL}/interactions`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-goog-api-key': apiKey,
+                },
+                body: JSON.stringify({
+                    model: GEMINI_TTS_MODEL,
+                    input: [{
+                            type: 'user_input',
+                            content: [{
+                                    type: 'text',
+                                    text,
+                                    annotations: [{ type: 'speech_metadata', style: speechStyle(opts.rate) }],
+                                }],
+                        }],
+                    response_format: { type: 'audio' },
+                    generation_config: {
+                        speech_config: [{ voice: opts.voice ?? this.defaultVoice }],
+                    },
+                }),
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+        }
+        catch (error) {
+            if (opts.signal?.aborted)
+                throw opts.signal.reason ?? error;
+            const network = classifyNetworkError(error, { provider: 'gemini-tts', url });
+            if (network)
+                throw network;
+            throw error;
+        }
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            const classified = classifyHttpStatus(response.status, {
+                provider: 'gemini-tts',
+                url,
+                body,
+            });
+            if (classified)
+                throw classified;
+            throw new MoxxyError({
+                code: 'PROVIDER_BAD_REQUEST',
+                message: `Gemini text-to-speech returned HTTP ${response.status}.`,
+                context: { provider: 'gemini-tts', url, status: response.status },
+            });
+        }
+        const payload = await response.json();
+        const audioPart = payload.steps
+            ?.flatMap((step) => step.content ?? [])
+            .find((part) => part.type === 'audio' && part.data);
+        if (!audioPart?.data) {
+            throw new MoxxyError({
+                code: 'PROVIDER_UNKNOWN_RESPONSE',
+                message: 'Gemini text-to-speech returned no audio data.',
+                context: { provider: 'gemini-tts', url },
+            });
+        }
+        const rawAudio = Buffer.from(audioPart.data, 'base64');
+        const encodedAudio = wrapLinearPcmAsWav(rawAudio, audioPart.mime_type || 'audio/wav');
+        return {
+            audio: new Uint8Array(encodedAudio.audio),
+            mimeType: encodedAudio.mimeType,
+        };
+    }
+    async resolveKey() {
+        const key = this.explicitKey ?? (await this.getSecret?.(GEMINI_TTS_API_KEY_NAME)) ?? null;
+        if (!key) {
+            throw new MoxxyError({
+                code: 'AUTH_NO_CREDENTIALS',
+                message: 'No Gemini API key is configured for cloud text-to-speech.',
+                hint: 'Add a Gemini API key in Settings → Voice. It is stored in the local vault.',
+                context: { provider: 'gemini-tts' },
+            });
+        }
+        return key;
+    }
+}
+export async function listGeminiVoices(apiKey, options = {}) {
+    const baseURL = trimTrailingSlashes(options.baseURL ?? GEMINI_API_BASE_URL);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const voices = [];
+    let pageToken;
+    for (let page = 0; page < MAX_VOICE_PAGES; page += 1) {
+        options.signal?.throwIfAborted();
+        const query = new URLSearchParams({ page_size: String(VOICE_PAGE_SIZE) });
+        if (pageToken)
+            query.set('page_token', pageToken);
+        const url = `${baseURL}/voices?${query.toString()}`;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                headers: { 'x-goog-api-key': apiKey },
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
+            const network = classifyNetworkError(error, { provider: 'gemini-tts', url });
+            if (network)
+                throw network;
+            throw error;
+        }
+        if (!response.ok) {
+            const classified = classifyHttpStatus(response.status, {
+                provider: 'gemini-tts',
+                url,
+                body: await response.text().catch(() => ''),
+            });
+            if (classified)
+                throw classified;
+            throw new MoxxyError({
+                code: 'PROVIDER_BAD_REQUEST',
+                message: `Gemini voice library returned HTTP ${response.status}.`,
+                context: { provider: 'gemini-tts', url, status: response.status },
+            });
+        }
+        const payload = await response.json();
+        for (const voice of payload.voices ?? []) {
+            if (!voice.id)
+                continue;
+            voices.push({
+                id: voice.id,
+                displayName: voice.display_name || voice.id,
+                ...(voice.language_code ? { languageCode: voice.language_code } : {}),
+                ...(voice.description ? { description: voice.description } : {}),
+            });
+        }
+        pageToken = payload.next_page_token;
+        if (!pageToken)
+            return voices;
+    }
+    throw new MoxxyError({
+        code: 'PROVIDER_UNKNOWN_RESPONSE',
+        message: `Gemini voice library exceeded the ${MAX_VOICE_PAGES}-page safety limit.`,
+        context: { provider: 'gemini-tts' },
+    });
+}
+export async function listGeminiVoicesWithSecret(getSecret, options = {}) {
+    const apiKey = await getSecret(GEMINI_TTS_API_KEY_NAME);
+    if (!apiKey) {
+        throw new MoxxyError({
+            code: 'AUTH_NO_CREDENTIALS',
+            message: 'No Gemini API key is configured for cloud text-to-speech.',
+            hint: 'Add a Gemini API key in Settings → Voice. It is stored in the local vault.',
+            context: { provider: 'gemini-tts' },
+        });
+    }
+    return listGeminiVoices(apiKey, options);
+}
+/** Gemini returns raw PCM (`audio/L16;codec=pcm;rate=24000`) rather than a
+ *  container. The browser audio element consumes WAV, so wrap supported PCM
+ *  before crossing the IPC boundary. Already-containerized formats pass through. */
+function wrapLinearPcmAsWav(audio, mimeType) {
+    if (/^audio\/(?:wav|x-wav)(?:;|$)/i.test(mimeType))
+        return { audio, mimeType };
+    const [type, ...params] = mimeType.split(';').map((part) => part.trim());
+    const format = type?.split('/')[1] ?? '';
+    const linear = /^L(8|16|24|32)$/i.exec(format);
+    if (!/^audio\/(?:L(?:8|16|24|32)|pcm)$/i.test(type ?? ''))
+        return { audio, mimeType };
+    const bitsPerSample = linear ? Number(linear[1]) : 16;
+    const rateParam = params.find((param) => param.toLowerCase().startsWith('rate='));
+    const parsedRate = rateParam ? Number(rateParam.slice(rateParam.indexOf('=') + 1)) : 24_000;
+    const sampleRate = Number.isInteger(parsedRate) && parsedRate > 0 ? parsedRate : 24_000;
+    const channels = 1;
+    const blockAlign = channels * bitsPerSample / 8;
+    const header = Buffer.alloc(44);
+    header.write('RIFF', 0);
+    header.writeUInt32LE(36 + audio.length, 4);
+    header.write('WAVE', 8);
+    header.write('fmt ', 12);
+    header.writeUInt32LE(16, 16);
+    header.writeUInt16LE(1, 20);
+    header.writeUInt16LE(channels, 22);
+    header.writeUInt32LE(sampleRate, 24);
+    header.writeUInt32LE(sampleRate * blockAlign, 28);
+    header.writeUInt16LE(blockAlign, 32);
+    header.writeUInt16LE(bitsPerSample, 34);
+    header.write('data', 36);
+    header.writeUInt32LE(audio.length, 40);
+    return { audio: Buffer.concat([header, audio]), mimeType: 'audio/wav' };
+}
+function speechStyle(rate) {
+    if (rate !== undefined && rate >= 1.1)
+        return 'Natural, conversational delivery at a slightly brisk pace.';
+    if (rate !== undefined && rate <= 0.9)
+        return 'Natural, conversational delivery at a slightly slower pace.';
+    return 'Natural, conversational delivery.';
+}
+export function buildGeminiTtsPlugin(options = {}) {
+    const defaults = options.defaults ?? {};
+    return definePlugin({
+        name: '@moxxy/plugin-tts-gemini',
+        version: '0.0.0',
+        synthesizers: [
+            defineSynthesizer({
+                name: GEMINI_TTS_SYNTHESIZER_NAME,
+                displayName: 'Cloud (Gemini Flash-Lite)',
+                create: (ctx) => new GeminiTtsSynthesizer({
+                    ...defaults,
+                    ...optionsFromConfig(ctx.config),
+                    ...(ctx.getSecret ? { getSecret: ctx.getSecret } : {}),
+                }),
+            }),
+        ],
+    });
+}
+function optionsFromConfig(config) {
+    return typeof config.voice === 'string' && config.voice.length > 0
+        ? { voice: config.voice }
+        : {};
+}
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value[end - 1] === '/')
+        end -= 1;
+    return value.slice(0, end);
+}
+export { DEFAULT_VOICE };
+export {};
+export default buildGeminiTtsPlugin();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@moxxy/plugin-tts-gemini",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.42.0",
+  "description": "Google Gemini Flash-Lite text-to-speech extension for moxxy.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "tts",
+    "text-to-speech",
+    "gemini",
+    "google"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-tts-gemini"
+  },
+  "author": "Moxxy contributors",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "synthesizer"
+    }
+  },
+  "dependencies": {
+    "@moxxy/sdk": "0.42.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
 }

package/src/gemini-tts.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest';
+import {
+  GeminiTtsSynthesizer,
+  buildGeminiTtsPlugin,
+  listGeminiVoices,
+  GEMINI_TTS_MODEL,
+  GEMINI_TTS_SYNTHESIZER_NAME,
+  type FetchLike,
+} from './index.js';
+
+interface CapturedCall {
+  readonly url: string;
+  readonly init: RequestInit;
+}
+
+function makeFetch(body: unknown, status = 200): { fetchImpl: FetchLike; calls: CapturedCall[] } {
+  const calls: CapturedCall[] = [];
+  const fetchImpl: FetchLike = async (url, init) => {
+    calls.push({ url, init });
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: { 'content-type': 'application/json' },
+    });
+  };
+  return { fetchImpl, calls };
+}
+
+const audioResponse = {
+  steps: [{
+    type: 'model_output',
+    content: [{
+      type: 'audio',
+      mime_type: 'audio/wav',
+      data: Buffer.from('RIFFaudio').toString('base64'),
+    }],
+  }],
+  usage: {
+    total_input_tokens: 9,
+    total_output_tokens: 75,
+  },
+};
+
+function rawPcmResponse(seconds: number): unknown {
+  const pcm16 = Buffer.alloc(24_000 * 2 * seconds);
+  return {
+    steps: [{
+      type: 'model_output',
+      content: [{
+        type: 'audio',
+        mime_type: 'audio/L16;codec=pcm;rate=24000',
+        data: pcm16.toString('base64'),
+      }],
+    }],
+  };
+}
+
+describe('GeminiTtsSynthesizer', () => {
+  it('requests one short text chunk through Interactions and returns the WAV', async () => {
+    const { fetchImpl, calls } = makeFetch(audioResponse);
+    const synth = new GeminiTtsSynthesizer({
+      apiKey: 'test-key',
+      fetchImpl,
+    });
+
+    const result = await synth.synthesize('Pierwsze zdanie.', { voice: 'Fola', language: 'pl' });
+
+    expect(result.mimeType).toBe('audio/wav');
+    expect(Buffer.from(result.audio).toString()).toBe('RIFFaudio');
+    expect(result).not.toHaveProperty('usage');
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.url).toBe('https://generativelanguage.googleapis.com/v1beta/interactions');
+    expect((calls[0]?.init.headers as Record<string, string>)['x-goog-api-key']).toBe('test-key');
+    expect(JSON.parse(calls[0]?.init.body as string)).toMatchObject({
+      model: GEMINI_TTS_MODEL,
+      input: [{ type: 'user_input', content: [{
+        type: 'text',
+        text: 'Pierwsze zdanie.',
+        annotations: [{ type: 'speech_metadata', style: 'Natural, conversational delivery.' }],
+      }] }],
+      response_format: { type: 'audio' },
+      generation_config: { speech_config: [{ voice: 'Fola' }] },
+    });
+  });
+
+  it('wraps raw PCM from Google as WAV and returns audio only', async () => {
+    const { fetchImpl } = makeFetch(rawPcmResponse(1));
+    const synth = new GeminiTtsSynthesizer({ apiKey: 'test-key', fetchImpl });
+
+    const result = await synth.synthesize('A short sentence.');
+
+    expect(result.mimeType).toBe('audio/wav');
+    expect(Buffer.from(result.audio).toString('ascii', 0, 4)).toBe('RIFF');
+    expect(result).not.toHaveProperty('usage');
+  });
+
+  it('resolves the API key lazily from the vault and honors cancellation', async () => {
+    const { fetchImpl, calls } = makeFetch(audioResponse);
+    const synth = new GeminiTtsSynthesizer({
+      getSecret: async (name) => name === 'GEMINI_API_KEY' ? 'vault-key' : null,
+      fetchImpl,
+    });
+    const controller = new AbortController();
+
+    await synth.synthesize('Cześć.', { signal: controller.signal });
+    expect((calls[0]?.init.headers as Record<string, string>)['x-goog-api-key']).toBe('vault-key');
+    expect(calls[0]?.init.signal).toBe(controller.signal);
+
+    controller.abort(new Error('interrupted'));
+    await expect(synth.synthesize('Przerwane.', { signal: controller.signal })).rejects.toThrow('interrupted');
+    expect(calls).toHaveLength(1);
+  });
+
+  it('uses a rotated vault key on the next sentence without rebuilding the synthesizer', async () => {
+    let key = 'first-key';
+    const { fetchImpl, calls } = makeFetch(audioResponse);
+    const synth = new GeminiTtsSynthesizer({
+      getSecret: async () => key,
+      fetchImpl,
+    });
+
+    await synth.synthesize('Pierwsze zdanie.');
+    key = 'rotated-key';
+    await synth.synthesize('Następne zdanie.');
+
+    expect(calls.map(({ init }) => (init.headers as Record<string, string>)['x-goog-api-key']))
+      .toEqual(['first-key', 'rotated-key']);
+  });
+
+  it('classifies missing credentials and provider errors', async () => {
+    const noKey = new GeminiTtsSynthesizer({ getSecret: async () => null, fetchImpl: makeFetch(audioResponse).fetchImpl });
+    await expect(noKey.synthesize('Hej.')).rejects.toMatchObject({ code: 'AUTH_NO_CREDENTIALS' });
+
+    const limited = new GeminiTtsSynthesizer({ apiKey: 'bad', fetchImpl: makeFetch({ error: { message: 'quota' } }, 429).fetchImpl });
+    await expect(limited.synthesize('Hej.')).rejects.toMatchObject({ code: 'PROVIDER_RATE_LIMITED' });
+  });
+});
+
+describe('listGeminiVoices', () => {
+  it('loads all pages and returns ids with display metadata', async () => {
+    const calls: string[] = [];
+    const fetchImpl: FetchLike = async (url) => {
+      calls.push(url);
+      if (url.includes('page_token')) {
+        return Response.json({ voices: [{ id: 'voice_2', display_name: 'Warm Fola', language_code: 'pl-PL' }] });
+      }
+      return Response.json({
+        voices: [{ id: 'Fola', display_name: 'Fola', language_code: 'en-US' }],
+        next_page_token: 'next-page',
+      });
+    };
+
+    const voices = await listGeminiVoices('test-key', { fetchImpl });
+
+    expect(voices).toEqual([
+      { id: 'Fola', displayName: 'Fola', languageCode: 'en-US' },
+      { id: 'voice_2', displayName: 'Warm Fola', languageCode: 'pl-PL' },
+    ]);
+    expect(calls).toHaveLength(2);
+    expect(calls[1]).toContain('page_token=next-page');
+  });
+});
+
+describe('buildGeminiTtsPlugin', () => {
+  it('registers a single Gemini synthesizer with the selected default voice', () => {
+    const plugin = buildGeminiTtsPlugin();
+    expect(plugin.synthesizers).toHaveLength(1);
+    expect(plugin.synthesizers?.[0]?.name).toBe(GEMINI_TTS_SYNTHESIZER_NAME);
+
+    const synth = plugin.synthesizers?.[0]?.create({ config: { voice: 'Fola' } });
+    expect(synth.name).toBe(GEMINI_TTS_SYNTHESIZER_NAME);
+  });
+});

package/src/index.ts

@@ -0,0 +1,316 @@
+import {
+  classifyHttpStatus,
+  classifyNetworkError,
+  MoxxyError,
+  definePlugin,
+  defineSynthesizer,
+  type Plugin,
+  type SynthesizeOptions,
+  type SynthesisResult,
+  type Synthesizer,
+  type SynthesizerCreateContext,
+} from '@moxxy/sdk';
+
+export const GEMINI_TTS_SYNTHESIZER_NAME = 'gemini-tts';
+export const GEMINI_TTS_MODEL = 'gemini-3.8-flash-lite-tts';
+export const GEMINI_API_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
+export const GEMINI_TTS_API_KEY_NAME = 'GEMINI_API_KEY';
+
+const DEFAULT_VOICE = 'Fola';
+const VOICE_PAGE_SIZE = 1000;
+const MAX_VOICE_PAGES = 20;
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface GeminiTtsOptions {
+  readonly apiKey?: string;
+  readonly getSecret?: (name: string) => Promise<string | null>;
+  readonly voice?: string;
+  readonly baseURL?: string;
+  readonly fetchImpl?: FetchLike;
+}
+
+export interface GeminiVoice {
+  readonly id: string;
+  readonly displayName: string;
+  readonly languageCode?: string;
+  readonly description?: string;
+}
+
+export class GeminiTtsSynthesizer implements Synthesizer {
+  readonly name = GEMINI_TTS_SYNTHESIZER_NAME;
+
+  private readonly explicitKey: string | undefined;
+  private readonly getSecret: ((name: string) => Promise<string | null>) | undefined;
+  private readonly defaultVoice: string;
+  private readonly baseURL: string;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(options: GeminiTtsOptions = {}) {
+    this.explicitKey = options.apiKey;
+    this.getSecret = options.getSecret;
+    this.defaultVoice = options.voice ?? DEFAULT_VOICE;
+    this.baseURL = trimTrailingSlashes(options.baseURL ?? GEMINI_API_BASE_URL);
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  async synthesize(text: string, opts: SynthesizeOptions = {}): Promise<SynthesisResult> {
+    opts.signal?.throwIfAborted();
+    const apiKey = await this.resolveKey();
+    opts.signal?.throwIfAborted();
+
+    const url = `${this.baseURL}/interactions`;
+    let response: Response;
+    try {
+      response = await this.fetchImpl(url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-goog-api-key': apiKey,
+        },
+        body: JSON.stringify({
+          model: GEMINI_TTS_MODEL,
+          input: [{
+            type: 'user_input',
+            content: [{
+              type: 'text',
+              text,
+              annotations: [{ type: 'speech_metadata', style: speechStyle(opts.rate) }],
+            }],
+          }],
+          response_format: { type: 'audio' },
+          generation_config: {
+            speech_config: [{ voice: opts.voice ?? this.defaultVoice }],
+          },
+        }),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+      });
+    } catch (error) {
+      if (opts.signal?.aborted) throw opts.signal.reason ?? error;
+      const network = classifyNetworkError(error, { provider: 'gemini-tts', url });
+      if (network) throw network;
+      throw error;
+    }
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      const classified = classifyHttpStatus(response.status, {
+        provider: 'gemini-tts',
+        url,
+        body,
+      });
+      if (classified) throw classified;
+      throw new MoxxyError({
+        code: 'PROVIDER_BAD_REQUEST',
+        message: `Gemini text-to-speech returned HTTP ${response.status}.`,
+        context: { provider: 'gemini-tts', url, status: response.status },
+      });
+    }
+
+    const payload = await response.json() as InteractionsResponse;
+    const audioPart = payload.steps
+      ?.flatMap((step) => step.content ?? [])
+      .find((part) => part.type === 'audio' && part.data);
+    if (!audioPart?.data) {
+      throw new MoxxyError({
+        code: 'PROVIDER_UNKNOWN_RESPONSE',
+        message: 'Gemini text-to-speech returned no audio data.',
+        context: { provider: 'gemini-tts', url },
+      });
+    }
+
+    const rawAudio = Buffer.from(audioPart.data, 'base64');
+    const encodedAudio = wrapLinearPcmAsWav(rawAudio, audioPart.mime_type || 'audio/wav');
+    return {
+      audio: new Uint8Array(encodedAudio.audio),
+      mimeType: encodedAudio.mimeType,
+    };
+  }
+
+  private async resolveKey(): Promise<string> {
+    const key = this.explicitKey ?? (await this.getSecret?.(GEMINI_TTS_API_KEY_NAME)) ?? null;
+    if (!key) {
+      throw new MoxxyError({
+        code: 'AUTH_NO_CREDENTIALS',
+        message: 'No Gemini API key is configured for cloud text-to-speech.',
+        hint: 'Add a Gemini API key in Settings → Voice. It is stored in the local vault.',
+        context: { provider: 'gemini-tts' },
+      });
+    }
+    return key;
+  }
+}
+
+export async function listGeminiVoices(
+  apiKey: string,
+  options: { readonly baseURL?: string; readonly fetchImpl?: FetchLike; readonly signal?: AbortSignal } = {},
+): Promise<ReadonlyArray<GeminiVoice>> {
+  const baseURL = trimTrailingSlashes(options.baseURL ?? GEMINI_API_BASE_URL);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const voices: GeminiVoice[] = [];
+  let pageToken: string | undefined;
+
+  for (let page = 0; page < MAX_VOICE_PAGES; page += 1) {
+    options.signal?.throwIfAborted();
+    const query = new URLSearchParams({ page_size: String(VOICE_PAGE_SIZE) });
+    if (pageToken) query.set('page_token', pageToken);
+    const url = `${baseURL}/voices?${query.toString()}`;
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        headers: { 'x-goog-api-key': apiKey },
+        ...(options.signal ? { signal: options.signal } : {}),
+      });
+    } catch (error) {
+      if (options.signal?.aborted) throw options.signal.reason ?? error;
+      const network = classifyNetworkError(error, { provider: 'gemini-tts', url });
+      if (network) throw network;
+      throw error;
+    }
+    if (!response.ok) {
+      const classified = classifyHttpStatus(response.status, {
+        provider: 'gemini-tts',
+        url,
+        body: await response.text().catch(() => ''),
+      });
+      if (classified) throw classified;
+      throw new MoxxyError({
+        code: 'PROVIDER_BAD_REQUEST',
+        message: `Gemini voice library returned HTTP ${response.status}.`,
+        context: { provider: 'gemini-tts', url, status: response.status },
+      });
+    }
+
+    const payload = await response.json() as VoicesListResponse;
+    for (const voice of payload.voices ?? []) {
+      if (!voice.id) continue;
+      voices.push({
+        id: voice.id,
+        displayName: voice.display_name || voice.id,
+        ...(voice.language_code ? { languageCode: voice.language_code } : {}),
+        ...(voice.description ? { description: voice.description } : {}),
+      });
+    }
+    pageToken = payload.next_page_token;
+    if (!pageToken) return voices;
+  }
+
+  throw new MoxxyError({
+    code: 'PROVIDER_UNKNOWN_RESPONSE',
+    message: `Gemini voice library exceeded the ${MAX_VOICE_PAGES}-page safety limit.`,
+    context: { provider: 'gemini-tts' },
+  });
+}
+
+export async function listGeminiVoicesWithSecret(
+  getSecret: (name: string) => Promise<string | null>,
+  options: { readonly fetchImpl?: FetchLike; readonly signal?: AbortSignal } = {},
+): Promise<ReadonlyArray<GeminiVoice>> {
+  const apiKey = await getSecret(GEMINI_TTS_API_KEY_NAME);
+  if (!apiKey) {
+    throw new MoxxyError({
+      code: 'AUTH_NO_CREDENTIALS',
+      message: 'No Gemini API key is configured for cloud text-to-speech.',
+      hint: 'Add a Gemini API key in Settings → Voice. It is stored in the local vault.',
+      context: { provider: 'gemini-tts' },
+    });
+  }
+  return listGeminiVoices(apiKey, options);
+}
+
+/** Gemini returns raw PCM (`audio/L16;codec=pcm;rate=24000`) rather than a
+ *  container. The browser audio element consumes WAV, so wrap supported PCM
+ *  before crossing the IPC boundary. Already-containerized formats pass through. */
+function wrapLinearPcmAsWav(
+  audio: Buffer,
+  mimeType: string,
+): { readonly audio: Buffer; readonly mimeType: string } {
+  if (/^audio\/(?:wav|x-wav)(?:;|$)/i.test(mimeType)) return { audio, mimeType };
+  const [type, ...params] = mimeType.split(';').map((part) => part.trim());
+  const format = type?.split('/')[1] ?? '';
+  const linear = /^L(8|16|24|32)$/i.exec(format);
+  if (!/^audio\/(?:L(?:8|16|24|32)|pcm)$/i.test(type ?? '')) return { audio, mimeType };
+  const bitsPerSample = linear ? Number(linear[1]) : 16;
+  const rateParam = params.find((param) => param.toLowerCase().startsWith('rate='));
+  const parsedRate = rateParam ? Number(rateParam.slice(rateParam.indexOf('=') + 1)) : 24_000;
+  const sampleRate = Number.isInteger(parsedRate) && parsedRate > 0 ? parsedRate : 24_000;
+  const channels = 1;
+  const blockAlign = channels * bitsPerSample / 8;
+  const header = Buffer.alloc(44);
+  header.write('RIFF', 0);
+  header.writeUInt32LE(36 + audio.length, 4);
+  header.write('WAVE', 8);
+  header.write('fmt ', 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(channels, 22);
+  header.writeUInt32LE(sampleRate, 24);
+  header.writeUInt32LE(sampleRate * blockAlign, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(bitsPerSample, 34);
+  header.write('data', 36);
+  header.writeUInt32LE(audio.length, 40);
+  return { audio: Buffer.concat([header, audio]), mimeType: 'audio/wav' };
+}
+
+function speechStyle(rate: number | undefined): string {
+  if (rate !== undefined && rate >= 1.1) return 'Natural, conversational delivery at a slightly brisk pace.';
+  if (rate !== undefined && rate <= 0.9) return 'Natural, conversational delivery at a slightly slower pace.';
+  return 'Natural, conversational delivery.';
+}
+
+export function buildGeminiTtsPlugin(options: { readonly defaults?: GeminiTtsOptions } = {}): Plugin {
+  const defaults = options.defaults ?? {};
+  return definePlugin({
+    name: '@moxxy/plugin-tts-gemini',
+    version: '0.0.0',
+    synthesizers: [
+      defineSynthesizer({
+        name: GEMINI_TTS_SYNTHESIZER_NAME,
+        displayName: 'Cloud (Gemini Flash-Lite)',
+        create: (ctx) => new GeminiTtsSynthesizer({
+          ...defaults,
+          ...optionsFromConfig(ctx.config),
+          ...(ctx.getSecret ? { getSecret: ctx.getSecret } : {}),
+        }),
+      }),
+    ],
+  });
+}
+
+function optionsFromConfig(config: Record<string, unknown>): Pick<GeminiTtsOptions, 'voice'> {
+  return typeof config.voice === 'string' && config.voice.length > 0
+    ? { voice: config.voice }
+    : {};
+}
+
+function trimTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === '/') end -= 1;
+  return value.slice(0, end);
+}
+
+interface InteractionsResponse {
+  readonly steps?: ReadonlyArray<{
+    readonly content?: ReadonlyArray<{
+      readonly type?: string;
+      readonly data?: string;
+      readonly mime_type?: string;
+    }>;
+  }>;
+}
+
+interface VoicesListResponse {
+  readonly voices?: ReadonlyArray<{
+    readonly id?: string;
+    readonly display_name?: string;
+    readonly language_code?: string;
+    readonly description?: string;
+  }>;
+  readonly next_page_token?: string;
+}
+
+export { DEFAULT_VOICE };
+export { type SynthesizerCreateContext };
+
+export default buildGeminiTtsPlugin();

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.