expo-edge-speech/dist/utils/audioUtils.d.ts

Text-to-speech library for Expo using Microsoft Edge TTS service

/**
 * This module provides utilities for processing audio data from Edge TTS
 * including MP3 format validation, binary message parsing, metadata extraction,
 * and audio streaming buffer management.
 */
/**
 * Message header format used by Edge TTS
 */
export interface EdgeTTSMessageHeader {
    [key: string]: string;
}
/**
 * Represents a parsed Edge TTS binary message containing audio data
 * Based on Edge TTS protocol: Int16 header length + JSON header + MP3 data
 */
export interface EdgeTTSBinaryMessage {
    /** Length of the header in bytes */
    headerLength: number;
    /** Parsed header containing metadata */
    header: Record<string, string>;
    /** Binary audio data (MP3 format) */
    audioData: ArrayBuffer;
}
/**
 * Audio metadata extracted from Edge TTS
 */
export interface EdgeTTSAudioMetadata {
    /** Audio format identifier */
    format: string;
    /** Sample rate in Hz */
    sampleRate: number;
    /** Bit rate in kbps */
    bitRate: number;
    /** Number of audio channels */
    channels: number;
    /** Estimated duration in milliseconds */
    estimatedDuration?: number;
}
/**
 * Word boundary data with Edge TTS timing
 */
export interface EdgeTTSWordBoundary {
    /** Character index in original text */
    charIndex: number;
    /** Character length of the word */
    charLength: number;
    /** Raw offset in Edge TTS ticks */
    rawOffset: number;
    /** Compensated offset in Edge TTS ticks */
    compensatedOffset: number;
    /** Offset in milliseconds */
    offsetMs: number;
}
/**
 * Audio buffer for streaming MP3 chunks
 */
export interface AudioStreamBuffer {
    /** Accumulated audio chunks */
    chunks: ArrayBuffer[];
    /** Total size in bytes */
    totalSize: number;
    /** Metadata from first chunk */
    metadata?: EdgeTTSAudioMetadata;
}
/**
 * Validates if the provided format string matches Edge TTS MP3 format
 * Edge TTS only supports: "audio-24khz-48kbitrate-mono-mp3"
 *
 * @param format - Audio format string to validate
 * @returns True if format is the supported Edge TTS MP3 format
 */
export declare function isValidMP3Format(format: string): boolean;
/**
 * Detects if binary data contains MP3 audio
 * Checks for MP3 frame header signature (11 bits set)
 *
 * @param data - Binary data to check
 * @returns True if data appears to be MP3 format
 */
export declare function detectMP3Format(data: ArrayBuffer): boolean;
/**
 * Validates that audio data conforms to Edge TTS MP3 specifications
 *
 * @param data - Audio data to validate
 * @returns True if data is valid Edge TTS MP3 format
 */
export declare function validateEdgeTTSMP3(data: ArrayBuffer): boolean;
/**
 * Parses Edge TTS binary message format: Int16 header length (big-endian) + JSON header + MP3 data
 *
 * @param data - Binary message data from Edge TTS WebSocket
 * @returns Parsed message structure or null if invalid
 */
export declare function parseEdgeTTSBinaryMessage(data: ArrayBuffer): EdgeTTSBinaryMessage | null;
/**
 * Validates that a binary message is an audio message from Edge TTS
 *
 * @param message - Parsed binary message
 * @returns True if message contains audio data
 */
export declare function isAudioMessage(message: EdgeTTSBinaryMessage): boolean;
/**
 * Extracts audio metadata from Edge TTS binary message
 * Based on Edge TTS specification: 24kHz, 48kbps, mono MP3
 *
 * @param message - Parsed Edge TTS binary message
 * @returns Audio metadata or null if not an audio message
 */
export declare function extractAudioMetadata(message: EdgeTTSBinaryMessage): EdgeTTSAudioMetadata | null;
/**
 * Estimates MP3 audio duration from binary data
 * Uses frame counting approach for MP3 duration calculation
 *
 * @param mp3Data - MP3 audio data
 * @returns Estimated duration in milliseconds
 */
