import { TranscriptionRequest, TranscriptionResult, TranscriptionStreamRequest, TranscriptionEvent, SynthesisRequest, SynthesisResult, SynthesisStreamRequest, SynthesisEvent } from '../browser.js'; import '@h-ai/core'; /** * @h-ai/ai/client — 浏览器语音客户端 * * 通过统一 WebSocket 连接 `@h-ai/serv` 的语音入口,向浏览器暴露与 Node 端一致的 * `ai.audio.*` 业务 API。WebSocket 建立、消息编解码等传输细节在此内部完成, * 调用方不接触任何厂商原生事件。 * @module client/ai-audio-client */ /** * getTicket 收到的当前 Audio 请求摘要 * * 供应用签发与本次操作严格绑定的能力票据(如 `iam.ticket.issue({ grant })`), * 使票据只能用于本次操作 / 模型 / 会话,降低票据被重放的风险。 * * @example * ```ts * import type { AudioTicketRequest } from '@h-ai/ai/client' * function grant(request: AudioTicketRequest) { * return { operation: request.operation, model: request.model } // 经已登录 HTTP 接口签发并在服务端原子消费。 * } * ``` */ interface AudioTicketRequest { /** 本次操作类型 */ operation: 'transcribe' | 'synthesize'; /** 本次使用的模型 ID(如有指定) */ model?: string; } /** * 浏览器语音客户端配置 * * @example * ```ts * import { createAudioClient } from '@h-ai/ai/client' * import type { AudioTicketRequest } from '@h-ai/ai/client' * function connect(issueTicket: (request: AudioTicketRequest) => Promise) { * return createAudioClient({ url: 'wss://example.com/api/v1/ai/audio', getTicket: issueTicket }) * } * ``` */ interface AudioClientConfig { /** 语音 WebSocket 完整 URL(如 `wss://host/api/v1/ai/audio`) */ url: string; /** * 获取短期、一次性的 Audio WebSocket ticket * * ticket 应由已登录 HTTP 请求签发,并在服务端首次校验时原子消费。 * 收到当前请求摘要(operation / model),可签发与本次操作严格绑定的票据。 */ getTicket: (request: AudioTicketRequest) => string | Promise; } /** * 浏览器语音操作接口 * * 与 Node 端 `AudioOperations` 业务形态一致;出错时抛出异常(浏览器 Client 约定)。 * * @example * ```ts * import type { AudioClientOperations } from '@h-ai/ai/client' * async function speak(audio: AudioClientOperations) { * // 浏览器 AudioClient 普通方法也显式抛错,由应用交互边界处理。 * const result = await audio.synthesize({ text: '你好', format: 'mp3' }) * return result.data * } * ``` */ interface AudioClientOperations { /** 将完整音频识别为完整文本 */ transcribe: (request: TranscriptionRequest) => Promise; /** 持续输入音频或增量返回识别文本(含语音起止事件) */ transcribeStream: (request: TranscriptionStreamRequest) => AsyncIterable; /** 将完整文本合成为完整音频 */ synthesize: (request: SynthesisRequest) => Promise; /** 持续输入文本段并按段输出结构化音频事件 */ synthesizeStream: (request: SynthesisStreamRequest) => AsyncIterable; } /** * 创建浏览器语音客户端 * * @param config - 语音客户端配置 * @returns 浏览器语音操作接口 * * @example * ```ts * import { createAudioClient } from '@h-ai/ai/client' * import type { AudioTicketRequest } from '@h-ai/ai/client' * function connect(issueTicket: (request: AudioTicketRequest) => Promise) { * return createAudioClient({ url: 'wss://example.com/api/v1/ai/audio', getTicket: issueTicket }) * } * ``` */ declare function createAudioClient(config: AudioClientConfig): AudioClientOperations; /** * 麦克风会话选项。应用通过回调决定何时转写和保存录音。 * @example * ```ts * import type { AudioRecorderOptions } from '@h-ai/ai/client' * const options: AudioRecorderOptions = { maxDurationSeconds: 30, onStop: blob => void blob.size } * ``` */ interface AudioRecorderOptions { /** 请求麦克风时使用的音轨约束,默认 true。 */ audio?: MediaTrackConstraints | true; /** MediaRecorder 的编码选项。 */ encoding?: MediaRecorderOptions; /** 分段间隔,毫秒,默认 250。 */ timesliceMs?: number; /** 达到录音时长上限后停止并发布最后一段数据。 */ maxDurationSeconds?: number; /** 超过编码字节上限时中止并调用 onError。 */ maxInputBytes?: number; /** 正常停止后的完整录音。 */ onStop: (recording: Blob) => void; /** 录音开始后发生的编码或容量错误。 */ onError?: (error: Error) => void; } /** * 浏览器麦克风会话。 * @example * ```ts * import { createAudioRecorder } from '@h-ai/ai/client' * const recorder = createAudioRecorder({ onStop: blob => void blob.size }) * recorder.close() * ``` */ interface AudioRecorder { /** 请求麦克风并开始录音,权限、设备和配置失败时 reject。 */ start: () => Promise; /** 正常停止,最终数据随后由 onStop 发布。 */ stop: () => void; /** 返回已经收到的录音分段,不改变录音状态。 */ snapshot: () => Blob; /** 放弃本次录音及未完成的麦克风申请,释放已有轨道。 */ close: () => void; } /** * 创建独立的浏览器麦克风会话,故读取权限及编码状态不依赖 AI 服务。 * @param options - 录音约束、会话上限和结果回调 * @returns 可开始、快照、停止或释放的会话实例 * @throws 上限或分段间隔无效时抛出 RangeError * @example * ```ts * import { createAudioRecorder } from '@h-ai/ai/client' * async function record() { * const recorder = createAudioRecorder({ onStop: blob => void blob.size }) * await recorder.start() * return recorder * } * ``` */ declare function createAudioRecorder(options: AudioRecorderOptions): AudioRecorder; /** * 浏览器端 WAV 编码工具 * * MediaRecorder 通常输出 webm/opus,而多数 ASR 服务(如 MiMo)仅接受 wav/mp3, * 故录音快照先用 Web Audio API 解码,再重采样为单声道并编码为 16bit PCM WAV。 * 所有 API 均为浏览器专用(AudioContext / OfflineAudioContext),仅在客户端调用。 * @module audio/wav */ /** * WAV 转换的目标格式和处理上限。 * @example * ```ts * import type { AudioWavOptions } from '@h-ai/ai/client' * const options: AudioWavOptions = { maxInputBytes: 1024 * 1024, maxDurationSeconds: 30, overflow: 'truncate' } * ``` */ interface AudioWavOptions { /** 输出采样率,单位 Hz,默认 16000。 */ sampleRate?: number; /** 解码前允许的 Blob 最大字节数。 */ maxInputBytes?: number; /** 输出 PCM 的最长秒数,在解码后、重采样前检查。 */ maxDurationSeconds?: number; /** 超过最长秒数时默认拒绝,设为 truncate 时保留开头。 */ overflow?: 'reject' | 'truncate'; } /** * 将任意浏览器可解码的音频 Blob(如 MediaRecorder 的 webm)转换为单声道 16bit PCM WAV。 * * @param blob - 录制得到的原始音频 * @param options - 目标采样率(兼容旧调用)或含转换上限的配置 * @throws 配置无效、输入超限、解码失败或超时长且未指定截断时抛错 * @returns `audio/wav` 类型的 Blob * @example * ```ts * import { blobToWav } from '@h-ai/ai/client' * async function prepareRecording(recording: Blob) { * const wav = await blobToWav(recording) * return new File([wav], 'recording.wav', { type: wav.type }) * } * ``` */ declare function blobToWav(blob: Blob, options?: number | AudioWavOptions): Promise; export { blobToWav, createAudioClient, createAudioRecorder }; export type { AudioClientConfig, AudioClientOperations, AudioRecorder, AudioRecorderOptions, AudioTicketRequest, AudioWavOptions };