ms-vite-plugin 1.1.1 → 1.1.3

package/docs/api/tts.md

@@ -0,0 +1,334 @@
+# TTS 模块 (Text-to-Speech)
+
+TTS（文本转语音）模块提供了语音合成、播放控制等功能，支持多种语言和语音设置。
+
+## 接口定义
+
+### VoiceInfo - 语音信息接口
+
+```typescript
+interface VoiceInfo {
+  /** 语音标识符 */
+  identifier: string;
+  /** 语音名称 */
+  name: string;
+  /** 语言代码 */
+  language: string;
+  /** 语音质量等级 */
+  quality: number;
+}
+```
+
+**属性说明：**
+
+| 属性名       | 类型   | 描述                                      |
+| ------------ | ------ | ----------------------------------------- |
+| `identifier` | string | 语音的唯一标识符，用于设置特定语音        |
+| `name`       | string | 语音的显示名称                            |
+| `language`   | string | 语音支持的语言代码（如 "zh-CN", "en-US"） |
+| `quality`    | number | 语音质量等级，数值越高质量越好            |
+
+## 语音播放
+
+### speak - 播放文本转语音
+
+#### 完整参数版本
+
+```typescript
+function speak(
+  text: string,
+  rate?: number,
+  pitch?: number,
+  volume?: number,
+  language?: string
+): boolean;
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值  | 描述                         |
+| ---------- | ------ | -------- | ------- | ---------------------------- |
+| `text`     | string | 是       |         | 要转换为语音的文本内容       |
+| `rate`     | number | 否       | 0.5     | 语速，范围 0.0-1.0，默认 0.5 |
+| `pitch`    | number | 否       | 1.0     | 音调，范围 0.5-2.0，默认 1.0 |
+| `volume`   | number | 否       | 1.0     | 音量，范围 0.0-1.0，默认 1.0 |
+| `language` | string | 否       | "zh-CN" | 语言代码，默认 "zh-CN"       |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 是否成功开始播放 |
+
+**示例：**
+
+```javascript
+// 使用简化参数播放中文文本
+tts.speak("欢迎使用 TTS 功能");
+
+// 使用完整参数播放中文语音
+const success = tts.speak("你好世界", 0.5, 1.0, 1.0, "zh-CN");
+if (success) {
+  logi("语音播放成功");
+}
+
+// 播放英文语音，调整语速和音调
+tts.speak("Hello World", 0.7, 1.2, 0.8, "en-US");
+
+// 慢速播放，低音调
+tts.speak("这是一段慢速语音", 0.3, 0.8, 1.0, "zh-CN");
+
+// 快速播放，高音调
+tts.speak("这是一段快速语音", 0.9, 1.5, 1.0, "zh-CN");
+```
+
+## 播放控制
+
+### waitEnd - 等待播放完成
+
+```typescript
+function waitEnd(): void;
+```
+
+**说明：**
+
+- 调用 `waitEnd()` 会阻塞当前线程，直到当前播放的语音完成。
+- 通常在需要确保语音播放完成后再执行后续操作时使用。
+
+**示例：**
+
+```javascript
+// 播放一段文本
+tts.speak("这是一段需要等待播放完成的文本");
+
+// 等待播放完成
+tts.waitEnd();
+
+logi("语音播放完成");
+```
+
+### stop - 停止播放
+
+```typescript
+function stop(): void;
+```
+
+停止当前正在播放的语音。
+
+**示例：**
+
+```javascript
+// 开始播放
+tts.speak("这是一段很长的文本内容...");
+
+// 在某个条件下停止播放
+if (shouldStop) {
+  tts.stop();
+  logi("语音播放已停止");
+}
+```
+
+### isSpeaking - 检查播放状态
+
+```typescript
+function isSpeaking(): boolean;
+```
+
+检查当前是否正在播放语音。
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否正在播放 |
+
+**示例：**
+
+```javascript
+// 检查播放状态
+if (tts.isSpeaking()) {
+  logi("正在播放语音");
+} else {
+  logi("当前没有播放语音");
+}
+
+// 等待播放完成
+while (tts.isSpeaking()) {
+  sleep(100); // 等待 100ms
+}
+logi("语音播放完成");
+```
+
+## 语音设置
+
+### getAvailableVoices - 获取可用语音列表
+
+```typescript
+function getAvailableVoices(): VoiceInfo[];
+```
+
+获取系统中所有可用的语音信息。
+
+**返回值：**
+
+| 类型          | 描述         |
+| ------------- | ------------ |
+| `VoiceInfo[]` | 语音信息数组 |
+
+**示例：**
+
+```javascript
+// 获取并显示所有可用语音
+const voices = tts.getAvailableVoices();
+logi(`找到 ${voices.length} 个可用语音：`);
+
+voices.forEach((voice, index) => {
+  logi(`${index + 1}. 名称: ${voice.name}`);
+  logi(`   语言: ${voice.language}`);
+  logi(`   标识符: ${voice.identifier}`);
+  logi(`   质量: ${voice.quality}`);
+  logi("---");
+});
+
+// 筛选中文语音
+const chineseVoices = voices.filter((voice) => voice.language.startsWith("zh"));
+logi(`找到 ${chineseVoices.length} 个中文语音`);
+
+// 筛选英文语音
+const englishVoices = voices.filter((voice) => voice.language.startsWith("en"));
+logi(`找到 ${englishVoices.length} 个英文语音`);
+```
+
+### setVoice - 设置语音
+
+```typescript
+function setVoice(voiceIdentifier: string): boolean;
+```
+
+设置要使用的语音。
+
+**参数说明：**
+
+| 参数名            | 类型   | 是否必填 | 默认值 | 描述                                         |
+| ----------------- | ------ | -------- | ------ | -------------------------------------------- |
+| `voiceIdentifier` | string | 是       |        | 语音标识符，可从 `getAvailableVoices()` 获取 |
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否设置成功 |
+
+**示例：**
+
+```javascript
+// 获取可用语音并设置第一个中文语音
+const voices = tts.getAvailableVoices();
+const chineseVoice = voices.find((voice) => voice.language.startsWith("zh"));
+
+if (chineseVoice) {
+  const success = tts.setVoice(chineseVoice.identifier);
+  if (success) {
+    logi(`成功设置语音: ${chineseVoice.name}`);
+    tts.speak("语音设置成功");
+  } else {
+    loge("语音设置失败");
+  }
+}
+
+// 设置特定的系统语音
+const success = tts.setVoice("com.apple.ttsbundle.Samantha-compact");
+if (success) {
+  logi("成功设置为 Samantha 语音");
+  tts.speak("Hello, I am Samantha");
+}
+```
+
+## 资源管理
+
+### free - 释放 TTS 资源
+
+```typescript
+function free(): void;
+```
+
+`speak`方法调用时，会自动初始化 TTS 模块并在内存缓存，大概增加 20-30MB 的内存占用。
+
+默认缓存的情况下，`speak`方法调用会更快，因为不需要重复初始化 TTS 模块。
+
+一般情况下，不需要手动调用`free`方法，除非内存资源有限。
+
+调用`free`时，会立即停止当前播放并释放 TTS 资源。
+
+**示例：**
+
+```javascript
+tts.free();
+```
+
+## 实用示例
+
+### 语音提醒功能
+
+```javascript
+function voiceAlert(message, urgent) {
+  if (urgent) {
+    // 紧急提醒：快速、高音调
+    tts.speak(message, 0.8, 1.5, 1.0, "zh-CN");
+  } else {
+    // 普通提醒：正常语速
+    tts.speak(message, 0.5, 1.0, 0.8, "zh-CN");
+  }
+}
+
+// 使用示例
+voiceAlert("任务完成", false);
+voiceAlert("发现错误，请立即处理", true);
+```
+
+### 多语言播报
+
+```javascript
+function speakInLanguage(text, language) {
+  // 根据语言选择合适的语音
+  const voices = tts.getAvailableVoices();
+  const targetVoice = voices.find((voice) =>
+    voice.language.startsWith(language)
+  );
+
+  if (targetVoice) {
+    tts.setVoice(targetVoice.identifier);
+    tts.speak(text, 0.5, 1.0, 1.0, language);
+  } else {
+    logw(`未找到 ${language} 语音，使用默认语音`);
+    tts.speak(text);
+  }
+}
+
+// 使用示例
+speakInLanguage("Hello World", "en");
+speakInLanguage("你好世界", "zh");
+speakInLanguage("こんにちは", "ja");
+```
+
+## 注意事项
+
+1. **语音资源**：不同设备可用的语音可能不同，建议在使用前检查可用语音列表
+2. **播放状态**：在开始新的语音播放前，建议检查当前播放状态
+3. **语言匹配**：设置语音时要确保语音支持要播放的语言
+4. **性能考虑**：频繁的语音播放可能影响性能，建议合理控制播放频率
+5. **错误处理**：语音播放可能失败，建议检查返回值并进行适当的错误处理
+
+## 常见问题
+
+**Q: 为什么语音播放失败？**
+
+A: 可能的原因包括：文本为空、语音资源不可用、系统音频设置问题等。建议检查参数和系统设置。
+
+**Q: 如何实现更自然的语音效果？**
+
+A: 可以通过调整语速（rate）、音调（pitch）参数，选择高质量的语音，以及在文本中添加适当的标点符号来改善语音效果。
+
+**Q: 支持哪些语言？**
+
+A: 支持的语言取决于系统安装的语音包，可以通过 `getAvailableVoices()` 查看所有可用的语言和语音。