终极指南：如何用annyang.js与语音合成API打造全双工语音交互体验

【免费下载链接】annyang TalAter/annyang: 是一个用于语音识别的 JavaScript 库。适合在网页中添加语音识别功能。特点是提供了简单的 API，支持多种语音识别引擎，并且可以自定义识别语言和行为。 项目地址: https://gitcode.com/gh_mirrors/an/annyang

在当今Web开发领域，语音交互正成为提升用户体验的关键技术。annyang.js作为一款轻量级JavaScript语音识别库，让开发者能够轻松为网页添加语音控制功能。本指南将带你从零开始，掌握如何使用annyang.js构建响应迅速、交互自然的语音应用，无需深厚的语音技术背景。

一、认识annyang.js：让网页听懂你的指令 🎤

annyang.js是一个开源的JavaScript库，它将复杂的语音识别技术封装成简单API，使开发者能够在网页中快速实现语音命令识别。其核心优势在于：

• 零依赖：无需额外安装插件或框架
• 轻量级：核心文件仅10KB左右
• 多语言支持：默认支持50+种语言
• 高度可定制：支持自定义命令和回调函数

项目的核心代码位于src/annyang.js，通过简单的API调用即可激活语音识别功能。

二、5分钟快速上手：annyang.js基础用法 ⚡

2.1 引入库文件

首先需要在HTML中引入annyang.js。你可以直接使用demo目录中的demo/annyang.min.js文件：

<script src="annyang.min.js"></script>

2.2 初始化与添加命令

基本使用只需三步：初始化、定义命令、启动监听：

// 检查浏览器支持
if (annyang) {
  // 定义语音命令
  const commands = {
    'hello': () => alert('Hello there!'),
    'open *page': (page) => window.location.href = `/${page}`,
    'search for *query': (query) => window.location.href = `https://example.com/search?q=${query}`
  };

  // 添加命令
  annyang.addCommands(commands);
  
  // 开始监听
  annyang.start();
}

2.3 核心API解析

annyang提供了简洁的API接口，主要包括：

• annyang.addCommands(commands)：添加语音命令
• annyang.start()：开始语音识别
• annyang.stop()：停止语音识别
• annyang.pause()：暂停识别

这些方法在src/annyang.js中定义，代码简洁易读，适合新手理解语音识别的工作流程。

三、打造全双工交互：语音识别+语音合成 🗣️🔊

全双工语音交互需要结合语音识别（用户输入）和语音合成（程序输出）。以下是实现方案：

3.1 集成Web Speech API

现代浏览器原生支持Web Speech API，可与annyang.js配合使用：

// 语音合成函数
const speak = (text) => {
  const utterance = new SpeechSynthesisUtterance(text);
  utterance.lang = 'zh-CN';
  window.speechSynthesis.speak(utterance);
};

// 结合annyang使用
const commands = {
  '你好': () => speak('你好！有什么可以帮助你的吗？'),
  '今天天气怎么样': () => {
    // 调用天气API获取数据
    speak('今天天气晴朗，气温25度');
  }
};

annyang.addCommands(commands);
annyang.start();

3.2 实现对话流程控制

通过状态管理实现多轮对话：

let conversationState = 'idle';

const commands = {
  '创建新任务': () => {
    conversationState = 'task_name';
    speak('请说出任务名称');
  },
  '*task': (task) => {
    if (conversationState === 'task_name') {
      saveTask(task);
      conversationState = 'idle';
      speak(`已创建任务：${task}`);
    }
  }
};

四、实战案例：构建语音控制的待办事项应用 📝

4.1 项目结构

推荐的项目文件结构：

project/
├── index.html       # 主页面
├── annyang.min.js   # 语音识别库
├── app.js           # 应用逻辑
└── styles.css       # 样式文件

4.2 核心功能实现

以下是实现语音控制待办事项的关键代码：

// app.js
document.addEventListener('DOMContentLoaded', () => {
  if (!annyang) {
    alert('您的浏览器不支持语音识别');
    return;
  }

  const taskList = document.getElementById('task-list');
  
  // 定义命令
  const commands = {
    '添加任务 *task': (task) => {
      addTask(task);
      speak(`已添加任务：${task}`);
    },
    '删除任务 *number': (number) => {
      removeTask(number - 1); // 转成0-based索引
      speak(`已删除第${number}个任务`);
    },
    '列出所有任务': () => {
      const tasks = getTasks();
      if (tasks.length === 0) {
        speak('没有任务');
        return;
      }
      speak(`共有${tasks.length}个任务：${tasks.join('，')}`);
    }
  };

  annyang.addCommands(commands);
  
  // 启动语音识别
  document.getElementById('start-btn').addEventListener('click', () => {
    annyang.start();
    speak('语音控制已启动');
  });
});

4.3 界面设计建议

为语音应用设计友好的用户界面：

• 添加语音活动指示器
• 显示命令提示列表
• 提供语音反馈的视觉提示
• 支持键盘备用输入方式

适合语音应用的背景设计，营造科技感与交互氛围

五、高级技巧与最佳实践 🌟

5.1 提高识别准确率

• 使用特定词汇：限制命令词汇范围
• 添加同义词：为同一命令提供多种表达方式
• 上下文提示：根据应用状态动态调整命令集

5.2 处理识别错误

annyang.addCallback('error', (err) => {
  console.error('识别错误:', err);
  speak('抱歉，我没听清楚，请再说一遍');
});

annyang.addCallback('noMatch', () => {
  speak('抱歉，我不理解这个命令');
});

5.3 性能优化

• 不需要时调用annyang.pause()暂停识别
• 使用命令优先级避免冲突
• 长对话中定期重启识别以保持准确性

六、常见问题与解决方案 ❓

6.1 浏览器兼容性

annyang.js依赖Web Speech API，目前支持Chrome、Edge和部分移动浏览器。可在docs/FAQ.md中查看完整的浏览器支持列表。

6.2 本地开发问题

如果在本地文件系统运行时遇到权限问题，可通过搭建本地服务器解决：

git clone https://gitcode.com/gh_mirrors/an/annyang
cd annyang
npx serve

6.3 语音合成语言设置

// 设置中文语音
const utterance = new SpeechSynthesisUtterance('你好');
utterance.lang = 'zh-CN';
// 选择特定语音
const voices = window.speechSynthesis.getVoices();
utterance.voice = voices.find(voice => voice.lang === 'zh-CN');

七、总结与扩展学习

通过本指南，你已经掌握了使用annyang.js构建语音交互应用的核心技能。这只是开始，你还可以：

• 探索test/spec/目录中的测试用例，了解更多API用法
• 查阅docs/README.md获取完整API文档
• 参与项目贡献，提交改进建议到CONTRIBUTING.md

语音交互正在改变用户与Web应用的交互方式，掌握这一技能将为你的项目带来独特优势。现在就开始构建你的第一个语音应用吧！ 🚀

【免费下载链接】annyang TalAter/annyang: 是一个用于语音识别的 JavaScript 库。适合在网页中添加语音识别功能。特点是提供了简单的 API，支持多种语音识别引擎，并且可以自定义识别语言和行为。 项目地址: https://gitcode.com/gh_mirrors/an/annyang