@loonylabs/tts-middleware 0.1.1

package/dist/middleware/services/tts/types/provider-options.types.d.ts

@@ -0,0 +1,414 @@
+/**
+ * Provider-specific option types for TTS synthesis
+ *
+ * These types define all possible provider-specific parameters.
+ * All providers are typed NOW (MVP + Future) to prevent breaking API changes.
+ *
+ * @MVP ✅ Azure options are implemented
+ * @Future 🔮 Other providers typed but not implemented yet
+ */
+/**
+ * Azure Speech Services provider options
+ *
+ * @MVP ✅ Implemented
+ * @provider Azure Speech Services
+ *
+ * @see https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speech-synthesis-markup-voice
+ */
+export interface AzureProviderOptions {
+    /**
+     * Emotional tone of the speech
+     * @MVP ✅ Implemented
+     *
+     * @description Maps to SSML style attribute. Only supported by
+     * specific Azure neural voices (e.g., Jenny, Guy, Aria).
+     *
+     * @options 'sad', 'angry', 'cheerful', 'friendly', 'terrified',
+     *          'shouting', 'whispering', 'hopeful', 'gentle', 'excited',
+     *          'empathetic', 'calm', 'fearful', 'disgruntled', 'serious',
+     *          'depressed', 'embarrassed'
+     *
+     * @example 'cheerful'
+     */
+    emotion?: 'sad' | 'angry' | 'cheerful' | 'friendly' | 'terrified' | 'shouting' | 'whispering' | 'hopeful' | 'gentle' | 'excited' | 'empathetic' | 'calm' | 'fearful' | 'disgruntled' | 'serious' | 'depressed' | 'embarrassed';
+    /**
+     * Speaking style for the voice
+     * @MVP ✅ Implemented
+     *
+     * @description Maps to SSML style attribute. Voice-dependent feature.
+     *
+     * @options 'chat', 'customerservice', 'newscast', 'assistant',
+     *          'newscast-casual', 'newscast-formal', 'chat-casual',
+     *          'lyrical', 'advertisement-upbeat', 'narration-professional',
+     *          'narration-relaxed', 'sports-commentary',
+     *          'sports-commentary-excited'
+     *
+     * @example 'chat'
+     */
+    style?: 'chat' | 'customerservice' | 'newscast' | 'assistant' | 'newscast-casual' | 'newscast-formal' | 'chat-casual' | 'lyrical' | 'advertisement-upbeat' | 'narration-professional' | 'narration-relaxed' | 'sports-commentary' | 'sports-commentary-excited';
+    /**
+     * Style intensity/degree (0.01 to 2.0)
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @range 0.01 - 2.0
+     * @default 1.0
+     */
+    styleDegree?: number;
+    /**
+     * Role play scenario
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @options 'YoungAdultFemale', 'YoungAdultMale', 'OlderAdultFemale', 'OlderAdultMale', 'Girl', 'Boy'
+     */
+    role?: string;
+}
+/**
+ * OpenAI TTS provider options
+ *
+ * @Future 🔮 Not implemented in MVP
+ * @provider OpenAI TTS API
+ *
+ * @see https://platform.openai.com/docs/guides/text-to-speech
+ */
+export interface OpenAIProviderOptions {
+    /**
+     * TTS model to use
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @options
+     * - 'tts-1': Standard quality, lower latency
+     * - 'tts-1-hd': High quality, higher latency
+     * - 'gpt-4o-mini-tts': Token-based model
+     *
+     * @default 'tts-1'
+     */
+    model?: 'tts-1' | 'tts-1-hd' | 'gpt-4o-mini-tts';
+    /**
+     * Response format override
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description If not specified, uses the format from audio.format
+     *
+     * @options 'mp3', 'opus', 'aac', 'flac'
+     * @default 'mp3'
+     */
+    responseFormat?: 'mp3' | 'opus' | 'aac' | 'flac';
+}
+/**
+ * ElevenLabs TTS provider options
+ *
+ * @Future 🔮 Not implemented in MVP
+ * @provider ElevenLabs TTS API
+ *
+ * @see https://elevenlabs.io/docs/api-reference/text-to-speech
+ */
+export interface ElevenLabsProviderOptions {
+    /**
+     * Voice model ID
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @options
+     * - 'eleven_monolingual_v1': English only, lower latency
+     * - 'eleven_multilingual_v1': Multiple languages
+     * - 'eleven_multilingual_v2': Latest multilingual model
+     * - 'eleven_turbo_v2': Fastest, lower quality
+     *
+     * @default 'eleven_multilingual_v2'
+     */
+    model_id?: string;
+    /**
+     * Voice stability (0.0 - 1.0)
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Higher values = more stable/consistent, less expressive
+     * Lower values = more variable/expressive
+     *
+     * @range 0.0 - 1.0
+     * @default 0.5
+     */
+    stability?: number;
+    /**
+     * Similarity boost (0.0 - 1.0)
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Higher values = more similar to original voice sample
+     *
+     * @range 0.0 - 1.0
+     * @default 0.75
+     */
+    similarity_boost?: number;
+    /**
+     * Enable speaker boost
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Enhances voice clarity and reduces artifacts
+     *
+     * @default true
+     */
+    speaker_boost?: boolean;
+    /**
+     * Style exaggeration (0.0 - 1.0)
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Higher values = more exaggerated style (different from Azure style!)
+     *
+     * @range 0.0 - 1.0
+     * @default 0.0
+     */
+    style?: number;
+    /**
+     * Use speaker boost (legacy parameter)
+     * @Future 🔮 Not implemented in MVP
+     * @deprecated Use speaker_boost instead
+     */
+    use_speaker_boost?: boolean;
+}
+/**
+ * Google Cloud Text-to-Speech provider options
+ *
+ * @Future 🔮 Not implemented in MVP
+ * @provider Google Cloud TTS
+ *
+ * @see https://cloud.google.com/text-to-speech/docs/reference/rest/v1/text/synthesize
+ */
+export interface GoogleCloudProviderOptions {
+    /**
+     * Audio effects profile IDs
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Array of audio effect profile IDs to apply
+     *
+     * @options
+     * - 'wearable-class-device'
+     * - 'handset-class-device'
+     * - 'headphone-class-device'
+     * - 'small-bluetooth-speaker-class-device'
+     * - 'medium-bluetooth-speaker-class-device'
+     * - 'large-home-entertainment-class-device'
+     * - 'large-automotive-class-device'
+     * - 'telephony-class-application'
+     *
+     * @example ['headphone-class-device']
+     */
+    effectsProfileId?: string[];
+    /**
+     * Pitch adjustment in semitones
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Overrides the pitch parameter in AudioOptions if both are specified
+     *
+     * @range -20.0 to 20.0
+     * @default 0.0
+     */
+    pitchSemitones?: number;
+    /**
+     * Speaking rate multiplier
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Alternative to speed in AudioOptions
+     *
+     * @range 0.25 - 4.0
+     * @default 1.0
+     */
+    speakingRate?: number;
+    /**
+     * Volume gain in dB
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Alternative to volumeGainDb in AudioOptions
+     *
+     * @range -96.0 to 16.0
+     * @default 0.0
+     */
+    volumeGainDb?: number;
+}
+/**
+ * Deepgram TTS provider options
+ *
+ * @Future 🔮 Not implemented in MVP
+ * @provider Deepgram TTS API
+ *
+ * @see https://developers.deepgram.com/docs/tts-rest
+ */
+export interface DeepgramProviderOptions {
+    /**
+     * TTS model to use
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @options
+     * - 'aura-asteria-en': Female, US English
+     * - 'aura-luna-en': Female, US English
+     * - 'aura-stella-en': Female, US English
+     * - 'aura-athena-en': Female, UK English
+     * - 'aura-hera-en': Female, US English
+     * - 'aura-orion-en': Male, US English
+     * - 'aura-arcas-en': Male, US English
+     * - 'aura-perseus-en': Male, US English
+     * - 'aura-angus-en': Male, Irish English
+     * - 'aura-orpheus-en': Male, US English
+     * - 'aura-helios-en': Male, UK English
+     * - 'aura-zeus-en': Male, US English
+     *
+     * @default 'aura-asteria-en'
+     */
+    model?: string;
+    /**
+     * Audio encoding format
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Alternative to format in AudioOptions
+     *
+     * @options 'linear16', 'mulaw', 'alaw', 'opus', 'aac', 'mp3'
+     * @default 'linear16'
+     */
+    encoding?: 'linear16' | 'mulaw' | 'alaw' | 'opus' | 'aac' | 'mp3';
+    /**
+     * Audio container format
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @options 'wav', 'mp3', 'opus', 'flac'
+     * @default 'wav'
+     */
+    container?: 'wav' | 'mp3' | 'opus' | 'flac';
+    /**
+     * Bitrate for encoded audio
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @example '128000' (128 kbps)
+     */
+    bitrate?: string;
+    /**
+     * Sample rate in Hz
+     * @Future 🔮 Not implemented in MVP
+     *
+     * @description Alternative to sampleRate in AudioOptions
+     *
+     * @options 8000, 16000, 24000, 48000
+     * @default 24000
+     */
+    sampleRate?: number;
+}
+/**
+ * EdenAI TTS provider options
+ *
+ * @description EdenAI is a multi-provider aggregator that provides access
+ * to multiple TTS providers through a single API.
+ *
+ * @provider EdenAI (multi-provider aggregator)
+ *
+ * @see https://docs.edenai.co/reference/text_to_speech_create
+ */
+export interface EdenAIProviderOptions {
+    /**
+     * Underlying provider to use via EdenAI
+     *
+     * @description EdenAI acts as an aggregator, routing requests to the selected provider.
+     *
+     * @options
+     * - 'amazon': Amazon Polly
+     * - 'google': Google Cloud TTS
+     * - 'ibm': IBM Watson TTS
+     * - 'microsoft': Microsoft Azure Speech
+     * - 'openai': OpenAI TTS
+     * - 'elevenlabs': ElevenLabs TTS
+     *
+     * @default Auto-selected by EdenAI based on language/voice
+     */
+    provider?: 'amazon' | 'google' | 'ibm' | 'microsoft' | 'openai' | 'elevenlabs';
+    /**
+     * Speaking rate multiplier
+     *
+     * @description Controls the speed of speech synthesis
+     *
+     * @range 0.25 - 4.0
+     * @default 1.0
+     */
+    speaking_rate?: number;
+    /**
+     * Pitch adjustment in semitones
+     *
+     * @description Adjusts the pitch of the synthesized voice
+     *
+     * @range -20.0 to 20.0
+     * @default 0.0
+     */
+    speaking_pitch?: number;
+    /**
+     * Volume adjustment in decibels
+     *
+     * @description Adjusts the volume of the synthesized speech
+     *
+     * @range -96.0 to 16.0
+     * @default 0.0
+     */
+    speaking_volume?: number;
+    /**
+     * Audio format override
+     *
+     * @description If not specified, uses the format from audio.format
+     *
+     * @options 'mp3', 'wav', 'ogg', 'flac'
+     * @default 'mp3'
+     */
+    audio_format?: 'mp3' | 'wav' | 'ogg' | 'flac';
+    /**
+     * Sample rate in Hz
+     *
+     * @description If not specified, uses the sampleRate from audio options
+     *
+     * @options 8000, 16000, 22050, 24000, 44100, 48000
+     * @default 24000
+     */
+    sampling_rate?: number;
+    /**
+     * Fallback providers
+     *
+     * @description List of provider names to use as fallbacks if the primary provider fails
+     *
+     * @example ['google', 'amazon', 'microsoft']
+     */
+    fallback_providers?: string[];
+    /**
+     * Webhook URL for async notifications
+     *
+     * @description URL to receive notifications when synthesis completes (for async requests)
+     */
+    webhook_url?: string;
+    /**
+     * Webhook receiver identifier
+     *
+     * @description Identifier for the webhook receiver
+     */
+    webhook_receiver?: string;
+}
+/**
+ * Union type of all provider options
+ *
+ * @description Use this type when you need to accept any provider options
+ */
+export type ProviderOptions = AzureProviderOptions | OpenAIProviderOptions | ElevenLabsProviderOptions | GoogleCloudProviderOptions | DeepgramProviderOptions | EdenAIProviderOptions;
+/**
+ * Type guard to check if options are for Azure
+ */
+export declare function isAzureOptions(options: unknown): options is AzureProviderOptions;
+/**
+ * Type guard to check if options are for OpenAI
+ */
+export declare function isOpenAIOptions(options: unknown): options is OpenAIProviderOptions;
+/**
+ * Type guard to check if options are for ElevenLabs
+ */
+export declare function isElevenLabsOptions(options: unknown): options is ElevenLabsProviderOptions;
+/**
+ * Type guard to check if options are for Google Cloud
+ */
+export declare function isGoogleCloudOptions(options: unknown): options is GoogleCloudProviderOptions;
+/**
+ * Type guard to check if options are for Deepgram
+ */
+export declare function isDeepgramOptions(options: unknown): options is DeepgramProviderOptions;
+/**
+ * Type guard to check if options are for EdenAI
+ */
+export declare function isEdenAIOptions(options: unknown): options is EdenAIProviderOptions;
+//# sourceMappingURL=provider-options.types.d.ts.map

