@mingto/huoshan-lat

火山引擎实时语音识别（ASR）工具库，专为浏览器端设计，支持流式音频处理、智能语音监听与自动结束控制。

特性

• 🎤 流式识别：支持实时音频流输入，边录制边识别
• 👂 智能监听：自动检测语音音量，音量超过阈值自动开始识别
• 🌍 多语言支持：支持中文、英文及多种方言
• 🔧 丰富配置：支持采样率、位深度、声道数、标点、ITN 等多种配置
• ⏱️ 智能延迟控制：支持首段延迟和后续延迟的自动/手动控制
• 🎯 事件驱动：基于事件总线架构，提供实时识别结果和最终结果回调
• 📦 TypeScript 支持：完整的类型定义与类型推导
• 🔄 自动重连：监听模式下识别结束自动恢复监听
• 🎛️ 音频预处理：内置音频处理器与分片机制
• 🚀 Web Worker 优化：音频处理在 Worker 中执行，不阻塞主线程

安装

# npm
npm install @mingto/huoshan-lat

# yarn
yarn add @mingto/huoshan-lat

# pnpm (推荐)
pnpm add @mingto/huoshan-lat

快速开始

import huoshanLAT from '@mingto/huoshan-lat'

// 1. 配置系统参数（只需配置一次）
huoshanLAT.config({
  latRequestBaseUrl: 'wss://audio.workbrain.cn/asr',
})

// 2. 创建语音识别控制器实例
const lat = huoshanLAT.create({
  sample_rate: 16000,
  bits: 16,
  channels: 1,
  format: 'raw',
  codec: 'raw',
  enable_itn: true,    // 启用文本规范化
  enable_punc: true,   // 启用标点
  enable_ddc: true,    // 启用顺滑
}, {
  autoControl: true,
  initialDelay: 3500,
  subsequentDelay: 3000,
})

// 3. 监听事件
lat
  .on('appResponseText', (text) => {
    console.log('实时识别中:', text)
  })
  .on('appResultText', (text) => {
    console.log('最终识别结果:', text)
  })
  .on('appFinish', () => {
    console.log('识别结束')
  })

// 4. 开始识别（人工控制）
lat.start()

// 或：启用智能语音监听（自动检测声音开始）
// lat.watch()

// 5. 结束识别（手动控制模式下）
// lat.finish()

API 文档

配置系统参数

huoshanLAT.config(systemConfig)

配置系统参数，全局只需配置一次。

huoshanLAT.config({
  latRequestBaseUrl: 'wss://audio.workbrain.cn/asr',
})

参数说明：

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | latRequestBaseUrl | string | ✅ | wss://audio.workbrain.cn/asr | ASR 服务 WebSocket 地址 |

创建实例

huoshanLAT.create(businessParams?, sectionDelayParams?)

创建语音识别控制器实例。

const lat = huoshanLAT.create({
  sample_rate: 16000,
  bits: 16,
  channels: 1,
  format: 'raw',
  codec: 'raw',
  enable_itn: true,
  enable_punc: true,
  enable_ddc: true,
}, {
  autoControl: true,
  initialDelay: 3500,
  subsequentDelay: 3000,
})

业务参数 businessParams:

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | sample_rate | number | ❌ | 16000 | 采样率，一般为 16000 | | bits | number | ❌ | 16 | 位深度，一般为 16 | | channels | number | ❌ | 1 | 声道数，一般为 1（单声道） | | format | string | ❌ | 'raw' | 音频格式，raw 或 wav，浏览器录音一般为 raw | | codec | string | ❌ | 'raw' | 编码格式 | | enable_itn | boolean | ❌ | true | 是否启用 ITN（文本规范化） | | enable_punc | boolean | ❌ | true | 是否启用标点符号 | | enable_ddc | boolean | ❌ | true | 是否启用顺滑处理 |

