retiam 2.0.2 → 2.0.3

package/dist/libs/explainer/types.d.ts

@@ -1,3 +1,4 @@
+import { ElevenLabsGenerateOptions } from '../tts/core/types';
 /** A visual profile is independent of the topic and teaching sequence. */
 export type StyleId = 'mathematical' | 'excalidraw' | 'minimal' | 'cinematic';
 export interface StyleProfile {
@@ -39,6 +40,8 @@ export interface LessonClaim {
 export interface NarrationSegment {
     id: string;
     text: string;
+    /** Optional synthesis text with delivery tags; text remains clean for captions/cues. */
+    speechText?: string;
     pauseAfterMs?: number;
 }
 /** Phrases are scoped to a segment. Repeated phrases require an explicit occurrence (1-based). */
@@ -73,6 +76,7 @@ export interface LessonPlan {
         speed?: number;
         pitch?: string;
         volume?: number;
+        elevenlabs?: ElevenLabsGenerateOptions;
     };
     sources: LessonSource[];
     claims?: LessonClaim[];
@@ -85,6 +89,7 @@ export interface TimedWord {
 }
 export interface SpeechAsset {
     text: string;
+    speechText?: string;
     durationMs: number;
     words: TimedWord[];
     url?: string;

package/dist/libs/tts/animations/Speak.d.ts

@@ -1,13 +1,17 @@
 import { Animation, AnimOptions, Entity, Scene } from 'retiam';
 import { Subtitles } from '../components/Subtitles';
-import { MsEdgeVoiceId, TTSAudioResult } from '../core/types';
+import { VoiceId, TTSAudioResult, ElevenLabsGenerateOptions } from '../core/types';
 export interface SpeakOptions extends AnimOptions {
-    /** Microsoft Edge neural voice ID for narration. */
-    voice?: MsEdgeVoiceId;
-    /** Speaking rate multiplier. Defaults to 1.0. */
+    /** Voice ID; omitted values use the active provider's default. */
+    voice?: VoiceId;
+    /** Speaking rate multiplier; omitted values inherit the provider default. */
     speed?: number;
     /** Pitch shift (for MsEdge TTS, e.g. "+0Hz", "+5st", "+10%"). */
     pitch?: string | number;
+    /** Clean subtitle text when speech contains delivery or pronunciation tags. */
+    displayText?: string;
+    /** Per-utterance ElevenLabs delivery and model overrides. */
+    elevenlabs?: ElevenLabsGenerateOptions;
     /** Optional Subtitles component to automatically synchronize closed captions. */
     subtitles?: Subtitles;
     /** Optional entity to animate with speaking micro-pulses. */
@@ -22,7 +26,7 @@ export interface SpeakOptions extends AnimOptions {
 /**
  * Retiam Animation for spoken narration.
  *
- * Synchronizes Microsoft Edge neural speech, voiceover auto-ducking
+ * Synchronizes speech from the active provider, voiceover auto-ducking
  * on Retiam's [[AudioManager]], timeline pacing, closed captions/subtitles, and entity micro-animations.
  *
  * @example
@@ -37,7 +41,7 @@ export interface SpeakOptions extends AnimOptions {
  */
 export declare class Speak extends Animation {
     readonly text: string;
-    readonly voice: string;
+    readonly voice?: string;
     readonly speed: number;
     readonly pitch?: string | number;
     readonly subtitles?: Subtitles;
@@ -46,6 +50,8 @@ export declare class Speak extends Animation {
     readonly duckingRatio: number;
     readonly volume: number;
     private _audioResult;
+    private _audioTask;
+    private readonly _synthesisOptions;
     private _isStarted;
     private _baseScale;
     constructor(text: string, options?: SpeakOptions);
@@ -64,7 +70,7 @@ export declare class Speak extends Animation {
 /**
  * High-level helper function to speak narration in a Retiam Scene.
  *
- * Synthesizes speech using Microsoft Edge neural TTS,
+ * Synthesizes speech using the active provider,
  * synchronizes subtitles, ducks background music, and pauses scene progression
  * for the duration of the audio.
  *

package/dist/libs/tts/components/TTSNarrationComponent.d.ts

@@ -1,10 +1,11 @@
 import { Component } from 'retiam';
-import { MsEdgeVoiceId, TTSAudioResult, TTSGenerateOptions, TTSPlaybackOptions } from '../core/types';
+import { VoiceId, TTSAudioResult, TTSGenerateOptions, TTSPlaybackOptions, ElevenLabsGenerateOptions } from '../core/types';
 export interface TTSNarrationOptions {
-    /** Preferred Microsoft Edge neural voice ID. */
-    voice?: MsEdgeVoiceId;
-    /** Default speaking rate. Defaults to 1.0. */
+    /** Voice ID; omitted values use the active provider's default. */
+    voice?: VoiceId;
+    /** Speaking rate override; omitted values inherit the provider default. */
     speed?: number;
+    elevenlabs?: ElevenLabsGenerateOptions;
     /** Whether to visually pulse the entity's scale during speech. Defaults to true. */
     animateSpeaking?: boolean;
     /** Scale pulse amplitude during speech (e.g. 0.06 = ±6% pulse). Defaults to 0.05. */
@@ -19,12 +20,13 @@ export interface TTSNarrationOptions {
 /**
  * Retiam ECS Component that empowers any visual Entity with voice narration capabilities.
  *
- * Features automatic Microsoft Edge neural speech synthesis,
+ * Features speech synthesis through the active provider,
  * voiceover ducking, and synchronized micro-interaction visual pulses while speaking.
  */
 export declare class TTSNarrationComponent extends Component {
-    voice: string;
-    speed: number;
+    voice?: string;
+    speed?: number;
+    elevenlabs?: ElevenLabsGenerateOptions;
     animateSpeaking: boolean;
     pulseAmplitude: number;
     pulseFrequency: number;

package/dist/libs/tts/core/TTSCache.d.ts

@@ -7,9 +7,9 @@ export declare class TTSCache {
     private readonly cache;
     constructor(maxSize?: number);
     private static createKey;
-    get(text: string, voice: string, speed: number): TTSAudioResult | undefined;
-    set(text: string, voice: string, speed: number, result: TTSAudioResult): void;
-    has(text: string, voice: string, speed: number): boolean;
+    get(text: string, voice: string, speed: number, variant?: string): TTSAudioResult | undefined;
+    set(text: string, voice: string, speed: number, result: TTSAudioResult, variant?: string): void;
+    has(text: string, voice: string, speed: number, variant?: string): boolean;
     clear(): void;
     get size(): number;
 }

package/dist/libs/tts/core/TTSClient.d.ts

@@ -34,7 +34,7 @@ export declare class TTSClient {
     /** Releases provider resources and cached audio. */
     dispose(): Promise<void>;
 }
-/** Global Microsoft Edge speech facade for Retiam scenes. */
+/** Global speech facade for Retiam scenes. */
 export declare class TTS {
     /** Replaces the global client configuration and restores the built-in provider. */
     static configure(config: TTSConfig): void;
@@ -46,7 +46,7 @@ export declare class TTS {
     static get provider(): ITTSProvider;
     /** Synthesizes text to speech. */
     static synthesize(text: string, options?: TTSGenerateOptions): Promise<TTSAudioResult>;
-    /** Explicit alias for Microsoft Edge neural synthesis. */
+    /** Legacy synthesis alias; follows the active provider. */
     static msedge(text: string, options?: TTSGenerateOptions): Promise<TTSAudioResult>;
     /** Streams synthesized speech sentence by sentence. */
     static stream(text: string, options?: TTSGenerateOptions): AsyncGenerator<TTSStreamChunk>;
@@ -57,7 +57,7 @@ export declare class TTS {
     }>;
     /** Returns the active provider's voices. */
     static getVoices(): VoiceInfo[];
-    /** Finds a Microsoft Edge neural voice. */
+    /** Finds a voice exposed by the active provider. */
     static findVoice(query: string): VoiceInfo | undefined;
     /** Recommended default voice. */
     static readonly DEFAULT_VOICE: MsEdgeVoiceId;

package/dist/libs/tts/core/types.d.ts

@@ -4,7 +4,7 @@ import { AudioManager, VoiceoverOptions } from 'retiam';
  * The open string union preserves autocomplete while accepting any current voice ID.
  */
 export type MsEdgeVoiceId = "en-US-JennyNeural" | "en-US-GuyNeural" | "en-US-AriaNeural" | "en-US-AndrewNeural" | "en-US-AvaNeural" | "en-US-EmmaNeural" | "en-US-BrianNeural" | "en-US-ChristopherNeural" | "en-US-EricNeural" | "en-US-MichelleNeural" | "en-US-AnaNeural" | "en-US-SteffanNeural" | "en-US-AndrewMultilingualNeural" | "en-US-AvaMultilingualNeural" | "en-US-BrianMultilingualNeural" | "en-US-EmmaMultilingualNeural" | "en-GB-SoniaNeural" | "en-GB-RyanNeural" | "en-GB-LibbyNeural" | "en-GB-ThomasNeural" | "en-AU-NatashaNeural" | "en-AU-WilliamMultilingualNeural" | "en-CA-ClaraNeural" | "en-CA-LiamNeural" | "en-IN-NeerjaNeural" | "en-IN-PrabhatNeural" | "es-ES-ElviraNeural" | "fr-FR-DeniseNeural" | "fr-FR-HenriNeural" | "de-DE-KatjaNeural" | "de-DE-KillianNeural" | "it-IT-ElsaNeural" | "ja-JP-NanamiNeural" | "ja-JP-KeitaNeural" | "zh-CN-XiaoxiaoNeural" | "zh-CN-YunxiNeural" | (string & {});
-/** Voice identifier accepted by the built-in TTS provider. */
+/** Provider voice identifier; preserves autocomplete for the built-in Edge voices. */
 export type VoiceId = MsEdgeVoiceId;
 /** Word or sentence timing metadata for synchronized captions. */
 export interface WordBoundary {
@@ -18,13 +18,13 @@ export interface VoiceInfo {
     id: string;
     name: string;
     language: string;
-    gender: "Female" | "Male";
+    gender: "Female" | "Male" | "Unknown";
     traits?: string;
     targetQuality?: string;
     overallGrade?: string;
-    provider?: "msedge";
+    provider?: "msedge" | "elevenlabs";
 }
-/** Global configuration for Microsoft Edge speech synthesis. */
+/** Shared speech configuration and built-in Microsoft Edge settings. */
 export interface TTSConfig {
     /** Browser proxy endpoint. Defaults to "/api/tts/msedge". */
     msedgeEndpoint?: string;
@@ -33,10 +33,48 @@ export interface TTSConfig {
     /** Maximum utterances retained by the LRU cache. Defaults to 128. */
     maxCacheSize?: number;
 }
+export type ElevenLabsModelId = "eleven_multilingual_v2" | "eleven_v3" | "eleven_v4" | "eleven_flash_v2_5" | "eleven_turbo_v2_5" | (string & {});
+/** MP3 formats supported by the Retiam audio container and duration parser. */
+export type ElevenLabsOutputFormat = "mp3_22050_32" | "mp3_24000_48" | "mp3_44100_32" | "mp3_44100_64" | "mp3_44100_96" | "mp3_44100_128" | "mp3_44100_192";
+/** Settings are model-dependent; omitted fields use the voice's stored settings. */
+export interface ElevenLabsVoiceSettings {
+    stability?: number;
+    similarityBoost?: number;
+    style?: number;
+    useSpeakerBoost?: boolean;
+    /** Speaking-rate multiplier, from 0.7 to 1.2. */
+    speed?: number;
+}
+export interface ElevenLabsGenerateOptions {
+    modelId?: ElevenLabsModelId;
+    voiceSettings?: ElevenLabsVoiceSettings;
+    languageCode?: string;
+    seed?: number;
+    previousText?: string;
+    nextText?: string;
+    applyTextNormalization?: "auto" | "on" | "off";
+    pronunciationDictionaries?: {
+        id: string;
+        versionId?: string;
+    }[];
+}
+/** Passed directly to ElevenLabsTTSProvider.init(); no Vite plugin is required. */
+export interface ElevenLabsTTSConfig extends TTSConfig, ElevenLabsGenerateOptions {
+    /** Caller-supplied credential, retained only by this provider instance. */
+    apiKey?: string;
+    /** Default ElevenLabs voice ID. May also be supplied per utterance. */
+    voiceId?: string;
+    /** Defaults to https://api.elevenlabs.io. */
+    baseUrl?: string;
+    /** Defaults to mp3_44100_128. */
+    outputFormat?: ElevenLabsOutputFormat;
+    /** Request timeout, including response download. Defaults to 90000 ms. */
+    timeoutMs?: number;
+}
 /** Per-utterance synthesis options. */
 export interface TTSGenerateOptions {
-    /** Microsoft Edge neural voice ID. Defaults to "en-US-JennyNeural". */
-    voice?: MsEdgeVoiceId;
+    /** Voice ID; defaults to the active provider's configured voice. */
+    voice?: VoiceId;
     /** Speaking-rate multiplier. Defaults to 1.0. */
     speed?: number;
     /** SSML pitch shift such as "+0Hz", "+5st", or "+10%". */
@@ -45,6 +83,10 @@ export interface TTSGenerateOptions {
     volume?: string | number;
     /** Custom sentence splitter for progressive streaming. */
     splitPattern?: RegExp;
+    /** Caption text when synthesis text contains delivery tags or pronunciation markup. */
+    displayText?: string;
+    /** ElevenLabs model, delivery, pronunciation, and continuity overrides. */
+    elevenlabs?: ElevenLabsGenerateOptions;
 }
 /** Playback options for Retiam's voiceover bus. */
 export interface TTSPlaybackOptions extends VoiceoverOptions {

package/dist/libs/tts/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Retiam Text-To-Speech (TTS) Suite powered by Microsoft Edge neural voices.
+ * Retiam speech synthesis, expressive narration, and subtitles with Edge and ElevenLabs.
  *
  * @packageDocumentation
  */
@@ -11,6 +11,7 @@ export * from './core/TTSCache';
 export * from './core/TTSClient';
 export * from './providers/ITTSProvider';
 export * from './providers/MsEdgeTTSProvider';
+export * from './providers/ElevenLabsTTSProvider';
 export * from './components/TTSNarrationComponent';
 export * from './components/Subtitles';
 export * from './animations/Speak';