package/dist/middleware/services/tts/types/provider-options.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-options.types.d.ts","sourceRoot":"","sources":["../../../../../src/middleware/services/tts/types/provider-options.types.ts"],"names":[],"mappings":"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"}

package/dist/middleware/services/tts/types/provider-options.types.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Provider-specific option types for TTS synthesis
+ *
+ * These types define all possible provider-specific parameters.
+ * All providers are typed NOW (MVP + Future) to prevent breaking API changes.
+ *
+ * @MVP ✅ Azure options are implemented
+ * @Future 🔮 Other providers typed but not implemented yet
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAzureOptions = isAzureOptions;
+exports.isOpenAIOptions = isOpenAIOptions;
+exports.isElevenLabsOptions = isElevenLabsOptions;
+exports.isGoogleCloudOptions = isGoogleCloudOptions;
+exports.isDeepgramOptions = isDeepgramOptions;
+exports.isEdenAIOptions = isEdenAIOptions;
+/**
+ * Type guard to check if options are for Azure
+ */
+function isAzureOptions(options) {
+    return (typeof options === 'object' &&
+        options !== null &&
+        ('emotion' in options || 'style' in options));
+}
+/**
+ * Type guard to check if options are for OpenAI
+ */
+function isOpenAIOptions(options) {
+    return (typeof options === 'object' &&
+        options !== null &&
+        'model' in options &&
+        typeof options.model === 'string');
+}
+/**
+ * Type guard to check if options are for ElevenLabs
+ */
+function isElevenLabsOptions(options) {
+    return (typeof options === 'object' &&
+        options !== null &&
+        ('stability' in options || 'similarity_boost' in options));
+}
+/**
+ * Type guard to check if options are for Google Cloud
+ */
+function isGoogleCloudOptions(options) {
+    return (typeof options === 'object' &&
+        options !== null &&
+        ('effectsProfileId' in options || 'pitchSemitones' in options));
+}
+/**
+ * Type guard to check if options are for Deepgram
+ */
+function isDeepgramOptions(options) {
+    return (typeof options === 'object' &&
+        options !== null &&
+        ('encoding' in options || 'container' in options));
+}
+/**
+ * Type guard to check if options are for EdenAI
+ */
+function isEdenAIOptions(options) {
+    return (typeof options === 'object' &&
+        options !== null &&
+        ('speaking_rate' in options ||
+            'speaking_pitch' in options ||
+            'speaking_volume' in options ||
+            'fallback_providers' in options ||
+            'webhook_url' in options));
+}
+//# sourceMappingURL=provider-options.types.js.map