分段延迟参数 sectionDelayParams:

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | autoControl | boolean | ❌ | true | 是否自动控制结束 | | initialDelay | number | ❌ | 3500 | 首次延迟时间（毫秒） | | subsequentDelay | number | ❌ | 3000 | 后续延迟时间（毫秒） |

实例方法

lat.start()

激活应用，使处理器进入工作状态，开始录制音频并识别。

lat.start()

lat.watch()

启用智能语音监听模式。监听浏览器音频输入，当检测到音量大于 20% 且系统处于离线状态时自动启动录音和识别。识别结束后会自动恢复监听状态。

lat.watch()

音量阈值说明： 20% 为经验值，适合大多数安静环境下的语音检测场景。

lat.finish()

停止所有处理器，重置应用状态，触发 appFinish 事件。如果在监听模式下，停止识别后会自动重新进入监听状态。

lat.finish()

lat.on(eventName, callback)

监听事件，支持链式调用。

lat
  .on('appResponseText', (text) => {
    console.log('实时识别:', text)
  })
  .on('appResultText', (text) => {
    console.log('最终结果:', text)
  })
  .on('appFinish', () => {
    console.log('识别结束')
  })

事件说明

| 事件名 | 触发时机 | 回调参数 | 说明 | |--------|----------|----------|------| | appResponseText | 实时识别过程中，有新的识别片段时 | string | 返回当前识别的文本片段 | | appResultText | 完整识别结果可用时 | string | 返回完整的识别文本 | | appFinish | 应用结束时（调用 finish() 或自动结束） | - | 所有处理器已停止 |

使用示例

基础手动控制模式

import huoshanLAT from '@mingto/huoshan-lat'

huoshanLAT.config()

const lat = huoshanLAT.create({
  enable_punc: true,
  enable_itn: true,
}, {
  autoControl: false,  // 关闭自动控制，手动调用 finish()
})

lat
  .on('appResponseText', (text) => {
    console.log('实时:', text)
  })
  .on('appResultText', (text) => {
    console.log('最终:', text)
  })
  .on('appFinish', () => {
    console.log('结束')
  })

// 开始识别
lat.start()

// 5 秒后结束
setTimeout(() => {
  lat.finish()
}, 5000)

智能监听模式（推荐）

import huoshanLAT from '@mingto/huoshan-lat'

huoshanLAT.config()

const lat = huoshanLAT.create({
  enable_punc: true,
  enable_itn: true,
}, {
  autoControl: true,
  initialDelay: 3500,
  subsequentDelay: 3000,
})

lat
  .on('appResponseText', (text) => {
    // 更新 UI 显示实时识别结果
    document.getElementById('realtime-text').innerText = text
  })
  .on('appResultText', (text) => {
    // 保存最终结果
    console.log('用户说了:', text)
  })
  .on('appFinish', () => {
    // 识别结束，系统会自动重新监听
    console.log('已完成，等待下一次语音输入')
  })

// 启用监听模式
lat.watch()

// 用户开始说话 → 20% 音量阈值触发 → 自动开始识别
// 说话结束 → 静音检测触发自动结束 → 返回最终结果 → 自动恢复监听

在 React 中使用

import { useState, useEffect, useRef } from 'react'
import huoshanLAT from '@mingto/huoshan-lat'

const VoiceInput = () => {
  const [realtimeText, setRealtimeText] = useState('')
  const [finalText, setFinalText] = useState('')
  const [isListening, setIsListening] = useState(false)
  const latRef = useRef(null)

  useEffect(() => {
    huoshanLAT.config()

    latRef.current = huoshanLAT.create(
      {
        enable_punc: true,
        enable_itn: true,
      },
      {
        autoControl: true,
        initialDelay: 3500,
        subsequentDelay: 3000,
      }
    )

    latRef.current
      .on('appResponseText', (text) => {
        setRealtimeText(text)
      })
      .on('appResultText', (text) => {
        setFinalText(text)
        setRealtimeText('')
      })
      .on('appFinish', () => {
        setIsListening(false)
      })

    return () => {
      latRef.current?.finish()
    }
  }, [])

  const handleStart = () => {
    setIsListening(true)
    latRef.current?.watch()
  }

  const handleStop = () => {
    latRef.current?.finish()
    setIsListening(false)
  }

  return (
    <div>
      <div>
        <strong>实时识别:</strong> {realtimeText}
      </div>
      <div>
        <strong>最终结果:</strong> {finalText}
      </div>
      <button onClick={handleStart} disabled={isListening}>
        开始监听
      </button>
      <button onClick={handleStop} disabled={!isListening}>
        停止
      </button>
    </div>
  )
}