export declare function estimateMP3Duration(mp3Data: ArrayBuffer): number;
/**
 * Applies Edge TTS word boundary offset compensation
 * Implements: max(0, offset - 8750000) for padding compensation
 *
 * @param rawOffset - Raw offset in Edge TTS ticks
 * @returns Compensated offset in ticks
 */
export declare function compensateWordBoundaryOffset(rawOffset: number): number;
/**
 * Converts Edge TTS ticks to milliseconds
 * Implements: ticks / 10000
 *
 * @param ticks - Time value in Edge TTS ticks
 * @returns Time value in milliseconds
 */
export declare function ticksToMilliseconds(ticks: number): number;
/**
 * Processes word boundary data from Edge TTS with offset compensation
 *
 * @param charIndex - Character index in original text
 * @param charLength - Character length of the word
 * @param rawOffset - Raw offset in Edge TTS ticks
 * @returns Processed word boundary data
 */
export declare function processWordBoundary(charIndex: number, charLength: number, rawOffset: number): EdgeTTSWordBoundary;
/**
 * Creates a new audio stream buffer for accumulating MP3 chunks
 *
 * @returns New empty audio stream buffer
 */
export declare function createAudioStreamBuffer(): AudioStreamBuffer;
/**
 * Adds an audio chunk to the streaming buffer
 *
 * @param buffer - Audio stream buffer
 * @param chunk - New audio chunk to add
 * @param metadata - Optional metadata (used for first chunk)
 */
export declare function addAudioChunk(buffer: AudioStreamBuffer, chunk: ArrayBuffer, metadata?: EdgeTTSAudioMetadata): void;
/**
 * Combines all audio chunks into a single ArrayBuffer
 *
 * @param buffer - Audio stream buffer
 * @returns Combined audio data
 */
export declare function combineAudioChunks(buffer: AudioStreamBuffer): ArrayBuffer;
/**
 * Clears the audio stream buffer and releases memory
 *
 * @param buffer - Audio stream buffer to clear
 */
export declare function clearAudioBuffer(buffer: AudioStreamBuffer): void;
/**
 * Gets the current size of buffered audio data
 *
 * @param buffer - Audio stream buffer
 * @returns Total buffered size in bytes
 */
export declare function getBufferedSize(buffer: AudioStreamBuffer): number;
/**
 * Checks if the buffer has any audio data
 *
 * @param buffer - Audio stream buffer
 * @returns True if buffer contains audio data
 */
export declare function hasAudioData(buffer: AudioStreamBuffer): boolean;
/**
 * Validates that streaming audio data maintains MP3 format consistency
 *
 * @param chunks - Array of audio chunks
 * @returns True if all chunks are valid MP3 format
 */
export declare function validateStreamingMP3Consistency(chunks: ArrayBuffer[]): boolean;
/**
 * Handles Edge TTS protocol specific audio processing edge cases
 *
 * @param data - Audio data to process
 * @returns Processed audio data or null if invalid
 */
export declare function handleEdgeTTSAudioEdgeCases(data: ArrayBuffer): ArrayBuffer | null;
/**
 * Network Service streaming audio processor interface
 * Used for coordinating with Network Service real-time processing
 */
export interface NetworkServiceAudioProcessor {
    /** Process incoming WebSocket binary message containing audio */
    processWebSocketMessage(data: ArrayBuffer): EdgeTTSBinaryMessage | null;
    /** Extract audio data from processed message */
    extractAudioFromMessage(message: EdgeTTSBinaryMessage): ArrayBuffer | null;
    /** Validate streaming audio consistency */
    validateStreamingConsistency(chunks: ArrayBuffer[]): boolean;
    /** Handle network service edge cases */
    handleNetworkEdgeCases(data: ArrayBuffer): ArrayBuffer | null;
}
/**
 * Creates a Network Service audio processor for real-time WebSocket integration
 * Coordinates with Network Service for streaming audio processing
 *
 * @returns Network Service audio processor instance
 */