package/dist/middleware/services/tts/types/provider-options.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-options.types.js","sourceRoot":"","sources":["../../../../../src/middleware/services/tts/types/provider-options.types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA0cH,wCAQC;AAKD,0CASC;AAKD,kDAQC;AAKD,oDAQC;AAKD,8CAQC;AAKD,0CAYC;AAjFD;;GAEG;AACH,SAAgB,cAAc,CAC5B,OAAgB;IAEhB,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,CAAC,SAAS,IAAI,OAAO,IAAI,OAAO,IAAI,OAAO,CAAC,CAC7C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAC7B,OAAgB;IAEhB,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,OAAO,IAAI,OAAO;QAClB,OAAQ,OAA8B,CAAC,KAAK,KAAK,QAAQ,CAC1D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CACjC,OAAgB;IAEhB,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,CAAC,WAAW,IAAI,OAAO,IAAI,kBAAkB,IAAI,OAAO,CAAC,CAC1D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,oBAAoB,CAClC,OAAgB;IAEhB,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,CAAC,kBAAkB,IAAI,OAAO,IAAI,gBAAgB,IAAI,OAAO,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAC/B,OAAgB;IAEhB,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,CAAC,UAAU,IAAI,OAAO,IAAI,WAAW,IAAI,OAAO,CAAC,CAClD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAC7B,OAAgB;IAEhB,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,CAAC,eAAe,IAAI,OAAO;YACzB,gBAAgB,IAAI,OAAO;YAC3B,iBAAiB,IAAI,OAAO;YAC5B,oBAAoB,IAAI,OAAO;YAC/B,aAAa,IAAI,OAAO,CAAC,CAC5B,CAAC;AACJ,CAAC"}

