@bdky/aaas-pilot-kit 1.0.8 → 1.1.0

package/dist/libs/aaas-pilot-kit/src/lib/service/rtc-asr/asr/baseAsrService.d.ts

@@ -1,6 +1,7 @@
 import Emittery from 'emittery';
 import type { IResolvedOptions } from '../../../../types/config';
 import type { BaseSignalingService } from '../signal/base';
+import type { MediaStreamManager } from '../../../utils/MediaStreamManager';
 import { ErrorManager } from '../../../error';
 import { type AudioDeviceCheckResult, type AudioDetectorOptions } from '../../../utils/AudioDeviceDetector';
 export declare namespace NBaseAsrService {
@@ -37,6 +38,7 @@ export declare namespace NBaseAsrService {
     interface IMessageEventPayload extends IMessageProtocol, IEventWithSessionIdPayload {
     }
     type IDeviceCheckCompletedPayload = AudioDeviceCheckResult;
+    type IDeviceCheckResult = AudioDeviceCheckResult;
     interface IEmitter {
         start: IStartEventPayload;
         stop: IStopEventPayload;
@@ -58,11 +60,25 @@ export declare abstract class BaseAsrService<E extends NBaseAsrService.IEmitter
     muted: boolean;
     readonly emitter: Emittery<E, E & import("emittery").OmnipresentEventData, import("emittery").DatalessEventNames<E>>;
     protected started: boolean;
+    protected customSessionId: string | null;
+    /**
+     * MediaStream 管理器（通过 DI 注入）
+     */
+    protected readonly streamManager: MediaStreamManager;
     private lastCheckResult;
     private lastCheckTime;
     private readonly CHECK_CACHE_TTL;
-    constructor(opts: IResolvedOptions, signalingService: BaseSignalingService, errorManager: ErrorManager);
+    constructor(opts: IResolvedOptions, signalingService: BaseSignalingService, errorManager: ErrorManager, streamManager: MediaStreamManager);
     get sessionId(): string | null;
+    /**
+     * 静音控制
+     *
+     * 实现说明：
+     * - BRTC: 调用 signalingService.Mute()，由 BRTC SDK 控制
+     * - Azure: 设置 MediaStreamTrack.enabled = false，生成空帧（软静音）
+     *
+     * @param muted - 是否静音
+     */
     mute: (muted: boolean) => void;
     setMutedByUser: (muted: boolean) => void;
     /**
@@ -75,6 +91,18 @@ export declare abstract class BaseAsrService<E extends NBaseAsrService.IEmitter
     tryUnmuteAsr: () => boolean;
     disable: () => void;
     enable: () => void;
+    /**
+     * 设置外部播放抑制启用状态
+     *
+     * 该方法用于控制 ASR 输入的外部播放抑制策略（例如 TTS 外放期间抬阈门控）。
+     *
+     * @param enabled - 是否启用抑制
+     *
+     * @remarks
+     * - 默认实现为空操作，需要子类根据具体实现来重写
+     * - 例如 Azure ASR 使用能量门控（EnergyBasedGate）进行抬阈抑制
+     */
+    setPlaybackSuppressionEnabled: (enabled: boolean) => void;
     /**
      * 检查音频设备可用性
      *
@@ -102,6 +130,15 @@ export declare abstract class BaseAsrService<E extends NBaseAsrService.IEmitter
     checkAudioDevice: (options?: AudioDetectorOptions & {
         forceCheck?: boolean;
     }) => Promise<AudioDeviceCheckResult>;
+    /**
+     * 处理麦克风检测失败的策略
+     *
+     * @param strategy - 处理策略
+     * @param result - 检测结果
+     * @param callback - 用户自定义回调（仅 prompt 策略使用）
+     * @returns Promise<boolean> - true: 继续启动，false: 终止启动
+     */
+    protected readonly handleMicrophoneCheckFailure: (strategy: "error" | "warn" | "silent" | "prompt", result: AudioDeviceCheckResult, callback?: (result: AudioDeviceCheckResult) => Promise<boolean>) => Promise<boolean>;
     protected readonly _stop: () => Promise<void>;
     protected readonly _dispose: () => void;
     /**
@@ -112,6 +149,4 @@ export declare abstract class BaseAsrService<E extends NBaseAsrService.IEmitter
     abstract start(): Promise<void>;
     abstract stop(): Promise<void>;
     abstract dispose(): void;
-    protected abstract makeStartOptions(extra: any): unknown;
-    protected abstract parseMessage(raw: string): NBaseAsrService.IMessageProtocol;
 }

package/dist/libs/aaas-pilot-kit/src/lib/service/rtc-asr/signal/noop.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file 空信令服务实现（用于不需要 Signaling 的 ASR，如 Azure）
+ * @description 用于满足 DI 容器的依赖注入要求，但实际不执行任何信令操作
+ */
+import { BaseSignalingService } from './base';
+/**
+ * 空信令服务（No-op Signaling Service）
+ *
+ * 用于不需要独立信令层的 ASR 实现（如 Azure Speech SDK）
+ * 提供最小化的方法实现以满足 BaseSignalingService 接口要求
+ *
+ * 特点：
+ * - 不执行任何实际的信令操作
+ * - 自动生成简单的 sessionId
+ * - 所有方法都是空操作（no-op）
+ *
+ * 使用场景：
+ * - Azure ASR 不需要独立的信令服务
+ * - 其他自管理连接的 ASR 实现
+ */
+export declare class NoopSignalingService extends BaseSignalingService {
+    /**
+     * 启动信令服务（空操作）
+     *
+     * 仅生成一个简单的 sessionId 以满足接口要求
+     *
+     * @param _opts - 启动选项（未使用）
+     */
+    Start<P extends Record<string, any>>(_opts: P): Promise<void>;
+    /**
+     * 停止信令服务（空操作）
+     *
+     * 清空 sessionId
+     */
+    Stop(): Promise<void>;
+    /**
+     * 销毁信令服务（空操作）
+     *
+     * 调用基类的 _dispose 方法进行清理
+     */
+    Dispose(): void;
+    /**
+     * 静音控制（空操作）
+     *
+     * @param _muted - 是否静音（未使用）
+     */
+    Mute(_muted: boolean): void;
+    /**
+     * 获取会话 ID
+     *
+     * @returns 自动生成的会话 ID
+     */
+    GetSessionID(): string;
+}

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

@@ -46,8 +46,10 @@ export interface AudioDeviceCheckResult {
     available: boolean;
     /** 错误类型 (仅在 available = false 时存在) */
     error?: AudioDeviceError;
-    /** 错误详细信息 */
+    /** 错误详细信息（技术性） */
     message?: string;
+    /** 用户友好的错误提示文案 */
+    userMessage?: string;
     /** 检测通过的层级 (1-4) */
     passedLevel?: number;
     /** 找到的音频设备列表 */

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;
+}