export declare function createNetworkServiceAudioProcessor(): NetworkServiceAudioProcessor;
/**
 * Processes streaming audio chunks from Network Service with performance optimization
 * Designed for real-time processing with minimal latency
 *
 * @param chunks - Array of audio chunks from Network Service
 * @param processor - Network Service audio processor
 * @returns Processed and validated audio chunks
 */
export declare function processNetworkServiceAudioChunks(chunks: ArrayBuffer[], processor: NetworkServiceAudioProcessor): ArrayBuffer[];
/**
 * Storage Service buffer format interface for coordinating with Storage Service
 */
export interface StorageServiceBufferFormat {
    /** Connection ID for buffer tracking */
    connectionId: string;
    /** Audio chunks in Storage Service format (Uint8Array[]) */
    audioChunks: Uint8Array[];
    /** Total buffer size coordination */
    totalSize: number;
    /** Last activity timestamp for Storage Service cleanup */
    lastActivity: Date;
}
/**
 * Converts AudioStreamBuffer to Storage Service buffer format
 * Coordinates with Storage Service buffer management
 *
 * @param buffer - Audio stream buffer
 * @param connectionId - Connection ID for Storage Service tracking
 * @returns Storage Service compatible buffer format
 */
export declare function convertToStorageServiceFormat(buffer: AudioStreamBuffer, connectionId: string): StorageServiceBufferFormat;
/**
 * Converts Storage Service buffer format back to AudioStreamBuffer
 * Enables coordination between audio processing and Storage Service
 *
 * @param storageBuffer - Storage Service buffer format
 * @returns AudioStreamBuffer for audio processing
 */
export declare function convertFromStorageServiceFormat(storageBuffer: StorageServiceBufferFormat): AudioStreamBuffer;
/**
 * Merges audio chunks with Storage Service coordination
 * Optimized for Storage Service buffer management patterns
 *
 * @param storageBuffer - Storage Service buffer format
 * @returns Combined audio data ready for playback
 */
export declare function mergeStorageServiceAudioChunks(storageBuffer: StorageServiceBufferFormat): ArrayBuffer;
/**
 * expo-av compatible audio data interface
 * Based on expo-av documentation for Sound.createAsync requirements
 */
export interface ExpoAVAudioData {
    /** Data URI for expo-av Sound.createAsync */
    uri: string;
    /** Audio metadata for expo-av */
    metadata: {
        format: string;
        duration?: number;
        sampleRate: number;
        channels: number;
    };
}
/**
 * Generates expo-av compatible data URI from MP3 audio data
 * Creates base64 data URI for expo-av Sound.createAsync usage
 *
 * @param mp3Data - MP3 audio data from Edge TTS
 * @returns Data URI string for expo-av compatibility
 */
export declare function generateExpoAVDataURI(mp3Data: ArrayBuffer): string;
/**
 * Creates expo-av compatible audio data from Edge TTS MP3
 * Prepares audio data for use with expo-av Sound.createAsync
 *
 * @param mp3Data - MP3 audio data from Edge TTS
 * @param metadata - Optional audio metadata
 * @returns expo-av compatible audio data
 */
export declare function createExpoAVAudioData(mp3Data: ArrayBuffer, metadata?: EdgeTTSAudioMetadata): ExpoAVAudioData;
/**
 * Validates expo-av audio data compatibility
 * Ensures audio data meets expo-av Sound.createAsync requirements
 *
 * @param audioData - expo-av audio data to validate
 * @returns True if compatible with expo-av
 */
export declare function validateExpoAVCompatibility(audioData: ExpoAVAudioData): boolean;
/**
 * Real-time streaming validator for audio processing
 */
