@voiceloop/web-sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+type LogLevel = "info" | "warn" | "error";
+type LogEntry = {
+    id: number;
+    ts: number;
+    level: LogLevel;
+    tag: string;
+    msg: string;
+    detail?: string;
+};
+declare function log(tag: string, msg: string, detail?: string, level?: LogLevel): void;
+declare function warn(tag: string, msg: string, detail?: string): void;
+declare function logError(tag: string, msg: string, detail?: string): void;
+declare function getEntries(): readonly LogEntry[];
+declare function clearLog(): void;
+declare function subscribe(fn: () => void): () => void;
+declare function formatForCopy(): string;
+
+declare const MIC_SAMPLE_RATE = 16000;
+declare const TTS_SAMPLE_RATE = 24000;
+type AudioCaptureHandle = {
+    stop: () => void;
+    getVolume: () => number;
+};
+declare function startMicCapture(onPcm: (chunk: ArrayBuffer) => void): Promise<AudioCaptureHandle>;
+type PcmPlayerHandle = {
+    enqueue: (pcm: Uint8Array) => void;
+    flush: () => void;
+    resume: () => void;
+};
+declare function createPcmPlayer(): PcmPlayerHandle;
+
+type SessionConfig = {
+    type: "session.config";
+    session_id: string;
+    audio_format: "pcm";
+    sample_rate: number;
+    brain_mode: "server" | "client";
+    turn_policy: {
+        vad_stop_secs: number;
+        vad_start_secs: number;
+        allow_interruptions: boolean;
+        eot_strategy: "vad" | "smart";
+    };
+    capabilities: {
+        server_vad: boolean;
+        client_barge: boolean;
+        client_turn_end: boolean;
+        client_say: boolean;
+        smart_eot: boolean;
+        filler: boolean;
+    };
+};
+type FillerStartedEvent = {
+    type: "filler.started";
+    id: string;
+    text: string;
+    category?: string | null;
+    duration_ms: number;
+};
+type FillerStoppedEvent = {
+    type: "filler.stopped";
+    id: string;
+};
+type FillerSkippedEvent = {
+    type: "filler.skipped";
+    reason: "tts_fast";
+    wait_ms: number;
+};
+type BrainRequestEvent = {
+    type: "brain.request";
+    transcript: string;
+    history: Array<{
+        role: string;
+        content: string;
+    }>;
+    generation_id: string;
+    session_id: string;
+    /** Original filler phrase already spoken to the user (optional). */
+    filler_prefix?: string;
+    /** Server-built prompt append; concatenate to your system prompt. */
+    system_append?: string;
+};
+type AsrPartialEvent = {
+    type: "transcript.partial";
+    text: string;
+};
+type AsrFinalEvent = {
+    type: "transcript.final";
+    text: string;
+};
+type AsrIncompleteEvent = {
+    type: "transcript.incomplete";
+    text: string;
+    wait_ms?: number;
+};
+type AsrTimingEvent = {
+    type: "transcript.timing";
+    wait_ms: number;
+};
+type TurnStartedEvent = {
+    type: "turn.started";
+};
+type TurnEndedEvent = {
+    type: "turn.ended";
+    transcript?: string;
+};
+type AssistantDelta = {
+    type: "assistant.delta";
+    text: string;
+    phase?: "main";
+    generationId?: string;
+    generation_id?: string;
+};
+type TtsStartedEvent = {
+    type: "tts.started";
+};
+type TtsStoppedEvent = {
+    type: "tts.stopped";
+    reason: "completed" | "interrupted";
+};
+type AssistantDoneEvent = {
+    type: "assistant.done";
+};
+type InterruptedEvent = {
+    type: "interrupted";
+};
+type ErrorEvent = {
+    type: "error";
+    code?: number;
+    message: string;
+};
+type FtlMetrics = {
+    total_ms: number;
+    asr_tail_ms: number | null;
+    svad_infer_ms: number | null;
+    svad_wait_ms: number | null;
+    lftl_ms: number | null;
+    tfal_ms: number | null;
+};
+type IlMetrics = {
+    total_ms: number | null;
+    vsl_ms: number;
+    aftl_ms: number | null;
+};
+type TurnMetricsEvent = {
+    type: "turn.metrics";
+    turn_id: string;
+    ftl: FtlMetrics | null;
+    il: IlMetrics | null;
+};
+type ServerEvent = AssistantDoneEvent | TurnMetricsEvent | SessionConfig | AsrPartialEvent | AsrFinalEvent | AsrIncompleteEvent | AsrTimingEvent | TurnStartedEvent | TurnEndedEvent | AssistantDelta | FillerStartedEvent | FillerStoppedEvent | FillerSkippedEvent | TtsStartedEvent | TtsStoppedEvent | InterruptedEvent | ErrorEvent | BrainRequestEvent;
+type BargeFrame = {
+    type: "barge";
+};
+type TurnEndFrame = {
+    type: "turn.end";
+    transcript?: string;
+};
+type SayFrame = {
+    type: "say";
+    text: string;
+    voice?: string;
+};
+type ClientControlFrame = BargeFrame | TurnEndFrame | SayFrame;
+type SessionState = "idle" | "listening" | "thinking" | "speaking" | "interrupted";
+type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting";
+type BrainDeltaFrame = {
+    type: "brain.delta";
+    text: string;
+    generation_id: string;
+};
+type BrainDoneFrame = {
+    type: "brain.done";
+    generation_id: string;
+};
+type BrainErrorFrame = {
+    type: "brain.error";
+    message: string;
+    generation_id: string;
+};
+type TtsOptions = {
+    /** 音色 ID，例如 "zh_male_yuanboxiaoshu_uranus_bigtts" */
+    speaker?: string;
+    /** 语速，范围 -50~100（100 = 2倍速，-50 = 0.5倍速） */
+    speech_rate?: number;
+    /** 音量，范围 -50~100（100 = 2倍音量，-50 = 0.5倍音量） */
+    loudness_rate?: number;
+    /**
+     * 方言。目前仅 zh_female_vv_uranus_bigtts 音色支持，可选值：
+     * - "dongbei"  东北话
+     * - "shaanxi"  陕西话
+     * - "sichuan"  四川话
+     */
+    explicit_dialect?: "dongbei" | "shaanxi" | "sichuan";
+    /**
+     * 语音指令/情绪引导，传入参考文本让模型按指定风格合成，
+     * 例如 ["用特别特别痛心的语气说话"]
+     */
+    context_texts?: string[];
+};
+type TurnPolicy = {
+    /** 连接后立即播报的欢迎语，传空字符串可禁用服务端默认欢迎语 */
+    welcome_text?: string;
+    /** 是否启用垫词，默认 true（仅 doubao TTS 后端生效） */
+    filler_enabled?: boolean;
+    tts_options?: TtsOptions;
+};
+type CreateSessionRequest = {
+    turn_policy?: TurnPolicy;
+    app_context?: Record<string, unknown>;
+    brain_mode?: "server" | "client";
+};
+type CreateSessionResponse = {
+    session_id: string;
+    session_token: string;
+    policy_profile: Record<string, unknown>;
+};
+
+type Utterance = {
+    role: "user" | "assistant";
+    text: string;
+    partial?: boolean;
+    incomplete?: boolean;
+    fillerPrefix?: string;
+    waitTimes?: number[];
+};
+type TurnMetricsSummary = {
+    turn_id: string;
+    ftl: FtlMetrics | null;
+    il: IlMetrics | null;
+    ts: number;
+};
+type VoiceSessionState = {
+    connection: ConnectionState;
+    session: SessionState;
+    utterances: Utterance[];
+    volume: number;
+    error: string | null;
+    latency: {
+        current: TurnMetricsSummary | null;
+        history: TurnMetricsSummary[];
+    };
+};
+declare function createInitialState(): VoiceSessionState;
+
+type EventMap = {
+    state: (s: VoiceSessionState) => void;
+    log: (e: LogEntry) => void;
+};
+declare class TypedEmitter {
+    private _listeners;
+    on<K extends keyof EventMap>(event: K, fn: EventMap[K]): this;
+    off<K extends keyof EventMap>(event: K, fn: EventMap[K]): this;
+    protected emit<K extends keyof EventMap>(event: K, ...args: Parameters<EventMap[K]>): void;
+}
+type BrainSendFrame = (frame: BrainDeltaFrame | BrainDoneFrame | BrainErrorFrame) => void;
+type VoiceLoopClientOptions = {
+    serverUrl?: string;
+    apiKey?: string;
+    /** 话轮策略与 TTS 参数，含垫词、打断、EoT、音色、语速等。 */
+    turnPolicy?: TurnPolicy;
+    /** Called when the server delegates an LLM request to the client. */
+    onBrainRequest?: (evt: BrainRequestEvent, sendFrame: BrainSendFrame) => void | Promise<void>;
+    /** Inject custom microphone capture (useful for testing). */
+    micCapture?: (onPcm: (chunk: ArrayBuffer) => void) => Promise<AudioCaptureHandle>;
+    /** Inject custom PCM player factory (useful for testing). */
+    playerFactory?: () => PcmPlayerHandle;
+};
+declare class VoiceLoopClient extends TypedEmitter {
+    private _state;
+    private _ctx;
+    private _ws;
+    private _mic;
+    private _player;
+    private _volTimer;
+    private readonly _serverUrl;
+    private readonly _apiKey;
+    private readonly _turnPolicy;
+    private readonly _onBrainRequest;
+    private readonly _micCapture;
+    constructor(opts?: VoiceLoopClientOptions);
+    get state(): VoiceSessionState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    barge(): void;
+    endTurn(transcript?: string): void;
+    say(text: string, voice?: string): void;
+    private _send;
+    private _handleEvent;
+    private _applyPatch;
+    private _cleanup;
+}
+
+type StateMachineContext = {
+    assistantBubbleOpen: boolean;
+    userTurnActive: boolean;
+    incompleteAccum: string;
+    hasIncompleteUserTurn: boolean;
+    preLLMText: string;
+};
+declare function createStateMachineContext(): StateMachineContext;
+type SideEffect = {
+    kind: "flush_player";
+};
+type ReduceResult = {
+    state: VoiceSessionState;
+    ctx: StateMachineContext;
+    effects: SideEffect[];
+};
+declare function reduceServerEvent(state: VoiceSessionState, ctx: StateMachineContext, evt: ServerEvent): ReduceResult;
+
+export { type AsrFinalEvent, type AsrIncompleteEvent, type AsrPartialEvent, type AsrTimingEvent, type AssistantDelta, type AssistantDoneEvent, type AudioCaptureHandle, type BargeFrame, type BrainDeltaFrame, type BrainDoneFrame, type BrainErrorFrame, type BrainRequestEvent, type BrainSendFrame, type ClientControlFrame, type ConnectionState, type CreateSessionRequest, type CreateSessionResponse, type ErrorEvent, type FillerSkippedEvent, type FillerStartedEvent, type FillerStoppedEvent, type FtlMetrics, type IlMetrics, type InterruptedEvent, type LogEntry, type LogLevel, MIC_SAMPLE_RATE, type PcmPlayerHandle, type ReduceResult, type SayFrame, type ServerEvent, type SessionConfig, type SessionState, type SideEffect, type StateMachineContext, TTS_SAMPLE_RATE, type TtsOptions, type TtsStartedEvent, type TtsStoppedEvent, type TurnEndFrame, type TurnEndedEvent, type TurnMetricsEvent, type TurnMetricsSummary, type TurnPolicy, type TurnStartedEvent, type Utterance, VoiceLoopClient, type VoiceLoopClientOptions, type VoiceSessionState, clearLog, createInitialState, createPcmPlayer, createStateMachineContext, formatForCopy, getEntries, log, logError, reduceServerEvent, startMicCapture, subscribe, warn };