@loonylabs/tts-middleware 0.1.1

package/dist/middleware/services/tts/providers/azure-provider.js

@@ -0,0 +1,375 @@
+"use strict";
+/**
+ * Azure Speech Services TTS Provider
+ *
+ * @description Implementation of TTS provider for Microsoft Azure Speech Services.
+ * This is the MVP provider for EU-compliant TTS synthesis.
+ *
+ * @see https://learn.microsoft.com/en-us/azure/ai-services/speech-service/
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AzureProvider = void 0;
+const sdk = __importStar(require("microsoft-cognitiveservices-speech-sdk"));
+const types_1 = require("../types");
+const base_tts_provider_1 = require("./base-tts-provider");
+/**
+ * Azure Speech Services provider implementation
+ *
+ * @description Provides TTS synthesis using Microsoft Azure Speech Services.
+ * Supports emotion, style, and multiple audio formats.
+ *
+ * @example
+ * ```typescript
+ * const provider = new AzureProvider();
+ * const response = await provider.synthesize(
+ *   "Hello World",
+ *   "en-US-JennyNeural",
+ *   {
+ *     text: "Hello World",
+ *     voice: { id: "en-US-JennyNeural" },
+ *     audio: { speed: 1.0, format: "mp3" },
+ *     providerOptions: { emotion: "cheerful" }
+ *   }
+ * );
+ * ```
+ */
+class AzureProvider extends base_tts_provider_1.BaseTTSProvider {
+    /**
+     * Creates a new Azure TTS provider
+     *
+     * @param config - Optional Azure configuration (uses env vars if not provided)
+     * @throws {InvalidConfigError} If required configuration is missing
+     */
+    constructor(config) {
+        super(types_1.TTSProvider.AZURE);
+        this.speechConfig = null;
+        // Load configuration from environment or provided config
+        this.config = {
+            subscriptionKey: config?.subscriptionKey || process.env.AZURE_SPEECH_KEY || '',
+            region: config?.region || process.env.AZURE_SPEECH_REGION || '',
+            endpoint: config?.endpoint || process.env.AZURE_SPEECH_ENDPOINT,
+        };
+        // Validate configuration
+        this.validateAzureConfig();
+        // Initialize speech config
+        this.initializeSpeechConfig();
+    }
+    /**
+     * Validate Azure-specific configuration
+     *
+     * @private
+     * @throws {InvalidConfigError} If configuration is invalid
+     */
+    validateAzureConfig() {
+        if (!this.config.subscriptionKey) {
+            throw new base_tts_provider_1.InvalidConfigError(this.providerName, 'Azure Speech subscription key is required (AZURE_SPEECH_KEY)');
+        }
+        if (!this.config.region) {
+            throw new base_tts_provider_1.InvalidConfigError(this.providerName, 'Azure Speech region is required (AZURE_SPEECH_REGION)');
+        }
+    }
+    /**
+     * Initialize Azure Speech SDK configuration
+     *
+     * @private
+     */
+    initializeSpeechConfig() {
+        try {
+            if (this.config.endpoint) {
+                this.speechConfig = sdk.SpeechConfig.fromEndpoint(new URL(this.config.endpoint), this.config.subscriptionKey);
+            }
+            else {
+                this.speechConfig = sdk.SpeechConfig.fromSubscription(this.config.subscriptionKey, this.config.region);
+            }
+            this.log('info', 'Azure Speech SDK initialized', {
+                region: this.config.region,
+                hasEndpoint: !!this.config.endpoint,
+            });
+        }
+        catch (error) {
+            throw new base_tts_provider_1.InvalidConfigError(this.providerName, `Failed to initialize Azure Speech SDK: ${error.message}`, error);
+        }
+    }
+    /**
+     * Synthesize text to speech using Azure Speech Services
+     *
+     * @param text - The input text to synthesize
+     * @param voiceId - The voice identifier (e.g., "en-US-JennyNeural")
+     * @param request - The full synthesis request with options
+     * @returns Promise resolving to the synthesis response
+     * @throws {InvalidConfigError} If configuration is invalid
+     * @throws {InvalidVoiceError} If voice is not found
+     * @throws {SynthesisFailedError} If synthesis fails
+     */
+    async synthesize(text, voiceId, request) {
+        // Validate configuration
+        this.validateConfig(request);
+        if (!this.speechConfig) {
+            throw new base_tts_provider_1.InvalidConfigError(this.providerName, 'Speech configuration not initialized');
+        }
+        const startTime = Date.now();
+        try {
+            // Extract options
+            const audioFormat = request.audio?.format || 'mp3';
+            const speed = request.audio?.speed || 1.0;
+            const sampleRate = request.audio?.sampleRate || 24000;
+            // Set audio output format
+            this.setAudioFormat(audioFormat, sampleRate);
+            // Generate SSML
+            const ssml = this.generateSSML(text, voiceId, request);
+            this.log('debug', 'Synthesizing with Azure', {
+                voiceId,
+                audioFormat,
+                speed,
+                sampleRate,
+                ssmlLength: ssml.length,
+            });
+            // Create synthesizer
+            const synthesizer = new sdk.SpeechSynthesizer(this.speechConfig);
+            // Synthesize speech
+            const audioBuffer = await this.synthesizeSSML(synthesizer, ssml);
+            // Calculate duration (estimated)
+            const duration = Date.now() - startTime;
+            // Count billable characters (original text, not SSML)
+            const characters = this.countCharacters(text);
+            this.log('info', 'Synthesis successful', {
+                voiceId,
+                characters,
+                duration,
+                audioSize: audioBuffer.length,
+            });
+            // Return response
+            return {
+                audio: audioBuffer,
+                metadata: {
+                    provider: this.providerName,
+                    voice: voiceId,
+                    duration,
+                    audioFormat,
+                    sampleRate,
+                },
+                billing: {
+                    characters,
+                },
+            };
+        }
+        catch (error) {
+            this.log('error', 'Synthesis failed', {
+                voiceId,
+                error: error.message,
+            });
+            throw this.handleError(error, 'during synthesis');
+        }
+    }
+    /**
+     * Set audio output format for Azure Speech SDK
+     *
+     * @private
+     * @param format - The audio format (mp3, wav, opus)
+     * @param sampleRate - The sample rate in Hz
+     */
+    setAudioFormat(format, sampleRate) {
+        if (!this.speechConfig) {
+            throw new base_tts_provider_1.InvalidConfigError(this.providerName, 'Speech configuration not initialized');
+        }
+        // Map format and sample rate to Azure format strings
+        const azureFormat = this.getAzureAudioFormat(format, sampleRate);
+        this.speechConfig.speechSynthesisOutputFormat = azureFormat;
+        this.log('debug', 'Audio format set', {
+            format,
+            sampleRate,
+            azureFormat: sdk.SpeechSynthesisOutputFormat[azureFormat],
+        });
+    }
+    /**
+     * Map audio format and sample rate to Azure format enum
+     *
+     * @private
+     * @param format - The audio format
+     * @param sampleRate - The sample rate in Hz
+     * @returns Azure audio format enum value
+     */
+    getAzureAudioFormat(format, sampleRate) {
+        const formatKey = `${format}_${sampleRate}`;
+        const formatMap = {
+            // MP3 formats
+            mp3_8000: sdk.SpeechSynthesisOutputFormat.Audio16Khz32KBitRateMonoMp3,
+            mp3_16000: sdk.SpeechSynthesisOutputFormat.Audio16Khz128KBitRateMonoMp3,
+            mp3_24000: sdk.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3,
+            mp3_48000: sdk.SpeechSynthesisOutputFormat.Audio48Khz192KBitRateMonoMp3,
+            // WAV formats
+            wav_8000: sdk.SpeechSynthesisOutputFormat.Riff8Khz16BitMonoPcm,
+            wav_16000: sdk.SpeechSynthesisOutputFormat.Riff16Khz16BitMonoPcm,
+            wav_24000: sdk.SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm,
+            wav_48000: sdk.SpeechSynthesisOutputFormat.Riff48Khz16BitMonoPcm,
+            // Opus formats
+            opus_8000: sdk.SpeechSynthesisOutputFormat.Ogg16Khz16BitMonoOpus,
+            opus_16000: sdk.SpeechSynthesisOutputFormat.Ogg16Khz16BitMonoOpus,
+            opus_24000: sdk.SpeechSynthesisOutputFormat.Ogg24Khz16BitMonoOpus,
+            opus_48000: sdk.SpeechSynthesisOutputFormat.Ogg48Khz16BitMonoOpus,
+        };
+        // Default formats if exact match not found
+        const defaultFormats = {
+            mp3: sdk.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3,
+            wav: sdk.SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm,
+            opus: sdk.SpeechSynthesisOutputFormat.Ogg24Khz16BitMonoOpus,
+            aac: sdk.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3, // Fallback to MP3
+            flac: sdk.SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm, // Fallback to WAV
+        };
+        return (formatMap[formatKey] ||
+            defaultFormats[format] ||
+            sdk.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3);
+    }
+    /**
+     * Generate SSML from plain text and options
+     *
+     * @private
+     * @param text - The input text
+     * @param voiceId - The voice identifier
+     * @param request - The synthesis request with options
+     * @returns SSML string
+     */
+    generateSSML(text, voiceId, request) {
+        // Extract language from voice ID (e.g., "en-US-JennyNeural" -> "en-US")
+        const language = voiceId.split('-').slice(0, 2).join('-');
+        // Extract provider options
+        const emotion = request.providerOptions?.emotion || null;
+        const style = request.providerOptions?.style || null;
+        const speed = request.audio?.speed || 1.0;
+        // Escape XML special characters
+        const escapedText = this.escapeXML(text);
+        // Build SSML
+        let ssml = `<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xmlns:mstts="https://www.w3.org/2001/mstts" xml:lang="${language}">`;
+        ssml += `<voice name="${voiceId}">`;
+        // Add style/emotion if provided (Azure-specific)
+        if (style || emotion) {
+            const expressAs = style || emotion;
+            ssml += `<mstts:express-as style="${expressAs}">`;
+        }
+        // Add prosody for speed control
+        const rateValue = this.speedToProsodyRate(speed);
+        ssml += `<prosody rate="${rateValue}">`;
+        // Add text
+        ssml += escapedText;
+        // Close prosody
+        ssml += `</prosody>`;
+        // Close express-as if used
+        if (style || emotion) {
+            ssml += `</mstts:express-as>`;
+        }
+        // Close voice and speak
+        ssml += `</voice>`;
+        ssml += `</speak>`;
+        return ssml;
+    }
+    /**
+     * Convert speed multiplier to SSML prosody rate value
+     *
+     * @private
+     * @param speed - Speed multiplier (0.5 - 2.0)
+     * @returns SSML rate value
+     */
+    speedToProsodyRate(speed) {
+        // Azure accepts percentage values: "50%" = half speed, "200%" = double speed
+        // Or relative values: "x-slow", "slow", "medium", "fast", "x-fast"
+        if (speed === 1.0) {
+            return 'medium';
+        }
+        // Convert to percentage (1.0 = 100%, 0.5 = 50%, 2.0 = 200%)
+        const percentage = Math.round(speed * 100);
+        return `${percentage}%`;
+    }
+    /**
+     * Escape XML special characters
+     *
+     * @private
+     * @param text - The text to escape
+     * @returns Escaped text
+     */
+    escapeXML(text) {
+        return text
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+    /**
+     * Synthesize SSML using Azure Speech SDK
+     *
+     * @private
+     * @param synthesizer - The speech synthesizer
+     * @param ssml - The SSML to synthesize
+     * @returns Promise resolving to audio buffer
+     * @throws {InvalidVoiceError} If voice is not found
+     * @throws {SynthesisFailedError} If synthesis fails
+     */
+    async synthesizeSSML(synthesizer, ssml) {
+        return new Promise((resolve, reject) => {
+            synthesizer.speakSsmlAsync(ssml, (result) => {
+                if (result.reason === sdk.ResultReason.SynthesizingAudioCompleted) {
+                    // Convert ArrayBuffer to Buffer
+                    const audioBuffer = Buffer.from(result.audioData);
+                    synthesizer.close();
+                    resolve(audioBuffer);
+                }
+                else if (result.reason === sdk.ResultReason.Canceled) {
+                    const cancellation = sdk.CancellationDetails.fromResult(result);
+                    synthesizer.close();
+                    // Check error type
+                    if (cancellation.ErrorCode === sdk.CancellationErrorCode.AuthenticationFailure) {
+                        reject(new base_tts_provider_1.InvalidConfigError(this.providerName, `Authentication failed: ${cancellation.errorDetails}`));
+                    }
+                    else if (cancellation.errorDetails?.includes('voice')) {
+                        reject(new base_tts_provider_1.InvalidVoiceError(this.providerName, 'unknown', `Voice not found: ${cancellation.errorDetails}`));
+                    }
+                    else {
+                        reject(new base_tts_provider_1.SynthesisFailedError(this.providerName, `Synthesis canceled: ${cancellation.errorDetails || 'Unknown error'}`));
+                    }
+                }
+                else {
+                    synthesizer.close();
+                    reject(new base_tts_provider_1.SynthesisFailedError(this.providerName, `Unexpected result reason: ${sdk.ResultReason[result.reason]}`));
+                }
+            }, (error) => {
+                synthesizer.close();
+                reject(this.handleError(new Error(error), 'during Azure SDK call'));
+            });
+        });
+    }
+}
+exports.AzureProvider = AzureProvider;
+//# sourceMappingURL=azure-provider.js.map

package/dist/middleware/services/tts/providers/azure-provider.js.map

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

package/dist/middleware/services/tts/providers/base-tts-provider.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Base TTS Provider Abstract Class
+ *
+ * All TTS providers must extend this class and implement the abstract methods.
+ * This ensures consistency across all providers.
+ *
+ * @abstract
+ */
+import type { TTSProvider, TTSSynthesizeRequest, TTSResponse, TTSErrorCode } from '../types';
+/**
+ * Base error class for all TTS errors
+ */
+export declare class TTSError extends Error {
+    readonly provider: string;
+    readonly code: TTSErrorCode;
+    readonly cause?: Error | undefined;
+    /**
+     * Creates a new TTS error
+     *
+     * @param provider - The provider that threw the error
+     * @param code - Error code for categorization
+     * @param message - Human-readable error message
+     * @param cause - Optional underlying error that caused this error
+     */
+    constructor(provider: string, code: TTSErrorCode, message: string, cause?: Error | undefined);
+    /**
+     * Returns a formatted error message with context
+     */
+    toString(): string;
+}
+/**
+ * Error thrown when TTS configuration is invalid or missing
+ */
+export declare class InvalidConfigError extends TTSError {
+    constructor(provider: string, message: string, cause?: Error);
+}
+/**
+ * Error thrown when voice ID is invalid or not found
+ */
+export declare class InvalidVoiceError extends TTSError {
+    constructor(provider: string, voiceId: string, message?: string, cause?: Error);
+}
+/**
+ * Error thrown when provider quota/rate limit is exceeded
+ */
+export declare class QuotaExceededError extends TTSError {
+    constructor(provider: string, message?: string, cause?: Error);
+}
+/**
+ * Error thrown when provider service is unavailable
+ */
+export declare class ProviderUnavailableError extends TTSError {
+    constructor(provider: string, message?: string, cause?: Error);
+}
+/**
+ * Error thrown when synthesis fails for unknown reasons
+ */
+export declare class SynthesisFailedError extends TTSError {
+    constructor(provider: string, message: string, cause?: Error);
+}
+/**
+ * Error thrown when network operation fails
+ */
+export declare class NetworkError extends TTSError {
+    constructor(provider: string, message: string, cause?: Error);
+}
+/**
+ * Abstract base class for all TTS providers
+ *
+ * @abstract
+ *
+ * @description All provider implementations must:
+ * - Extend this class
+ * - Implement the abstract synthesize() method
+ * - Call super() in constructor with the provider name
+ * - Use the provided error classes for consistent error handling
+ *
+ * @example
+ * ```typescript
+ * class AzureProvider extends BaseTTSProvider {
+ *   constructor() {
+ *     super(TTSProvider.AZURE);
+ *   }
+ *
+ *   async synthesize(text: string, voiceId: string, request: TTSSynthesizeRequest): Promise<TTSResponse> {
+ *     this.validateConfig(request);
+ *     // ... implementation
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseTTSProvider {
+    /**
+     * The provider name (e.g., 'azure', 'openai')
+     */
+    protected readonly providerName: TTSProvider;
+    /**
+     * Creates a new TTS provider
+     *
+     * @param providerName - The provider identifier
+     */
+    constructor(providerName: TTSProvider);
+    /**
+     * Synthesize text to speech
+     *
+     * @abstract
+     * @param text - The input text to synthesize
+     * @param voiceId - The voice identifier (provider-specific)
+     * @param request - The full synthesis request with options
+     * @returns Promise resolving to the synthesis response with audio buffer
+     * @throws {InvalidConfigError} If provider configuration is invalid
+     * @throws {InvalidVoiceError} If voice ID is not found
+     * @throws {QuotaExceededError} If provider quota is exceeded
+     * @throws {ProviderUnavailableError} If provider service is unavailable
+     * @throws {SynthesisFailedError} If synthesis fails for other reasons
+     */
+    abstract synthesize(text: string, voiceId: string, request: TTSSynthesizeRequest): Promise<TTSResponse>;
+    /**
+     * Get the provider name
+     *
+     * @returns The provider identifier
+     */
+    getProviderName(): TTSProvider;
+    /**
+     * Validate provider configuration
+     *
+     * @protected
+     * @param request - The synthesis request to validate
+     * @throws {InvalidConfigError} If configuration is invalid
+     *
+     * @description Subclasses should override this to validate provider-specific
+     * configuration (e.g., API keys, region settings)
+     */
+    protected validateConfig(request: TTSSynthesizeRequest): void;
+    /**
+     * Count characters in text for billing purposes
+     *
+     * @protected
+     * @param text - The input text to count
+     * @returns The number of characters (including spaces and punctuation)
+     *
+     * @description This is the base implementation that counts all characters.
+     * Providers that use SSML or have special character counting rules
+     * should override this method.
+     *
+     * @example
+     * ```typescript
+     * const count = this.countCharacters("Hello World!"); // returns 12
+     * ```
+     */
+    protected countCharacters(text: string): number;
+    /**
+     * Validate that a voice exists
+     *
+     * @protected
+     * @param _voiceId - The voice identifier to validate (unused in base implementation)
+     * @returns Promise resolving to true if voice exists
+     * @throws {InvalidVoiceError} If voice does not exist
+     *
+     * @description Base implementation always returns true. Providers should
+     * override this to validate voice IDs against their voice catalogs.
+     */
+    protected validateVoiceExists(_voiceId: string): Promise<boolean>;
+    /**
+     * Create a standardized error from a provider-specific error
+     *
+     * @protected
+     * @param error - The original error
+     * @param context - Additional context for debugging
+     * @returns A standardized TTS error
+     *
+     * @description Wraps provider-specific errors in our error classes
+     * for consistent error handling across providers.
+     */
+    protected handleError(error: Error, context?: string): TTSError;
+    /**
+     * Log a message using the pluggable logger
+     *
+     * @protected
+     * @param level - Log level
+     * @param message - Log message
+     * @param meta - Optional metadata
+     *
+     * @description Uses the global TTS logger which can be customized via setLogger().
+     * By default uses console logging, but can be replaced with any logger (Winston, Pino, etc.)
+     *
+     * @example
+     * ```typescript
+     * // In application code:
+     * import { setLogger, silentLogger } from '@loonylabs/tts-middleware';
+     *
+     * // Disable all logging
+     * setLogger(silentLogger);
+     *
+     * // Use custom logger
+     * setLogger({
+     *   info: (msg, meta) => myLogger.info(msg, meta),
+     *   // ...
+     * });
+     * ```
+     */
+    protected log(level: 'info' | 'warn' | 'error' | 'debug', message: string, meta?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=base-tts-provider.d.ts.map

package/dist/middleware/services/tts/providers/base-tts-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-tts-provider.d.ts","sourceRoot":"","sources":["../../../../../src/middleware/services/tts/providers/base-tts-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,YAAY,EACb,MAAM,UAAU,CAAC;AAGlB;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAUf,QAAQ,EAAE,MAAM;aAChB,IAAI,EAAE,YAAY;aAElB,KAAK,CAAC,EAAE,KAAK;IAZ/B;;;;;;;OAOG;gBAEe,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,YAAY,EAClC,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,KAAK,YAAA;IAW/B;;OAEG;IACH,QAAQ,IAAI,MAAM;CAKnB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI7D;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBAE3C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,KAAK;CAUhB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAS9D;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,QAAQ;gBACxC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAS9D;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI7D;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,QAAQ;gBAC5B,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8BAAsB,eAAe;IACnC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;IAE7C;;;;OAIG;gBACS,YAAY,EAAE,WAAW;IAIrC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC;IAEvB;;;;OAIG;IACI,eAAe,IAAI,WAAW;IAIrC;;;;;;;;;OASG;IACH,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAgB7D;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI/C;;;;;;;;;;OAUG;cACa,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMvE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ;IAyD/D;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,GAAG,CACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,EAC1C,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI;CAGR"}