export default VoiceInput

结合打字机效果显示

import huoshanLAT from '@mingto/huoshan-lat'
import { createTypeWriter } from '@mingto/type-writer'

// 创建打字机实例
const typeWriter = createTypeWriter({ speed: 50 })

typeWriter.on('change', (text) => {
  document.getElementById('display-text').innerText = text
})

// 配置语音识别
huoshanLAT.config()

const lat = huoshanLAT.create()

lat
  .on('appResultText', (text) => {
    // 用打字机效果显示最终结果
    typeWriter.send(text)
  })

lat.watch()

内部处理流程

工具库采用链式处理器架构，按以下顺序处理音频数据：

录音采集（RecordActuator）
    ↓
音频处理（ProcessorAudio）
    ↓
音频分片（SplitAudio）
    ↓
发送请求（LatRequest）
    ↓
接收结果 → 触发事件

处理流程说明：

1. 录音采集：调用浏览器录音 API 捕获音频流
2. 音频处理：对音频数据进行预处理
3. 音频分片：按照设置的分片规则切割音频
4. 发送请求：通过 WebSocket 发送到 ASR 服务器
5. 结果接收：接收并解析识别结果，触发相应事件

系统状态说明

| 状态 | 值 | 说明 | |------|----|------| | OFFLINE | 'offline' | 离线状态，未在录音或识别 | | EXECUTE | 'execute' | 执行中状态，正在录音和识别 |

浏览器兼容性

| 浏览器 | 版本要求 | 兼容性 | |--------|----------|--------| | Chrome | 55+ | ✅ 完全支持 | | Firefox | 44+ | ✅ 完全支持 | | Safari | 11+ | ✅ 完全支持 | | Edge | 79+ | ✅ 完全支持 | | 微信浏览器 | 最新版 | ✅ 完全支持 |

💡 注意：必须在 HTTPS 或 localhost 环境下才能调用麦克风权限

注意事项

1. ⚠️ HTTPS 要求：浏览器录音功能需要 HTTPS 环境或 localhost
2. ⚠️ 麦克风权限：首次使用会弹出麦克风授权请求，必须用户允许
3. ⚠️ 配置顺序：必须先调用 config() 再调用 create()
4. ⚠️ 监听模式：watch() 模式下检测到音量 > 20% 自动开始识别
5. ⚠️ 自动结束：autoControl: true 时，静音达到延迟时间自动结束
6. ⚠️ 内存管理：页面卸载或组件销毁时，务必调用 finish() 释放资源
7. ⚠️ 音频格式：浏览器录音通常是 raw 格式，采样率建议 16000Hz
8. ⚠️ Worker 支持：音频处理在 Web Worker 中进行，需确保环境支持

常见问题

Q: 为什么没有声音反馈？ A: 请检查麦克风权限是否已授权，当前页面是否在 HTTPS 环境下。

Q: 识别准确率如何提升？ A: 可以调整以下参数：

• 确保录音环境安静
• 使用高质量麦克风
• 根据实际场景调整 initialDelay 和 subsequentDelay

Q: 监听模式下偶尔不触发？ A: 20% 音量阈值是经验值，特殊环境可能需要微调，也可以直接手动控制。

Q: 支持长时间语音识别吗？ A: 支持，但建议长语音分段处理，避免内存占用过高。

许可证

MIT