@t3lnet/sceneforge 1.0.7 → 1.0.8

package/dist/index.d.cts

@@ -457,6 +457,128 @@ declare function demoType(page: Page, selector: string, text: string, options?:
     delayBetweenChars?: number;
 }): Promise<void>;
 
+/**
+ * Voice settings that affect the generated audio output
+ */
+interface VoiceCacheSettings {
+    stability: number;
+    similarityBoost: number;
+    style: number;
+    useSpeakerBoost: boolean;
+}
+/**
+ * A single entry in the voice cache
+ */
+interface VoiceCacheEntry {
+    key: string;
+    voiceId: string;
+    modelId: string;
+    text: string;
+    voiceSettings: VoiceCacheSettings;
+    audioFileName: string;
+    durationMs: number;
+    fileSizeBytes: number;
+    createdAt: string;
+    lastUsedAt: string;
+}
+/**
+ * Configuration for the voice cache
+ */
+interface VoiceCacheConfig {
+    /** Directory where cache files are stored */
+    cacheDir: string;
+    /** Whether caching is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Statistics about the voice cache
+ */
+interface VoiceCacheStats {
+    totalEntries: number;
+    totalSizeBytes: number;
+    oldestEntry: string | null;
+    newestEntry: string | null;
+    hitCount: number;
+    missCount: number;
+}
+/**
+ * Voice cache manager for storing and retrieving synthesized audio.
+ * This helps avoid duplicate API calls to ElevenLabs for the same text/voice combinations.
+ */
+declare class VoiceCache {
+    private config;
+    private index;
+    private stats;
+    private indexDirty;
+    constructor(config: VoiceCacheConfig);
+    /**
+     * Gets the path to the cache index file
+     */
+    private get indexPath();
+    /**
+     * Gets the path to the audio cache directory
+     */
+    private get audioDir();
+    /**
+     * Whether caching is enabled
+     */
+    get enabled(): boolean;
+    /**
+     * Initializes the cache directory and loads the index
+     */
+    initialize(): Promise<void>;
+    /**
+     * Loads the cache index from disk
+     */
+    private loadIndex;
+    /**
+     * Saves the cache index to disk
+     */
+    saveIndex(): Promise<void>;
+    /**
+     * Looks up a cached audio file by its synthesis parameters.
+     * Returns the cache entry if found, null otherwise.
+     */
+    get(voiceId: string, modelId: string, text: string, voiceSettings: VoiceCacheSettings): Promise<VoiceCacheEntry | null>;
+    /**
+     * Gets the full path to a cached audio file
+     */
+    getAudioPath(entry: VoiceCacheEntry): string;
+    /**
+     * Stores a synthesized audio file in the cache.
+     * The audio data should be provided as a Buffer.
+     */
+    put(voiceId: string, modelId: string, text: string, voiceSettings: VoiceCacheSettings, audioData: Buffer, durationMs: number): Promise<VoiceCacheEntry>;
+    /**
+     * Removes a specific entry from the cache
+     */
+    remove(key: string): Promise<boolean>;
+    /**
+     * Clears all entries from the cache
+     */
+    clear(): Promise<number>;
+    /**
+     * Lists all entries in the cache
+     */
+    list(): Promise<VoiceCacheEntry[]>;
+    /**
+     * Gets statistics about the cache
+     */
+    getStats(): Promise<VoiceCacheStats>;
+    /**
+     * Prunes entries older than the specified age (in days)
+     */
+    pruneOlderThan(days: number): Promise<number>;
+    /**
+     * Validates the cache by checking that all indexed files exist
+     * and removing orphaned entries
+     */
+    validate(): Promise<{
+        valid: number;
+        removed: number;
+    }>;
+}
+
 interface RetryOptions {
     retries?: number;
     minDelayMs?: number;
@@ -470,6 +592,8 @@ interface VoiceSynthesisConfig {
     voiceId: string;
     modelId?: string;
     outputFormat?: "mp3_44100_128" | "mp3_44100_192" | "pcm_16000" | "pcm_22050" | "pcm_24000";
+    /** Voice cache configuration. Set to false to disable caching entirely. */
+    cache?: VoiceCacheConfig | false;
 }
 /**
  * Script segment from the generated JSON
@@ -518,7 +642,17 @@ interface VoiceSynthesisResult {
 declare class VoiceSynthesizer {
     private client;
     private config;
+    private cache;
+    private cacheInitialized;
     constructor(config: VoiceSynthesisConfig);
+    /**
+     * Ensures the cache is initialized before use
+     */
+    private ensureCacheInitialized;
+    /**
+     * Gets the voice cache instance (if enabled)
+     */
+    getCache(): VoiceCache | null;
     /**
      * List available voices (useful for finding voice IDs)
      */
@@ -535,8 +669,11 @@ declare class VoiceSynthesizer {
         similarityBoost?: number;
         style?: number;
         useSpeakerBoost?: boolean;
+        /** Skip cache lookup (still stores result in cache) */
+        skipCache?: boolean;
     }): Promise<{
         durationMs: number;
+        fromCache: boolean;
     }>;
     /**
      * Generate a sound effect from text description

package/dist/index.d.ts

@@ -457,6 +457,128 @@ declare function demoType(page: Page, selector: string, text: string, options?:
     delayBetweenChars?: number;
 }): Promise<void>;
 
+/**
+ * Voice settings that affect the generated audio output
+ */
+interface VoiceCacheSettings {
+    stability: number;
+    similarityBoost: number;
+    style: number;
+    useSpeakerBoost: boolean;
+}
+/**
+ * A single entry in the voice cache
+ */
+interface VoiceCacheEntry {
+    key: string;
+    voiceId: string;
+    modelId: string;
+    text: string;
+    voiceSettings: VoiceCacheSettings;
+    audioFileName: string;
+    durationMs: number;
+    fileSizeBytes: number;
+    createdAt: string;
+    lastUsedAt: string;
+}
+/**
+ * Configuration for the voice cache
+ */
+interface VoiceCacheConfig {
+    /** Directory where cache files are stored */
+    cacheDir: string;
+    /** Whether caching is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Statistics about the voice cache
+ */
+interface VoiceCacheStats {
+    totalEntries: number;
+    totalSizeBytes: number;
+    oldestEntry: string | null;
+    newestEntry: string | null;
+    hitCount: number;
+    missCount: number;
+}
+/**
+ * Voice cache manager for storing and retrieving synthesized audio.
+ * This helps avoid duplicate API calls to ElevenLabs for the same text/voice combinations.
+ */
+declare class VoiceCache {
+    private config;
+    private index;
+    private stats;
+    private indexDirty;
+    constructor(config: VoiceCacheConfig);
+    /**
+     * Gets the path to the cache index file
+     */
+    private get indexPath();
+    /**
+     * Gets the path to the audio cache directory
+     */
+    private get audioDir();
+    /**
+     * Whether caching is enabled
+     */
+    get enabled(): boolean;
+    /**
+     * Initializes the cache directory and loads the index
+     */
+    initialize(): Promise<void>;
+    /**
+     * Loads the cache index from disk
+     */
+    private loadIndex;
+    /**
+     * Saves the cache index to disk
+     */
+    saveIndex(): Promise<void>;
+    /**
+     * Looks up a cached audio file by its synthesis parameters.
+     * Returns the cache entry if found, null otherwise.
+     */
+    get(voiceId: string, modelId: string, text: string, voiceSettings: VoiceCacheSettings): Promise<VoiceCacheEntry | null>;
+    /**
+     * Gets the full path to a cached audio file
+     */
+    getAudioPath(entry: VoiceCacheEntry): string;
+    /**
+     * Stores a synthesized audio file in the cache.
+     * The audio data should be provided as a Buffer.
+     */
+    put(voiceId: string, modelId: string, text: string, voiceSettings: VoiceCacheSettings, audioData: Buffer, durationMs: number): Promise<VoiceCacheEntry>;
+    /**
+     * Removes a specific entry from the cache
+     */
+    remove(key: string): Promise<boolean>;
+    /**
+     * Clears all entries from the cache
+     */
+    clear(): Promise<number>;
+    /**
+     * Lists all entries in the cache
+     */
+    list(): Promise<VoiceCacheEntry[]>;
+    /**
+     * Gets statistics about the cache
+     */
+    getStats(): Promise<VoiceCacheStats>;
+    /**
+     * Prunes entries older than the specified age (in days)
+     */
+    pruneOlderThan(days: number): Promise<number>;
+    /**
+     * Validates the cache by checking that all indexed files exist
+     * and removing orphaned entries
+     */
+    validate(): Promise<{
+        valid: number;
+        removed: number;
+    }>;
+}
+
 interface RetryOptions {
     retries?: number;
     minDelayMs?: number;
@@ -470,6 +592,8 @@ interface VoiceSynthesisConfig {
     voiceId: string;
     modelId?: string;
     outputFormat?: "mp3_44100_128" | "mp3_44100_192" | "pcm_16000" | "pcm_22050" | "pcm_24000";
+    /** Voice cache configuration. Set to false to disable caching entirely. */
+    cache?: VoiceCacheConfig | false;
 }
 /**
  * Script segment from the generated JSON
@@ -518,7 +642,17 @@ interface VoiceSynthesisResult {
 declare class VoiceSynthesizer {
     private client;
     private config;
+    private cache;
+    private cacheInitialized;
     constructor(config: VoiceSynthesisConfig);
+    /**
+     * Ensures the cache is initialized before use
+     */
+    private ensureCacheInitialized;
+    /**
+     * Gets the voice cache instance (if enabled)
+     */
+    getCache(): VoiceCache | null;
     /**
      * List available voices (useful for finding voice IDs)
      */
@@ -535,8 +669,11 @@ declare class VoiceSynthesizer {
         similarityBoost?: number;
         style?: number;
         useSpeakerBoost?: boolean;
+        /** Skip cache lookup (still stores result in cache) */
+        skipCache?: boolean;
     }): Promise<{
         durationMs: number;
+        fromCache: boolean;
     }>;
     /**
      * Generate a sound effect from text description