export interface RealTimeStreamingValidator {
    /** Validate incoming audio chunk in real-time */
    validateChunk(chunk: ArrayBuffer, chunkIndex: number): boolean;
    /** Validate chunk sequence for streaming continuity */
    validateSequence(chunks: ArrayBuffer[]): boolean;
    /** Check if streaming is healthy */
    isStreamingHealthy(buffer: AudioStreamBuffer): boolean;
    /** Get streaming health metrics */
    getHealthMetrics(buffer: AudioStreamBuffer): StreamingHealthMetrics;
}
/**
 * Streaming health metrics for real-time monitoring
 */
export interface StreamingHealthMetrics {
    /** Number of chunks processed */
    chunksProcessed: number;
    /** Total data processed in bytes */
    totalDataProcessed: number;
    /** Average chunk size */
    averageChunkSize: number;
    /** Streaming consistency score (0-1) */
    consistencyScore: number;
    /** Is streaming within performance targets */
    isOptimal: boolean;
}
/**
 * Creates a real-time streaming validator for audio processing
 * Optimized for real-time validation with minimal overhead
 *
 * @returns Real-time streaming validator instance
 */
export declare function createRealTimeStreamingValidator(): RealTimeStreamingValidator;
/**
 * Performance-optimized audio chunk processor for real-time streaming
 */
export interface PerformanceOptimizedProcessor {
    /** Process chunk with performance optimization */
    processChunkOptimized(chunk: ArrayBuffer): ArrayBuffer | null;
    /** Batch process multiple chunks efficiently */
    batchProcessChunks(chunks: ArrayBuffer[]): ArrayBuffer[];
    /** Pre-allocate buffers for performance */
    preAllocateBuffers(expectedChunkCount: number, expectedTotalSize: number): void;
    /** Clean up allocated resources */
    cleanup(): void;
    /** Get pre-allocated buffer */
    getPreallocatedBuffer(): ArrayBuffer | null;
}
/**
 * Creates a performance-optimized processor for real-time audio processing
 * Minimizes allocations and copying for maximum performance
 *
 * @returns Performance-optimized processor instance
 */
export declare function createPerformanceOptimizedProcessor(): PerformanceOptimizedProcessor;
/**
 * Optimized audio chunk combiner with pre-allocated buffers
 * Reduces memory allocations for real-time performance
 *
 * @param chunks - Audio chunks to combine
 * @param preallocatedBuffer - Optional pre-allocated buffer for performance
 * @returns Combined audio data
 */
export declare function combineAudioChunksOptimized(chunks: ArrayBuffer[], preallocatedBuffer?: ArrayBuffer): ArrayBuffer;
/**
 * Enhanced edge case handler for Network Service integration
 * Handles edge cases discovered during Network Service implementation
 */
export interface NetworkServiceEdgeCaseHandler {
    /** Handle WebSocket connection edge cases */
    handleWebSocketEdgeCases(data: ArrayBuffer): ArrayBuffer | null;
    /** Handle audio chunk corruption scenarios */
    handleChunkCorruption(chunk: ArrayBuffer): ArrayBuffer | null;
    /** Handle incomplete audio messages */
    handleIncompleteMessages(data: ArrayBuffer): ArrayBuffer | null;
    /** Handle audio format inconsistencies */
    handleFormatInconsistencies(chunks: ArrayBuffer[]): ArrayBuffer[];
}
/**
 * Creates enhanced edge case handler for Network Service integration
 * Includes all edge cases discovered during Network Service implementation
 *
 * @returns Network Service edge case handler
 */
export declare function createNetworkServiceEdgeCaseHandler(): NetworkServiceEdgeCaseHandler;
/**
 * Enhanced audio processing pipeline for Network Service integration
 * Combines all enhancements for comprehensive audio processing
 *
 * @param chunks - Raw audio chunks from Network Service
 * @param connectionId - Connection ID for Storage Service coordination
 * @returns Processed audio data ready for expo-av playback
 */
export declare function processNetworkServiceAudioPipeline(chunks: ArrayBuffer[], connectionId: string): ExpoAVAudioData | null;
//# sourceMappingURL=audioUtils.d.ts.map