@bdky/aaas-pilot-kit 1.0.9 → 1.1.0

package/dist/libs/aaas-pilot-kit/src/lib/utils/EnergyBasedGate.d.ts

@@ -0,0 +1,240 @@
+/**
+ * @file 基于能量检测的智能门控 (Energy-based Gate)
+ * @description 通过实时监测音频能量差异,智能过滤外部音频干扰(如 TTS 回声),减少移动端 ASR 误识别
+ *
+ * 原理:
+ * 1. 实时计算麦克风音频的能量(RMS)
+ * 2. 在降噪启用期间,提高 ASR 激活阈值
+ * 3. 只有当麦克风能量显著高于基准能量时,才允许 ASR 识别
+ * 4. 使用自适应阈值算法,适应不同环境噪音
+ *
+ * 重构版本 (v2):
+ * - ✅ 修复历史窗口计算错误 (100帧 ≠ 1秒)
+ * - ✅ 直接从 inputBuffer 计算 RMS (绕过 analyser 分支不更新问题)
+ * - ✅ Float API 兼容层 (防止 iOS 崩溃)
+ * - ✅ 渐进增强: AudioWorklet → ScriptProcessorNode
+ * - ✅ AudioContext 生命周期管理
+ */
+/**
+ * 能量门控配置选项
+ */
+export interface IEnergyGateOptions {
+    /**
+     * 外部播放抑制启用时的能量倍数阈值
+     * 麦克风能量必须显著高于基准能量才能通过
+     * @default 3.0
+     */
+    suppressionEnergyMultiplier?: number;
+    /**
+     * 空闲期间的基准能量阈值(dBFS)
+     * 低于此值的信号被视为静音或微弱回声
+     * @default -45
+     */
+    idleThreshold?: number;
+    /**
+     * 能量平滑系数(0-1)
+     * 值越大,能量变化越平滑(降低噪声干扰)
+     * @default 0.7
+     */
+    smoothingFactor?: number;
+    /**
+     * 外部播放抑制启用延迟(毫秒)
+     * 启用抑制后,延迟多久才启用高阈值
+     * @default 100
+     */
+    suppressionActivationDelay?: number;
+    /**
+     * 外部播放抑制关闭恢复延迟(毫秒)
+     * 停止抑制后,延迟多久恢复正常阈值
+     * @default 500
+     */
+    suppressionRecoveryDelay?: number;
+    /**
+     * 是否启用调试日志
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * 能量统计数据
+ */
+export interface IEnergyStats {
+    /**
+     * 当前麦克风能量(dBFS)
+     */
+    microphoneEnergy: number;
+    /**
+     * 外部播放抑制是否启用（考虑延迟后的状态）
+     */
+    isSuppressionEnabled: boolean;
+    /**
+     * 当前激活阈值(dBFS)
+     */
+    currentThreshold: number;
+    /**
+     * 信号是否允许通过
+     */
+    isGateOpen: boolean;
+    /**
+     * 最近 1 秒内通过的帧数占比
+     */
+    passRate: number;
+}
+/**
+ * 基于能量检测的智能门控
+ *
+ * @example
+ * ```typescript
+ * const gate = new EnergyBasedGate(audioContext, {
+ *     suppressionEnergyMultiplier: 3.0,
+ *     idleThreshold: -45
+ * });
+ *
+ * // 连接麦克风
+ * microphoneNode.connect(gate.input);
+ *
+ * // 获取过滤后的输出流
+ * const cleanStream = gate.getOutputStream();
+ *
+ * // 外部音频播放时启用回声消除(如 TTS 播报)
+ * tts.on('start', () => gate.setSuppressionEnabled(true));
+ * tts.on('end', () => gate.setSuppressionEnabled(false));
+ *
+ * // 传给 Azure ASR
+ * const audioConfig = SpeechSDK.AudioConfig.fromStreamInput(cleanStream);
+ * ```
+ */
+export declare class EnergyBasedGate {
+    /**
+     * 音频输入节点
+     */
+    readonly input: GainNode;
+    private readonly context;
+    private readonly options;
+    /**
+     * 输出目标节点
+     */
+    private readonly destination;
+    /**
+     * 门控增益节点(用于静音)
+     */
+    private readonly gate;
+    /**
+     * 音频处理器 (AudioWorkletNode 或 ScriptProcessorNode)
+     */
+    private processor;
+    /**
+     * 处理器类型
+     */
+    private processorType;
+    /**
+     * 门控状态历史(用于计算通过率)
+     */
+    private readonly gateHistory;
+    /**
+     * ScriptProcessor 门控历史最大长度(动态计算,约 1 秒)
+     */
+    private readonly scriptProcessorMaxHistoryLength;
+    /**
+     * AudioWorklet 门控历史最大长度(动态计算,约 1 秒)
+     *
+     * @remarks
+     * AudioWorklet 的 render quantum 固定为 128 samples/callback，
+     * 与 ScriptProcessor(这里使用 2048) 不同，因此需要分别计算。
+     */
+    private readonly audioWorkletMaxHistoryLength;
+    /**
+     * 回声消除是否启用
+     */
+    private isSuppressionEnabled;
+    /**
+     * 回声消除状态切换定时器
+     */
+    private suppressionStateTimer;
+    /**
+     * 实际回声消除状态(考虑延迟后的状态)
+     */
+    private effectiveSuppressionState;
+    /**
+     * 当前麦克风能量(RMS,dBFS)
+     */
+    private currentEnergy;
+    /**
+     * 平滑后的能量值
+     */
+    private smoothedEnergy;
+    /**
+     * AudioWorklet 上报的最近一次统计（用于 getStats）
+     */
+    private workletPassRate;
+    private workletIsGateOpen;
+    /**
+     * 是否已启动
+     */
+    private started;
+    /**
+     * 创建配置的promise
+     */
+    private readonly setupAudioGraphPromise;
+    constructor(context: AudioContext, options?: IEnergyGateOptions);
+    /**
+     * 设置外部播放抑制启用状态（例如 TTS 播放期间抬阈）
+     *
+     * @param enabled - 是否启用抑制
+     */
+    setSuppressionEnabled: (enabled: boolean) => void;
+    /**
+     * 启动门控
+     */
+    start: () => void;
+    /**
+     * 停止门控
+     */
+    stop: () => void;
+    /**
+     * 获取处理后的音频流
+     */
+    getOutputStream: () => MediaStream;
+    /**
+     * 获取当前能量统计
+     */
+    getStats: () => IEnergyStats;
+    /**
+     * 动态调整阈值倍数
+     */
+    setEnergyMultiplier: (multiplier: number) => void;
+    /**
+     * 清理资源
+     */
+    dispose: () => void;
+    /**
+     * 搭建音频处理图(异步,支持 AudioWorklet 检测)
+     */
+    private setupAudioGraph;
+    /**
+     * 使用 AudioWorklet 设置音频图
+     */
+    private setupWithAudioWorklet;
+    /**
+     * 使用 ScriptProcessorNode 设置音频图(降级方案)
+     */
+    private setupWithScriptProcessor;
+    /**
+     * ScriptProcessor 音频处理回调
+     * 修复: 直接从 inputBuffer 计算 RMS,绕过 analyser 问题
+     */
+    private readonly processAudioScriptProcessor;
+    /**
+     * 判断门控是否应该打开
+     */
+    private readonly shouldGateOpen;
+    /**
+     * 获取当前激活阈值
+     */
+    private readonly getCurrentThreshold;
+    /**
+     * 获取 AudioWorklet 处理器代码
+     * (内联版本,生产环境可改为加载外部文件)
+     */
+    private getEnergyGateWorkletCode;
+}

package/dist/libs/aaas-pilot-kit/src/lib/utils/MediaStreamManager.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @file MediaStream 管理器
+ * @description 负责获取和管理 MediaStream，支持浏览器特性检测、动态约束构建、降级策略
+ */
+/**
+ * 音频处理特性配置
+ *
+ * 直接使用 Web 标准的 MediaTrackConstraints 类型，支持所有标准音频约束参数
+ *
+ * 常用特性：
+ * - echoCancellation: 回声消除
+ * - noiseSuppression: 降噪处理
+ * - autoGainControl: 自动增益控制
+ * - sampleRate: 采样率（Hz）
+ * - sampleSize: 采样大小（位）
+ * - channelCount: 通道数（1=单声道, 2=立体声）
+ * - deviceId: 设备 ID
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+ */
+export type IAudioFeatureConfig = MediaTrackConstraints;
+/**
+ * 浏览器特性支持检测结果
+ */
+export interface IFeatureSupportResult {
+    /**
+     * 支持的特性列表
+     */
+    supported: string[];
+    /**
+     * 不支持的特性列表
+     */
+    unsupported: string[];
+    /**
+     * 是否有不支持的特性
+     */
+    hasUnsupportedFeatures: boolean;
+}
+/**
+ * MediaStream 获取结果
+ */
+export interface IMediaStreamResult {
+    /**
+     * 获取到的 MediaStream 实例
+     */
+    stream: MediaStream;
+    /**
+     * 实际应用的约束配置
+     */
+    appliedConstraints: MediaTrackConstraints;
+    /**
+     * 启用的特性列表（用于调试）
+     */
+    enabledFeatures: string[];
+    /**
+     * 浏览器不支持的特性列表
+     */
+    unsupportedFeatures: string[];
+}
+/**
+ * MediaStreamManager 配置选项
+ */
+export interface IMediaStreamManagerOptions {
+    /**
+     * 音频特性配置
+     * @default { echoCancellation: true, noiseSuppression: true, autoGainControl: true }
+     */
+    audioFeatures?: IAudioFeatureConfig;
+    /**
+     * 是否在检测到不支持的特性时输出警告
+     * @default true
+     */
+    warnOnUnsupportedFeatures?: boolean;
+    /**
+     * 是否在成功获取流后输出调试信息
+     * @default true
+     */
+    logEnabledFeatures?: boolean;
+    /**
+     * 是否在完全不支持任何特性时回退到基础约束 {audio: true}
+     * @default true
+     */
+    enableFallback?: boolean;
+}
+/**
+ * MediaStream 管理器
+ *
+ * 负责获取和管理 MediaStream，支持：
+ * - 浏览器特性检测（echoCancellation、noiseSuppression、autoGainControl）
+ * - 动态约束构建（仅使用支持的特性）
+ * - 降级策略（不支持时使用基础约束）
+ * - 资源清理
+ *
+ * @example 默认配置
+ * ```typescript
+ * const manager = new MediaStreamManager();
+ * const result = await manager.getUserMedia();
+ * console.log('启用的特性:', result.enabledFeatures);
+ *
+ * // 使用完毕后清理
+ * manager.cleanup();
+ * ```
+ *
+ * @example 自定义配置
+ * ```typescript
+ * const manager = new MediaStreamManager({
+ *   audioFeatures: {
+ *     echoCancellation: true,
+ *     noiseSuppression: true,
+ *     autoGainControl: false,  // 禁用自动增益
+ *     sampleRate: 48000,       // 高采样率
+ *     channelCount: 1          // 单声道
+ *   },
+ *   warnOnUnsupportedFeatures: true
+ * });
+ *
+ * const result = await manager.getUserMedia();
+ * ```
+ */
+export declare class MediaStreamManager {
+    /**
+     * 默认音频特性配置（三大核心特性）
+     */
+    private static readonly DEFAULT_AUDIO_FEATURES;
+    /**
+     * 当前持有的 MediaStream 实例
+     */
+    private mediaStream;
+    /**
+     * 管理器配置选项
+     */
+    private readonly options;
+    /**
+     * 构造函数
+     *
+     * @param options - 配置选项
+     */
+    constructor(options?: IMediaStreamManagerOptions);
+    /**
+     * 检测浏览器支持的音频约束特性
+     *
+     * @returns 特性支持检测结果
+     */
+    checkFeatureSupport: () => IFeatureSupportResult;
+    /**
+     * 获取 MediaStream
+     *
+     * 核心方法，执行以下流程：
+     * 1. 检测浏览器特性支持
+     * 2. 构建动态约束对象
+     * 3. 降级处理（如需要）
+     * 4. 调用 getUserMedia 获取流
+     * 5. 记录日志
+     *
+     * @returns MediaStream 获取结果
+     * @throws Error - 获取失败时抛出原始错误（包含权限、设备等）
+     */
+    getUserMedia: () => Promise<IMediaStreamResult>;
+    /**
+     * 获取当前持有的 MediaStream
+     *
+     * @returns 当前的 MediaStream 实例，如果未获取则返回 null
+     */
+    getStream: () => MediaStream | null;
+    /**
+     * 控制音频轨道静音
+     *
+     * 通过设置 MediaStreamTrack.enabled 实现软静音
+     * enabled = false 时，track 生成空帧
+     *
+     * @param muted - 是否静音
+     * @returns this（支持链式调用）
+     */
+    mute: (muted: boolean) => MediaStreamManager;
+    /**
+     * 清理资源
+     *
+     * 停止所有音频轨道并释放 MediaStream
+     * 调用后可以再次调用 getUserMedia 获取新流
+     */
+    cleanup: () => void;
+    /**
+     * 检查当前是否持有有效的 MediaStream
+     *
+     * @returns 是否持有有效流
+     */
+    hasActiveStream: () => boolean;
+    /**
+     * 构建动态音频约束对象
+     *
+     * 仅包含浏览器支持的特性
+     *
+     * @param supportResult - 特性支持检测结果
+     * @returns 动态构建的约束对象
+     */
+    private readonly buildAudioConstraints;
+    /**
+     * 记录不支持的特性警告
+     *
+     * @param unsupportedFeatures - 不支持的特性列表
+     */
+    private readonly logUnsupportedFeaturesWarning;
+    /**
+     * 记录启用的特性
+     *
+     * @param enabledFeatures - 启用的特性列表
+     */
+    private readonly logEnabledFeatures;
+}

package/dist/libs/aaas-pilot-kit/src/lib/utils/audio-processing/AudioContextLifecycle.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @file AudioContext 生命周期管理
+ * @description 管理 AudioContext 在移动端的生命周期,处理页面后台/前台切换
+ *
+ * 移动端问题:
+ * - iOS: 页面后台运行或锁屏后,AudioContext 自动 suspend
+ * - Android: 部分设备在后台会暂停音频处理
+ * - 用户需要手动恢复(需要用户手势)
+ *
+ * 解决方案:
+ * - 监听 visibilitychange 事件
+ * - 监听 AudioContext.statechange 事件
+ * - 页面前台时自动尝试 resume
+ * - 提供回调通知上层应用
+ */
+/**
+ * AudioContext 生命周期选项
+ */
+export interface IAudioContextLifecycleOptions {
+    /**
+     * Context 被挂起时的回调
+     */
+    onSuspended?: () => void;
+    /**
+     * Context 恢复运行时的回调
+     */
+    onResumed?: () => void;
+    /**
+     * Context 被中断时的回调 (如来电)
+     */
+    onInterrupted?: () => void;
+    /**
+     * 是否自动恢复 (页面前台时)
+     * @default true
+     */
+    autoResume?: boolean;
+}
+/**
+ * AudioContext 生命周期管理器
+ *
+ * @example
+ * ```typescript
+ * const context = new AudioContext();
+ * const lifecycle = new AudioContextLifecycle(
+ *     context,
+ *     {
+ *         onSuspended: () => console.log('Audio suspended'),
+ *         onResumed: () => console.log('Audio resumed'),
+ *         autoResume: true
+ *     }
+ * );
+ *
+ * lifecycle.startMonitoring();
+ *
+ * // 手动确保运行 (需要用户手势上下文)
+ * await lifecycle.ensureRunning();
+ *
+ * // 停止监控
+ * lifecycle.stopMonitoring();
+ * lifecycle.dispose();
+ * ```
+ */
+export declare class AudioContextLifecycle {
+    private readonly context;
+    private readonly options;
+    private isMonitoring;
+    private readonly boundHandleVisibilityChange;
+    private readonly boundHandleStateChange;
+    constructor(context: AudioContext, options?: IAudioContextLifecycleOptions);
+    /**
+     * 开始监控 AudioContext 生命周期
+     *
+     * @remarks
+     * 监听:
+     * - document.visibilitychange (页面前后台切换)
+     * - AudioContext.statechange (Context 状态变化)
+     * - window.pagehide/pageshow (iOS 特定)
+     */
+    startMonitoring: () => void;
+    /**
+     * 停止监控
+     */
+    stopMonitoring: () => void;
+    /**
+     * 确保 AudioContext 处于运行状态
+     *
+     * @returns 是否成功恢复到运行状态
+     *
+     * @remarks
+     * - 必须在用户手势上下文中调用 (如 click/touch 事件)
+     * - 如果 Context 已关闭,无法恢复,返回 false
+     */
+    ensureRunning: () => Promise<boolean>;
+    /**
+     * 获取当前 AudioContext 状态
+     */
+    getState: () => AudioContextState;
+    /**
+     * 清理资源
+     */
+    dispose: () => void;
+    /**
+     * 处理页面可见性变化
+     */
+    private readonly handleVisibilityChange;
+    /**
+     * 处理 AudioContext 状态变化
+     */
+    private readonly handleStateChange;
+}

package/dist/libs/aaas-pilot-kit/src/lib/utils/audio-processing/AudioWorkletCapability.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @file AudioWorklet 能力检测
+ * @description 检测浏览器是否支持 AudioWorklet API
+ *
+ * 浏览器支持情况:
+ * - Chrome 66+ ✅
+ * - Edge 79+ ✅
+ * - Safari 14.1+ ✅
+ * - Firefox 76+ ✅
+ * - iOS Safari 14.5+ ✅
+ * - Android Chrome 66+ ✅
+ *
+ * 降级场景:
+ * - Safari < 14.1 → ScriptProcessorNode
+ * - iOS Safari < 14.5 → ScriptProcessorNode
+ * - Android WebView (部分) → ScriptProcessorNode
+ */
+/**
+ * AudioWorklet 能力检测结果
+ */
+export interface IAudioWorkletCapability {
+    /**
+     * 是否支持 AudioWorklet
+     */
+    supported: boolean;
+    /**
+     * 不支持的原因 (仅当 supported=false 时)
+     */
+    reason?: 'no-audio-worklet' | 'no-add-module' | 'no-constructor' | 'context-error' | 'test-load-failed';
+}
+/**
+ * AudioWorklet 能力检测工具
+ *
+ * @example
+ * ```typescript
+ * const context = new AudioContext();
+ * const capability = await AudioWorkletCapability.check(context);
+ *
+ * if (capability.supported) {
+ *     // 使用 AudioWorklet
+ *     await context.audioWorklet.addModule('processor.js');
+ *     const node = new AudioWorkletNode(context, 'my-processor');
+ * }
+ * else {
+ *     // 降级到 ScriptProcessorNode
+ *     console.warn('AudioWorklet not supported:', capability.reason);
+ *     const node = context.createScriptProcessor(2048, 1, 1);
+ * }
+ * ```
+ */
+export declare class AudioWorkletCapability {
+    /**
+     * 缓存的检测结果 (避免重复检测)
+     */
+    private static cachedResult;
+    /**
+     * 检测 AudioWorklet 支持情况
+     *
+     * @param context - AudioContext 实例
+     * @returns 检测结果
+     *
+     * @remarks
+     * - 首次调用会执行实际检测并缓存结果
+     * - 后续调用直接返回缓存结果
+     * - 调用 reset() 可清除缓存
+     */
+    static check: (context: AudioContext) => Promise<IAudioWorkletCapability>;
+    /**
+     * 重置缓存的检测结果
+     *
+     * @remarks
+     * 调用此方法后,下次 check() 会重新执行检测
+     * 一般用于测试场景
+     */
+    static reset: () => void;
+    /**
+     * 同步检测 (仅基础属性检查,不执行加载测试)
+     *
+     * @param context - AudioContext 实例
+     * @returns 是否可能支持 AudioWorklet
+     *
+     * @remarks
+     * - 此方法仅检查 API 存在性,不测试实际加载
+     * - 返回 true 不保证 100% 可用,建议使用异步的 check()
+     * - 用于快速预判,避免不必要的异步等待
+     */
+    static checkSync: (context: AudioContext) => boolean;
+    /**
+     * 执行实际的能力检测
+     *
+     * @param context - AudioContext 实例
+     * @returns 检测结果
+     */
+    private static readonly performCheck;
+}