@lee-zg/melange 1.0.0

package/dist/plugins/index.d.cts

@@ -0,0 +1,643 @@
+/**
+ * @fileoverview 语音模块类型定义
+ * @module melange/plugins/speech/types
+ * @description 语音合成和语音识别的类型定义
+ */
+/**
+ * 语音服务提供商类型
+ */
+type SpeechProviderType = 'browser' | 'azure' | 'google' | 'aws' | 'custom';
+/**
+ * 语音服务状态
+ */
+type SpeechServiceStatus = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * 语音服务错误
+ */
+interface SpeechError {
+    /** 错误代码 */
+    code: string;
+    /** 错误信息 */
+    message: string;
+    /** 原始错误对象 */
+    originalError?: Error;
+}
+/**
+ * 语音服务基础配置
+ */
+interface BaseSpeechConfig {
+    /** 语言代码 (如 'zh-CN', 'en-US') */
+    lang?: string;
+    /** 首选提供商 */
+    preferredProvider?: SpeechProviderType;
+    /** 是否自动降级 */
+    autoFallback?: boolean;
+    /** 降级提供商列表 */
+    fallbackProviders?: SpeechProviderType[];
+}
+/**
+ * 语音信息
+ */
+interface VoiceInfo {
+    /** 语音唯一标识 */
+    id: string;
+    /** 语音名称 */
+    name: string;
+    /** 语言代码 */
+    lang: string;
+    /** 是否为本地语音 */
+    localService: boolean;
+    /** 是否为默认语音 */
+    default: boolean;
+    /** 提供商类型 */
+    provider: SpeechProviderType;
+}
+/**
+ * 语音合成配置
+ */
+interface SynthesisConfig extends BaseSpeechConfig {
+    /** 语音对象或语音名称 */
+    voice?: VoiceInfo | string;
+    /** 音量 (0-1) */
+    volume?: number;
+    /** 语速 (0.1-10) */
+    rate?: number;
+    /** 音调 (0-2) */
+    pitch?: number;
+}
+/**
+ * 语音合成事件类型
+ */
+type SynthesisEventType = 'start' | 'end' | 'pause' | 'resume' | 'boundary' | 'mark' | 'error';
+/**
+ * 语音合成事件数据
+ */
+interface SynthesisEvent {
+    /** 事件类型 */
+    type: SynthesisEventType;
+    /** 当前字符索引 */
+    charIndex?: number;
+    /** 当前字符长度 */
+    charLength?: number;
+    /** 经过的时间（毫秒） */
+    elapsedTime?: number;
+    /** 边界名称 */
+    name?: string;
+    /** 错误信息 */
+    error?: SpeechError;
+}
+/**
+ * 语音合成事件处理器
+ */
+type SynthesisEventHandler = (event: SynthesisEvent) => void;
+/**
+ * 语音合成提供商接口
+ */
+interface SynthesisProvider {
+    /** 提供商类型 */
+    readonly type: SpeechProviderType;
+    /** 检查是否可用 */
+    isAvailable(): boolean;
+    /** 获取可用语音列表 */
+    getVoices(): Promise<VoiceInfo[]>;
+    /** 朗读文本 */
+    speak(text: string, config?: SynthesisConfig): Promise<void>;
+    /** 暂停 */
+    pause(): void;
+    /** 继续 */
+    resume(): void;
+    /** 取消 */
+    cancel(): void;
+    /** 是否正在朗读 */
+    isSpeaking(): boolean;
+    /** 是否已暂停 */
+    isPaused(): boolean;
+    /** 添加事件监听 */
+    on(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /** 移除事件监听 */
+    off(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+}
+/**
+ * 语音合成器接口
+ */
+interface SpeechSynthesizer {
+    /** 当前使用的提供商 */
+    readonly currentProvider: SpeechProviderType;
+    /** 服务状态 */
+    readonly status: SpeechServiceStatus;
+    /** 初始化 */
+    initialize(config?: SynthesisConfig): Promise<void>;
+    /** 获取可用语音列表 */
+    getVoices(): Promise<VoiceInfo[]>;
+    /** 朗读文本 */
+    speak(text: string, config?: SynthesisConfig): Promise<void>;
+    /** 暂停 */
+    pause(): void;
+    /** 继续 */
+    resume(): void;
+    /** 取消 */
+    cancel(): void;
+    /** 是否正在朗读 */
+    isSpeaking(): boolean;
+    /** 是否已暂停 */
+    isPaused(): boolean;
+    /** 添加事件监听 */
+    on(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /** 移除事件监听 */
+    off(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /** 销毁实例 */
+    dispose(): void;
+}
+/**
+ * 识别结果项
+ */
+interface RecognitionResultItem {
+    /** 识别的文本 */
+    transcript: string;
+    /** 置信度 (0-1) */
+    confidence: number;
+    /** 是否为最终结果 */
+    isFinal: boolean;
+}
+/**
+ * 识别结果
+ */
+interface RecognitionResult {
+    /** 结果列表 */
+    results: RecognitionResultItem[];
+    /** 最佳结果 */
+    bestTranscript: string;
+    /** 最佳置信度 */
+    bestConfidence: number;
+    /** 是否为最终结果 */
+    isFinal: boolean;
+}
+/**
+ * 语音识别配置
+ */
+interface RecognitionConfig extends BaseSpeechConfig {
+    /** 是否连续识别 */
+    continuous?: boolean;
+    /** 是否返回中间结果 */
+    interimResults?: boolean;
+    /** 最大备选结果数 */
+    maxAlternatives?: number;
+    /** 语法列表 (仅部分浏览器支持) */
+    grammars?: string[];
+}
+/**
+ * 语音识别事件类型
+ */
+type RecognitionEventType = 'start' | 'end' | 'result' | 'error' | 'soundstart' | 'soundend' | 'speechstart' | 'speechend' | 'audiostart' | 'audioend' | 'nomatch';
+/**
+ * 语音识别事件数据
+ */
+interface RecognitionEvent {
+    /** 事件类型 */
+    type: RecognitionEventType;
+    /** 识别结果 (仅 result 事件) */
+    result?: RecognitionResult;
+    /** 错误信息 (仅 error 事件) */
+    error?: SpeechError;
+}
+/**
+ * 语音识别事件处理器
+ */
+type RecognitionEventHandler = (event: RecognitionEvent) => void;
+/**
+ * 语音识别提供商接口
+ */
+interface RecognitionProvider {
+    /** 提供商类型 */
+    readonly type: SpeechProviderType;
+    /** 检查是否可用 */
+    isAvailable(): boolean;
+    /** 开始识别 */
+    start(config?: RecognitionConfig): Promise<void>;
+    /** 停止识别 */
+    stop(): void;
+    /** 中止识别 */
+    abort(): void;
+    /** 是否正在识别 */
+    isListening(): boolean;
+    /** 添加事件监听 */
+    on(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /** 移除事件监听 */
+    off(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+}
+/**
+ * 语音识别器接口
+ */
+interface SpeechRecognizer {
+    /** 当前使用的提供商 */
+    readonly currentProvider: SpeechProviderType;
+    /** 服务状态 */
+    readonly status: SpeechServiceStatus;
+    /** 初始化 */
+    initialize(config?: RecognitionConfig): Promise<void>;
+    /** 开始识别 */
+    start(config?: RecognitionConfig): Promise<void>;
+    /** 停止识别 */
+    stop(): void;
+    /** 中止识别 */
+    abort(): void;
+    /** 是否正在识别 */
+    isListening(): boolean;
+    /** 添加事件监听 */
+    on(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /** 移除事件监听 */
+    off(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /** 销毁实例 */
+    dispose(): void;
+}
+/**
+ * Azure 语音服务配置
+ */
+interface AzureSpeechConfig {
+    /** 订阅密钥 */
+    subscriptionKey: string;
+    /** 服务区域 */
+    region: string;
+    /** 自定义端点 */
+    endpoint?: string;
+}
+/**
+ * Google Cloud Speech 配置
+ */
+interface GoogleSpeechConfig {
+    /** API 密钥 */
+    apiKey: string;
+    /** 项目 ID */
+    projectId?: string;
+}
+/**
+ * AWS Polly/Transcribe 配置
+ */
+interface AWSSpeechConfig {
+    /** 访问密钥 ID */
+    accessKeyId: string;
+    /** 秘密访问密钥 */
+    secretAccessKey: string;
+    /** 区域 */
+    region: string;
+}
+/**
+ * 自定义提供商配置
+ */
+interface CustomProviderConfig {
+    /** 合成 API 端点 */
+    synthesisEndpoint?: string;
+    /** 识别 API 端点 */
+    recognitionEndpoint?: string;
+    /** 自定义请求头 */
+    headers?: Record<string, string>;
+    /** 认证令牌 */
+    authToken?: string;
+}
+/**
+ * 提供商配置联合类型
+ */
+type ProviderConfig = AzureSpeechConfig | GoogleSpeechConfig | AWSSpeechConfig | CustomProviderConfig;
+
+/**
+ * @fileoverview 语音合成 (TTS) 实现
+ * @module melange/plugins/speech/synthesis
+ * @description 提供语音合成功能，支持浏览器原生 API 和第三方服务降级
+ */
+
+/**
+ * 语音合成器
+ * 管理多个提供商，支持自动降级
+ */
+declare class SpeechSynthesizerImpl implements SpeechSynthesizer {
+    private _currentProvider;
+    private _status;
+    private provider;
+    private config;
+    private eventHandlers;
+    private providers;
+    /**
+     * 当前使用的提供商类型
+     */
+    get currentProvider(): SpeechProviderType;
+    /**
+     * 服务状态
+     */
+    get status(): SpeechServiceStatus;
+    /**
+     * 初始化语音合成器
+     * @param config - 合成配置
+     */
+    initialize(config?: SynthesisConfig): Promise<void>;
+    /**
+     * 尝试使用指定提供商
+     */
+    private tryProvider;
+    /**
+     * 转发提供商事件到合成器
+     */
+    private forwardProviderEvents;
+    /**
+     * 获取可用语音列表
+     */
+    getVoices(): Promise<VoiceInfo[]>;
+    /**
+     * 朗读文本
+     * @param text - 要朗读的文本
+     * @param config - 可选的合成配置
+     */
+    speak(text: string, config?: SynthesisConfig): Promise<void>;
+    /**
+     * 暂停朗读
+     */
+    pause(): void;
+    /**
+     * 继续朗读
+     */
+    resume(): void;
+    /**
+     * 取消朗读
+     */
+    cancel(): void;
+    /**
+     * 是否正在朗读
+     */
+    isSpeaking(): boolean;
+    /**
+     * 是否已暂停
+     */
+    isPaused(): boolean;
+    /**
+     * 添加事件监听
+     */
+    on(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /**
+     * 移除事件监听
+     */
+    off(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /**
+     * 触发事件
+     */
+    private emit;
+    /**
+     * 销毁实例
+     */
+    dispose(): void;
+    /**
+     * 注册自定义提供商
+     * @param type - 提供商类型
+     * @param provider - 提供商实例
+     */
+    registerProvider(type: SpeechProviderType, provider: SynthesisProvider): void;
+}
+/**
+ * 创建语音合成器实例
+ * @param config - 可选的合成配置
+ * @returns 语音合成器实例
+ *
+ * @example
+ * ```typescript
+ * // 创建并初始化语音合成器
+ * const synthesizer = await createSpeechSynthesizer({
+ *   lang: 'zh-CN',
+ *   rate: 1.0,
+ *   pitch: 1.0,
+ * });
+ *
+ * // 朗读文本
+ * await synthesizer.speak('你好，世界！');
+ *
+ * // 监听事件
+ * synthesizer.on('end', () => {
+ *   console.log('朗读完成');
+ * });
+ *
+ * // 销毁
+ * synthesizer.dispose();
+ * ```
+ */
+declare function createSpeechSynthesizer(config?: SynthesisConfig): Promise<SpeechSynthesizer>;
+/**
+ * 检查当前环境是否支持语音合成
+ * @returns 是否支持语音合成
+ */
+declare function isSpeechSynthesisSupported(): boolean;
+/**
+ * 快速朗读文本（一次性使用）
+ * @param text - 要朗读的文本
+ * @param config - 可选的合成配置
+ *
+ * @example
+ * ```typescript
+ * // 快速朗读
+ * await speak('你好，世界！');
+ *
+ * // 带配置的朗读
+ * await speak('Hello World', { lang: 'en-US', rate: 0.8 });
+ * ```
+ */
+declare function speak(text: string, config?: SynthesisConfig): Promise<void>;
+
+/**
+ * @fileoverview 语音识别 (STT) 实现
+ * @module melange/plugins/speech/recognition
+ * @description 提供语音识别功能，支持浏览器原生 API 和第三方服务降级
+ */
+
+/**
+ * SpeechRecognition 结果列表接口
+ */
+interface BrowserSpeechRecognitionResultList {
+    readonly length: number;
+    item(index: number): BrowserSpeechRecognitionResult | null;
+    [index: number]: BrowserSpeechRecognitionResult;
+}
+/**
+ * SpeechRecognition 结果接口
+ */
+interface BrowserSpeechRecognitionResult {
+    readonly length: number;
+    readonly isFinal: boolean;
+    item(index: number): BrowserSpeechRecognitionAlternative | null;
+    [index: number]: BrowserSpeechRecognitionAlternative;
+}
+/**
+ * SpeechRecognition 备选结果接口
+ */
+interface BrowserSpeechRecognitionAlternative {
+    readonly transcript: string;
+    readonly confidence: number;
+}
+/**
+ * SpeechRecognition 事件接口
+ */
+interface BrowserSpeechRecognitionEvent {
+    readonly results: BrowserSpeechRecognitionResultList;
+    readonly resultIndex: number;
+}
+/**
+ * SpeechRecognition 错误事件接口
+ */
+interface BrowserSpeechRecognitionErrorEvent {
+    readonly error: string;
+    readonly message: string;
+}
+/**
+ * 浏览器原生 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;
+}
+/**
+ * SpeechRecognition 构造函数类型
+ */
+interface BrowserSpeechRecognitionConstructor {
+    new (): BrowserSpeechRecognition;
+}
+declare global {
+    interface Window {
+        SpeechRecognition?: BrowserSpeechRecognitionConstructor;
+        webkitSpeechRecognition?: BrowserSpeechRecognitionConstructor;
+    }
+}
+/**
+ * 语音识别器
+ * 管理多个提供商，支持自动降级
+ */
+declare class SpeechRecognizerImpl implements SpeechRecognizer {
+    private _currentProvider;
+    private _status;
+    private provider;
+    private config;
+    private eventHandlers;
+    private providers;
+    /**
+     * 当前使用的提供商类型
+     */
+    get currentProvider(): SpeechProviderType;
+    /**
+     * 服务状态
+     */
+    get status(): SpeechServiceStatus;
+    /**
+     * 初始化语音识别器
+     * @param config - 识别配置
+     */
+    initialize(config?: RecognitionConfig): Promise<void>;
+    /**
+     * 尝试使用指定提供商
+     */
+    private tryProvider;
+    /**
+     * 转发提供商事件到识别器
+     */
+    private forwardProviderEvents;
+    /**
+     * 开始语音识别
+     * @param config - 可选的识别配置
+     */
+    start(config?: RecognitionConfig): Promise<void>;
+    /**
+     * 停止语音识别
+     */
+    stop(): void;
+    /**
+     * 中止语音识别
+     */
+    abort(): void;
+    /**
+     * 是否正在监听
+     */
+    isListening(): boolean;
+    /**
+     * 添加事件监听
+     */
+    on(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /**
+     * 移除事件监听
+     */
+    off(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /**
+     * 触发事件
+     */
+    private emit;
+    /**
+     * 销毁实例
+     */
+    dispose(): void;
+    /**
+     * 注册自定义提供商
+     * @param type - 提供商类型
+     * @param provider - 提供商实例
+     */
+    registerProvider(type: SpeechProviderType, provider: RecognitionProvider): void;
+}
+/**
+ * 创建语音识别器实例
+ * @param config - 可选的识别配置
+ * @returns 语音识别器实例
+ *
+ * @example
+ * ```typescript
+ * // 创建并初始化语音识别器
+ * const recognizer = await createSpeechRecognizer({
+ *   lang: 'zh-CN',
+ *   continuous: true,
+ *   interimResults: true,
+ * });
+ *
+ * // 监听识别结果
+ * recognizer.on('result', (event) => {
+ *   if (event.result) {
+ *     console.log('识别结果:', event.result.bestTranscript);
+ *   }
+ * });
+ *
+ * // 开始识别
+ * await recognizer.start();
+ *
+ * // 停止识别
+ * recognizer.stop();
+ *
+ * // 销毁
+ * recognizer.dispose();
+ * ```
+ */
+declare function createSpeechRecognizer(config?: RecognitionConfig): Promise<SpeechRecognizer>;
+/**
+ * 检查当前环境是否支持语音识别
+ * @returns 是否支持语音识别
+ */
+declare function isSpeechRecognitionSupported(): boolean;
+/**
+ * 快速进行一次语音识别
+ * @param config - 可选的识别配置
+ * @returns 识别结果
+ *
+ * @example
+ * ```typescript
+ * // 进行一次语音识别
+ * const result = await listen({ lang: 'zh-CN' });
+ * console.log('识别结果:', result.bestTranscript);
+ * ```
+ */
+declare function listen(config?: RecognitionConfig): 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 };