@lee-zg/melange 1.0.0 → 1.2.2

package/dist/plugins/index.d.ts

@@ -300,51 +300,150 @@ interface CustomProviderConfig {
 type ProviderConfig = AzureSpeechConfig | GoogleSpeechConfig | AWSSpeechConfig | CustomProviderConfig;
 
 /**
- * @fileoverview 语音合成 (TTS) 实现
+ * @fileoverview 语音合成 (TTS) 实现 - 商业级版本 v2.0
  * @module melange/plugins/speech/synthesis
- * @description 提供语音合成功能，支持浏览器原生 API 和第三方服务降级
+ * @description 生产级 Web 语音合成插件
+ *
+ * 架构：
+ * [UI层] -> [SpeechSynthesizerImpl] -> [NativeStrategy / CloudStrategy]
+ *                                          |
+ *                                          +-> [音频核心]: AudioContext, 流式播放
+ *                                          +-> [适配器]: AzureAdapter, GoogleAdapter, TencentAdapter...
+ *
+ * 功能特性：
+ * 1. 多模式: 支持原生 Web Speech API & 云端 TTS 服务
+ * 2. 状态机: IDLE -> LOADING -> SPEAKING -> PAUSED
+ * 3. 插件化: 内置 Azure/Google/AWS/讯飞/腾讯/百度/阿里 适配器
+ * 4. 核心: AudioContext 流式播放 + 音频队列管理
+ * 5. 兼容性: 多浏览器支持 + 自动降级处理
  */
 
 /**
- * 语音合成器
- * 管理多个提供商，支持自动降级
+ * 合成器状态枚举
+ */
+declare enum SynthesisStatus {
+    /** 空闲状态 */
+    IDLE = "IDLE",
+    /** 加载中（获取语音/准备中） */
+    LOADING = "LOADING",
+    /** 正在播放 */
+    SPEAKING = "SPEAKING",
+    /** 已暂停 */
+    PAUSED = "PAUSED"
+}
+/**
+ * 合成引擎模式
+ */
+type SynthesisEngineMode = 'native' | 'cloud' | 'auto';
+/**
+ * 云端 TTS 音频格式
+ */
+type CloudAudioFormat = 'mp3' | 'wav' | 'ogg' | 'pcm';
+/**
+ * 云端合成结果接口
+ */
+interface ISynthesisResult {
+    /** 音频数据 */
+    audioData: ArrayBuffer;
+    /** 音频格式 */
+    format: CloudAudioFormat;
+    /** 音频时长 (ms) */
+    duration?: number;
+    /** 原始响应数据 */
+    original?: unknown;
+}
+/**
+ * 云端语音信息
+ */
+interface ICloudVoice {
+    /** 语音 ID */
+    id: string;
+    /** 语音名称 */
+    name: string;
+    /** 语言代码 */
+    lang: string;
+    /** 性别 */
+    gender?: 'male' | 'female' | 'neutral';
+    /** 提供商名称 */
+    provider: string;
+}
+/**
+ * 高级合成配置
+ */
+interface IAdvancedSynthesisConfig extends SynthesisConfig {
+    /** 合成引擎模式 */
+    mode?: SynthesisEngineMode;
+    /** 云端适配器 */
+    cloudAdapter?: ICloudSynthesisAdapter;
+    /** 音频格式偏好 */
+    audioFormat?: CloudAudioFormat;
+    /** 是否启用 SSML */
+    enableSSML?: boolean;
+    /** 是否预加载音频 */
+    preload?: boolean;
+    /** 音频缓存大小 */
+    cacheSize?: number;
+}
+/**
+ * 云端合成适配器接口
+ * 提供统一的第三方语音合成服务集成接口
+ */
+interface ICloudSynthesisAdapter {
+    /** 适配器名称 */
+    readonly name: string;
+    /**
+     * 合成语音
+     * @param text 要合成的文本
+     * @param config 合成配置
+     * @returns 合成结果（音频数据）
+     */
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    /**
+     * 获取可用语音列表
+     * @returns 语音列表
+     */
+    getVoices?(): Promise<ICloudVoice[]>;
+    /**
+     * 检查适配器是否可用
+     * @returns 是否可用
+     */
+    isAvailable?(): boolean;
+}
+/**
+ * 语音合成器实现
+ * 统一封装原生合成和云端合成
  */
 declare class SpeechSynthesizerImpl implements SpeechSynthesizer {
+    private strategy;
+    private config;
     private _currentProvider;
     private _status;
-    private provider;
-    private config;
     private eventHandlers;
-    private providers;
-    /**
-     * 当前使用的提供商类型
-     */
+    private customProviders;
     get currentProvider(): SpeechProviderType;
+    get status(): SpeechServiceStatus;
     /**
-     * 服务状态
+     * 获取当前合成状态
      */
-    get status(): SpeechServiceStatus;
+    get synthesisStatus(): SynthesisStatus;
     /**
      * 初始化语音合成器
-     * @param config - 合成配置
      */
     initialize(config?: SynthesisConfig): Promise<void>;
     /**
-     * 尝试使用指定提供商
+     * 初始化合成策略
      */
-    private tryProvider;
+    private initializeStrategy;
     /**
-     * 转发提供商事件到合成器
+     * 转发策略事件
      */
-    private forwardProviderEvents;
+    private forwardStrategyEvents;
     /**
      * 获取可用语音列表
      */
     getVoices(): Promise<VoiceInfo[]>;
     /**
      * 朗读文本
-     * @param text - 要朗读的文本
-     * @param config - 可选的合成配置
      */
     speak(text: string, config?: SynthesisConfig): Promise<void>;
     /**
@@ -385,10 +484,12 @@ declare class SpeechSynthesizerImpl implements SpeechSynthesizer {
     dispose(): void;
     /**
      * 注册自定义提供商
-     * @param type - 提供商类型
-     * @param provider - 提供商实例
      */
     registerProvider(type: SpeechProviderType, provider: SynthesisProvider): void;
+    /**
+     * 使用云端适配器
+     */
+    useCloudAdapter(adapter: ICloudSynthesisAdapter): void;
 }
 /**
  * 创建语音合成器实例
@@ -397,26 +498,23 @@ declare class SpeechSynthesizerImpl implements SpeechSynthesizer {
  *
  * @example
  * ```typescript
- * // 创建并初始化语音合成器
+ * // 使用原生合成
  * const synthesizer = await createSpeechSynthesizer({
  *   lang: 'zh-CN',
  *   rate: 1.0,
- *   pitch: 1.0,
  * });
  *
- * // 朗读文本
- * await synthesizer.speak('你好，世界！');
- *
- * // 监听事件
- * synthesizer.on('end', () => {
- *   console.log('朗读完成');
+ * // 使用云端合成 (Azure)
+ * const azureAdapter = new AzureSynthesisAdapter('key', 'eastasia');
+ * const cloudSynthesizer = await createSpeechSynthesizer({
+ *   mode: 'cloud',
+ *   cloudAdapter: azureAdapter,
  * });
  *
- * // 销毁
- * synthesizer.dispose();
+ * await synthesizer.speak('你好，世界！');
  * ```
  */
-declare function createSpeechSynthesizer(config?: SynthesisConfig): Promise<SpeechSynthesizer>;
+declare function createSpeechSynthesizer(config?: SynthesisConfig | IAdvancedSynthesisConfig): Promise<SpeechSynthesizer>;
 /**
  * 检查当前环境是否支持语音合成
  * @returns 是否支持语音合成
@@ -436,134 +534,192 @@ declare function isSpeechSynthesisSupported(): boolean;
  * await speak('Hello World', { lang: 'en-US', rate: 0.8 });
  * ```
  */
-declare function speak(text: string, config?: SynthesisConfig): Promise<void>;
+declare function speak(text: string, config?: SynthesisConfig | IAdvancedSynthesisConfig): Promise<void>;
 
 /**
- * @fileoverview 语音识别 (STT) 实现
+ * @fileoverview 语音识别 (STT) 实现 - 商业级版本 v2.0
  * @module melange/plugins/speech/recognition
- * @description 提供语音识别功能，支持浏览器原生 API 和第三方服务降级
+ * @description 生产级 Web 语音识别插件
+ *
+ * 架构：
+ * [UI层] -> [SpeechRecognizerImpl] -> [NativeStrategy / CloudStrategy]
+ *                                          |
+ *                                          +-> [音频核心]: Worklet, VAD, Resample
+ *                                          +-> [适配器]: BaiduAdapter, XunfeiAdapter, TencentAdapter...
+ *
+ * 功能特性：
+ * 1. 多模式: 支持 WebSocket 流式识别 & HTTP 短语音识别
+ * 2. 状态机: IDLE -> CONNECTING -> RECORDING -> PROCESSING
+ * 3. 插件化: 内置 讯飞/腾讯/百度/阿里/Google/Azure 适配器
+ * 4. 核心: AudioWorklet + VAD + 自动重采样 + WAV编码
+ * 5. 兼容性: 自动降级处理 (ScriptProcessor) + 断网缓冲队列
  */
 
+declare global {
+    interface Window {
+        SpeechRecognition?: unknown;
+        webkitSpeechRecognition?: unknown;
+        webkitAudioContext?: typeof AudioContext;
+    }
+}
 /**
- * SpeechRecognition 结果列表接口
- */
-interface BrowserSpeechRecognitionResultList {
-    readonly length: number;
-    item(index: number): BrowserSpeechRecognitionResult | null;
-    [index: number]: BrowserSpeechRecognitionResult;
+ * 识别器状态枚举
+ */
+declare enum RecognitionStatus {
+    /** 空闲状态 */
+    IDLE = "IDLE",
+    /** 连接中 */
+    CONNECTING = "CONNECTING",
+    /** 录音中 */
+    RECORDING = "RECORDING",
+    /** 处理中/上传中 */
+    PROCESSING = "PROCESSING"
 }
 /**
- * SpeechRecognition 结果接口
+ * 识别引擎模式
  */
-interface BrowserSpeechRecognitionResult {
-    readonly length: number;
-    readonly isFinal: boolean;
-    item(index: number): BrowserSpeechRecognitionAlternative | null;
-    [index: number]: BrowserSpeechRecognitionAlternative;
-}
+type RecognitionEngineMode = 'native' | 'cloud' | 'auto';
 /**
- * SpeechRecognition 备选结果接口
+ * 云端传输协议类型
  */
-interface BrowserSpeechRecognitionAlternative {
-    readonly transcript: string;
-    readonly confidence: number;
-}
+type CloudTransportType = 'websocket' | 'http';
 /**
- * SpeechRecognition 事件接口
+ * 识别结果接口
  */
-interface BrowserSpeechRecognitionEvent {
-    readonly results: BrowserSpeechRecognitionResultList;
-    readonly resultIndex: number;
+interface IRecognitionResult {
+    /** 识别文本 */
+    transcript: string;
+    /** 是否为最终结果 */
+    isFinal: boolean;
+    /** 置信度 (0-1) */
+    confidence: number;
+    /** 原始响应数据 */
+    original?: unknown;
 }
 /**
- * SpeechRecognition 错误事件接口
- */
-interface BrowserSpeechRecognitionErrorEvent {
-    readonly error: string;
-    readonly message: string;
+ * 音频配置接口
+ */
+interface IAudioConfig {
+    /** 目标采样率 (默认 16000) */
+    sampleRate?: number;
+    /** VAD 阈值 (0.01 ~ 0.5) */
+    vadThreshold?: number;
+    /** VAD 静音超时 (ms) */
+    vadDuration?: number;
+    /** 是否启用回声消除 */
+    echoCancellation?: boolean;
+    /** 是否启用噪声抑制 */
+    noiseSuppression?: boolean;
+    /** 是否启用自动增益控制 */
+    autoGainControl?: boolean;
 }
 /**
- * 浏览器原生 SpeechRecognition 接口
- */
-interface BrowserSpeechRecognition extends EventTarget {
-    lang: string;
-    continuous: boolean;
-    interimResults: boolean;
-    maxAlternatives: number;
-    start(): void;
-    stop(): void;
-    abort(): void;
-    onstart: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
-    onend: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
-    onresult: ((this: BrowserSpeechRecognition, ev: BrowserSpeechRecognitionEvent) => void) | null;
-    onerror: ((this: BrowserSpeechRecognition, ev: BrowserSpeechRecognitionErrorEvent) => void) | null;
-    onsoundstart: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
-    onsoundend: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
-    onspeechstart: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
-    onspeechend: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
-    onaudiostart: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
-    onaudioend: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
-    onnomatch: ((this: BrowserSpeechRecognition, ev: Event) => void) | null;
+ * 高级识别配置
+ */
+interface IAdvancedRecognitionConfig extends RecognitionConfig {
+    /** 识别引擎模式 */
+    mode?: RecognitionEngineMode;
+    /** 云端适配器 */
+    cloudAdapter?: ICloudRecognitionAdapter;
+    /** 传输协议 */
+    transport?: CloudTransportType;
+    /** 音频配置 */
+    audioConfig?: IAudioConfig;
+    /** 是否启用自动重连 */
+    autoReconnect?: boolean;
+    /** 最大重连次数 */
+    maxReconnectAttempts?: number;
+    /** 重连间隔 (ms) */
+    reconnectInterval?: number;
 }
 /**
- * SpeechRecognition 构造函数类型
+ * 云端识别适配器接口
+ * 提供统一的第三方语音识别服务集成接口
  */
-interface BrowserSpeechRecognitionConstructor {
-    new (): BrowserSpeechRecognition;
-}
-declare global {
-    interface Window {
-        SpeechRecognition?: BrowserSpeechRecognitionConstructor;
-        webkitSpeechRecognition?: BrowserSpeechRecognitionConstructor;
-    }
+interface ICloudRecognitionAdapter {
+    /** 适配器名称 */
+    readonly name: string;
+    /**
+     * 获取 WebSocket 连接地址
+     * @returns WebSocket URL
+     */
+    getConnectUrl?(): Promise<string> | string;
+    /**
+     * 获取握手参数
+     * @returns 握手消息
+     */
+    getHandshakeParams?(): unknown;
+    /**
+     * HTTP 短语音识别
+     * @param audioData WAV/PCM 二进制数据
+     * @returns 识别结果
+     */
+    recognizeShortAudio?(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    /**
+     * 转换音频数据格式
+     * @param pcmData PCM 原始数据
+     * @returns 转换后的数据
+     */
+    transformAudioData?(pcmData: ArrayBuffer): ArrayBuffer | string;
+    /**
+     * 解析识别结果
+     * @param data 原始响应数据
+     * @returns 识别结果
+     */
+    parseResult(data: unknown): IRecognitionResult | null;
+    /**
+     * 检查适配器是否可用
+     * @returns 是否可用
+     */
+    isAvailable?(): boolean;
 }
 /**
- * 语音识别器
- * 管理多个提供商，支持自动降级
+ * 语音识别器实现
+ * 统一封装原生识别和云端识别
  */
 declare class SpeechRecognizerImpl implements SpeechRecognizer {
+    private strategy;
+    private config;
     private _currentProvider;
     private _status;
-    private provider;
-    private config;
     private eventHandlers;
-    private providers;
-    /**
-     * 当前使用的提供商类型
-     */
+    private customProviders;
     get currentProvider(): SpeechProviderType;
+    get status(): SpeechServiceStatus;
     /**
-     * 服务状态
+     * 获取当前识别状态
      */
-    get status(): SpeechServiceStatus;
+    get recognitionStatus(): RecognitionStatus;
     /**
      * 初始化语音识别器
-     * @param config - 识别配置
      */
     initialize(config?: RecognitionConfig): Promise<void>;
     /**
-     * 尝试使用指定提供商
+     * 初始化识别策略
      */
-    private tryProvider;
+    private initializeStrategy;
     /**
-     * 转发提供商事件到识别器
+     * 转发策略事件
      */
-    private forwardProviderEvents;
+    private forwardStrategyEvents;
     /**
-     * 开始语音识别
-     * @param config - 可选的识别配置
+     * 转换识别结果格式
+     */
+    private convertResult;
+    /**
+     * 开始识别
      */
     start(config?: RecognitionConfig): Promise<void>;
     /**
-     * 停止语音识别
+     * 停止识别
      */
     stop(): void;
     /**
-     * 中止语音识别
+     * 中止识别
      */
     abort(): void;
     /**
-     * 是否正在监听
+     * 是否正在识别
      */
     isListening(): boolean;
     /**
@@ -584,60 +740,58 @@ declare class SpeechRecognizerImpl implements SpeechRecognizer {
     dispose(): void;
     /**
      * 注册自定义提供商
-     * @param type - 提供商类型
-     * @param provider - 提供商实例
      */
     registerProvider(type: SpeechProviderType, provider: RecognitionProvider): void;
+    /**
+     * 使用云端适配器
+     */
+    useCloudAdapter(adapter: ICloudRecognitionAdapter): void;
 }
 /**
  * 创建语音识别器实例
- * @param config - 可选的识别配置
+ * @param config 识别配置
  * @returns 语音识别器实例
  *
  * @example
  * ```typescript
- * // 创建并初始化语音识别器
+ * // 使用原生识别
  * const recognizer = await createSpeechRecognizer({
  *   lang: 'zh-CN',
  *   continuous: true,
- *   interimResults: true,
  * });
  *
- * // 监听识别结果
+ * // 使用云端识别 (百度)
+ * const baiduAdapter = new BaiduAdapter('your-access-token');
+ * const cloudRecognizer = await createSpeechRecognizer({
+ *   mode: 'cloud',
+ *   cloudAdapter: baiduAdapter,
+ *   transport: 'http',
+ * });
+ *
  * recognizer.on('result', (event) => {
- *   if (event.result) {
- *     console.log('识别结果:', event.result.bestTranscript);
- *   }
+ *   console.log('识别结果:', event.result?.bestTranscript);
  * });
  *
- * // 开始识别
  * await recognizer.start();
- *
- * // 停止识别
- * recognizer.stop();
- *
- * // 销毁
- * recognizer.dispose();
  * ```
  */
-declare function createSpeechRecognizer(config?: RecognitionConfig): Promise<SpeechRecognizer>;
+declare function createSpeechRecognizer(config?: RecognitionConfig | IAdvancedRecognitionConfig): Promise<SpeechRecognizer>;
 /**
  * 检查当前环境是否支持语音识别
- * @returns 是否支持语音识别
+ * @returns 是否支持
  */
 declare function isSpeechRecognitionSupported(): boolean;
 /**
  * 快速进行一次语音识别
- * @param config - 可选的识别配置
+ * @param config 识别配置
  * @returns 识别结果
  *
  * @example
  * ```typescript
- * // 进行一次语音识别
  * const result = await listen({ lang: 'zh-CN' });
  * console.log('识别结果:', result.bestTranscript);
  * ```
  */
-declare function listen(config?: RecognitionConfig): Promise<RecognitionResult>;
+declare function listen(config?: RecognitionConfig | IAdvancedRecognitionConfig): Promise<RecognitionResult>;
 
 export { type AWSSpeechConfig, type AzureSpeechConfig, type BaseSpeechConfig, type CustomProviderConfig, type GoogleSpeechConfig, type ProviderConfig, type RecognitionConfig, type RecognitionEvent, type RecognitionEventHandler, type RecognitionEventType, type RecognitionProvider, type RecognitionResult, type RecognitionResultItem, type SpeechError, type SpeechProviderType, type SpeechRecognizer, SpeechRecognizerImpl, type SpeechServiceStatus, type SpeechSynthesizer, SpeechSynthesizerImpl, type SynthesisConfig, type SynthesisEvent, type SynthesisEventHandler, type SynthesisEventType, type SynthesisProvider, type VoiceInfo, createSpeechRecognizer, createSpeechSynthesizer, isSpeechRecognitionSupported, isSpeechSynthesisSupported, listen, speak };

package/dist/plugins/index.js

@@ -1,4 +1,4 @@
-export { SpeechRecognizerImpl, SpeechSynthesizerImpl, createSpeechRecognizer, createSpeechSynthesizer, isSpeechRecognitionSupported, isSpeechSynthesisSupported, listen, speak } from '../chunk-YGMBCZJQ.js';
+export { SpeechRecognizerImpl, SpeechSynthesizerImpl, createSpeechRecognizer, createSpeechSynthesizer, isSpeechRecognitionSupported, isSpeechSynthesisSupported, listen, speak } from '../chunk-3RM45M64.js';
 import '../chunk-7QVYU63E.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map