package/dist/middleware/services/tts/utils/character-counter.utils.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Character Counting Utilities
+ *
+ * @description Accurate character counting for billing purposes.
+ * This is billing-critical code - all functions must be 100% accurate
+ * and match provider billing methodologies.
+ *
+ * @critical This code directly impacts customer billing. Any bugs here
+ * could result in incorrect charges. Test coverage MUST be 100%.
+ */
+/**
+ * Count all characters in text for billing purposes
+ *
+ * @param text - The input text to count
+ * @returns The total number of characters including spaces, punctuation, and newlines
+ *
+ * @description
+ * This function counts ALL characters in the input text:
+ * - Letters (a-z, A-Z)
+ * - Numbers (0-9)
+ * - Spaces and tabs
+ * - Newlines (\n, \r\n)
+ * - Punctuation and special characters
+ * - Unicode characters (counted as 1 character each)
+ * - Emoji (counted as 1 character each, regardless of byte length)
+ *
+ * @example
+ * ```typescript
+ * countCharacters("Hello World!") // returns 12
+ * countCharacters("Guten Morgen")  // returns 12
+ * countCharacters("Hello 👋")      // returns 8
+ * countCharacters("")              // returns 0
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length
+ *
+ * @critical Billing-critical function. Must be 100% accurate.
+ */
+export declare function countCharacters(text: string): number;
+/**
+ * Count characters in text after removing SSML markup
+ *
+ * @param text - The input text (may contain SSML tags)
+ * @returns The number of characters excluding SSML tags
+ *
+ * @description
+ * This function removes all SSML (Speech Synthesis Markup Language) tags
+ * before counting characters. This is used when the middleware generates
+ * SSML internally but billing is based on the plain text content.
+ *
+ * SSML tags removed include:
+ * - `<speak>`, `</speak>` - Root element
+ * - `<voice>`, `</voice>` - Voice selection
+ * - `<prosody>`, `</prosody>` - Prosody (rate, pitch, volume)
+ * - `<emphasis>`, `</emphasis>` - Emphasis
+ * - `<break>` - Pauses
+ * - `<say-as>`, `</say-as>` - Interpret-as hints
+ * - `<phoneme>`, `</phoneme>` - Phonetic pronunciation
+ * - `<sub>`, `</sub>` - Substitution
+ * - `<lang>`, `</lang>` - Language switching
+ * - And all other SSML tags
+ *
+ * @example
+ * ```typescript
+ * countCharactersWithoutSSML("<speak>Hello</speak>")
+ * // returns 5 (only "Hello" is counted)
+ *
+ * countCharactersWithoutSSML('<voice name="en-US-Jenny">Text</voice>')
+ * // returns 4 (only "Text" is counted)
+ *
+ * countCharactersWithoutSSML('<prosody rate="slow">Hello World</prosody>')
+ * // returns 11 (only "Hello World" is counted)
+ * ```
+ *
+ * @critical Billing-critical function. Must match Azure's character counting.
+ */
+export declare function countCharactersWithoutSSML(text: string): number;
+/**
+ * Validate that character count matches expected range
+ *
+ * @param text - The input text
+ * @param minChars - Minimum expected characters (default: 0)
+ * @param maxChars - Maximum expected characters (default: Infinity)
+ * @returns True if count is within range
+ * @throws {RangeError} If character count is outside expected range
+ *
+ * @description
+ * This is a utility function to validate text length before synthesis.
+ * Providers often have limits on input text length (e.g., Azure: 3000 chars per request).
+ *
+ * @example
+ * ```typescript
+ * validateCharacterCount("Hello", 1, 100) // returns true
+ * validateCharacterCount("", 1, 100)       // throws RangeError
+ * ```
+ */
+export declare function validateCharacterCount(text: string, minChars?: number, maxChars?: number): boolean;
+/**
+ * Count billable characters (alias for countCharacters)
+ *
+ * @param text - The input text
+ * @returns The number of billable characters
+ *
+ * @description
+ * Semantic alias for countCharacters to make billing calculations clearer.
+ * This is the function consumers should use when calculating costs.
+ *
+ * @example
+ * ```typescript
+ * const text = "Hello World!";
+ * const chars = countBillableCharacters(text); // 12
+ * const costUSD = (chars / 1_000_000) * 16; // $16 per 1M chars
+ * ```
+ */
+export declare function countBillableCharacters(text: string): number;
+/**
+ * Estimate audio duration based on character count
+ *
+ * @param text - The input text
+ * @param speedMultiplier - Speech speed (0.5 to 2.0, default: 1.0)
+ * @param charsPerSecond - Average characters spoken per second (default: 15)
+ * @returns Estimated duration in milliseconds
+ *
+ * @description
+ * Provides a rough estimate of audio duration based on character count.
+ * This is NOT exact and varies by:
+ * - Language (some languages are more verbose)
+ * - Voice (different voices have different pacing)
+ * - Content (technical terms take longer)
+ * - Speed setting
+ *
+ * Default assumption: ~15 characters per second at normal speed
+ * (roughly 150-180 words per minute, assuming 5-6 chars per word)
+ *
+ * @example
+ * ```typescript
+ * estimateAudioDuration("Hello World!", 1.0) // ~800ms
+ * estimateAudioDuration("Hello World!", 0.5) // ~1600ms (slower)
+ * ```
+ */
+export declare function estimateAudioDuration(text: string, speedMultiplier?: number, charsPerSecond?: number): number;
+/**
+ * Format character count for display
+ *
+ * @param count - The character count
+ * @returns Formatted string (e.g., "1.2K chars", "1.5M chars")
+ *
+ * @description
+ * Formats large character counts in human-readable format.
+ * Useful for displaying usage statistics.
+ *
+ * @example
+ * ```typescript
+ * formatCharacterCount(500)         // "500 chars"
+ * formatCharacterCount(1234)        // "1.2K chars"
+ * formatCharacterCount(1500000)     // "1.5M chars"
+ * ```
+ */
+export declare function formatCharacterCount(count: number): string;
+//# sourceMappingURL=character-counter.utils.d.ts.map

package/dist/middleware/services/tts/utils/character-counter.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-counter.utils.d.ts","sourceRoot":"","sources":["../../../../../src/middleware/services/tts/utils/character-counter.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAU,EACpB,QAAQ,GAAE,MAAiB,GAC1B,OAAO,CAgBT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,eAAe,GAAE,MAAY,EAC7B,cAAc,GAAE,MAAW,GAC1B,MAAM,CAWR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAU1D"}