@minto-ai/microsoft-tts/README.md

微软LAT 语音转文本

# Microsoft Text-to-Speech (TTS) 工具

一个基于 Microsoft Cognitive Services 的流式文本转语音工具，支持实时音频播放和丰富的语音控制选项。

## 功能特性

- 流式文本转语音合成
- 实时音频播放
- 支持语速、音量、音调调节
- 智能断句处理
- 多合成器并行处理
- 事件回调机制
- SSML 格式支持

## 安装

```bash
npm install microsoft-cognitiveservices-speech-sdk
```

## 快速开始

```typescript
import { SpeechOptions, StreamingTextToSpeech } from 'mt-utils/packages/microsoft-tts/src/index'

// 配置参数
const subscriptionKey = 'YOUR_AZURE_SUBSCRIPTION_KEY'
const region = 'YOUR_AZURE_REGION' // 例如: 'southeastasia'

// 创建 TTS 实例
const options: SpeechOptions = {
  voiceName: 'zh-CN-XiaoxiaoNeural',
  rate: 0, // 语速 (-100 到 100, 默认为 0)
  volume: 0, // 音量 (-100 到 100, 默认为 0)
  pitch: 0, // 音调 (-50 到 50, 默认为 0)
  autoPlay: true,
  smartBreaking: true
}

const tts = new StreamingTextToSpeech(subscriptionKey, region, options)

// 注册事件回调
tts.on('play', (data) => {
  console.log('开始播放音频')
  // 处理音频播放事件
})

tts.on('playCompleted', () => {
  console.log('音频播放完成')
  // 处理播放完成事件
})

tts.on('error', (error) => {
  console.error('发生错误:', error)
  // 处理错误事件
})

// 转换文本为语音
tts.speakText('你好，世界！')
tts.speakText('这是一个流式文本转语音的示例。')

// 标记输入结束
tts.endInput()

// 销毁实例
// tts.destroy()
```

## API 参考

### 构造函数

```typescript
new StreamingTextToSpeech(subscriptionKey: string, region: string, options?: SpeechOptions)
```

**参数:**

- `subscriptionKey`: Azure 语音服务订阅密钥
- `region`: Azure 语音服务区域 (例如: 'southeastasia')
- `options`: 语音配置选项 (可选)

### SpeechOptions 配置项

| 属性          | 类型                        | 默认值               | 描述                                    |
| ------------- | --------------------------- | -------------------- | --------------------------------------- |
| voiceName     | string                      | -                    | 语音名称 (例如: 'zh-CN-XiaoxiaoNeural') |
| rate          | number                      | 0                    | 语速 (-100 到 100)                      |
| volume        | number                      | 0                    | 音量 (-100 到 100)                      |
| pitch         | number                      | 0                    | 音调 (-50 到 50)                        |
| outputFormat  | SpeechSynthesisOutputFormat | Raw24Khz16BitMonoPcm | 音频输出格式                            |
| language      | string                      | 'zh-CN'              | 源语言                                  |
| autoPlay      | boolean                     | true                 | 是否自动播放                            |
| smartBreaking | boolean                     | true                 | 是否启用智能断句                        |

### 方法

#### speakText(text: string, ssml: boolean = false)

转换文本为语音

**参数:**

- `text`: 要转换的文本
- `ssml`: 是否使用 SSML 格式 (默认: false)

#### endInput()

标记输入结束，处理缓冲区剩余文本并触发播放完成事件

#### updateOptions(options: SpeechOptions)

更新语音配置选项

**参数:**

- `options`: 新的语音配置选项

#### on<T extends TtsEvent>(event: T, callback: TtsEventCallbacks[T])

注册事件回调

**参数:**

- `event`: 事件名称
- `callback`: 回调函数

#### off(event: TtsEvent)

移除事件回调

**参数:**

- `event`: 事件名称

#### destroy()

销毁实例，释放资源

### 支持的事件

## 使用示例

### 基础用法

```typescript
const tts = new StreamingTextToSpeech(subscriptionKey, region)

tts.on('play', (data) => {
  console.log('开始播放')
})

tts.on('playCompleted', () => {
  console.log('播放完成')
})

tts.speakText('你好，世界！')
tts.endInput()
```

### 调整语速

```typescript
const tts = new StreamingTextToSpeech(subscriptionKey, region, {
  rate: 50 // 提高语速 50%
})

tts.speakText('这是一段语速较快的语音。')
tts.endInput()
```

### 使用 SSML

```typescript
const tts = new StreamingTextToSpeech(subscriptionKey, region)

const ssml = `<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="zh-CN">
  <voice name="zh-CN-XiaoxiaoNeural">
    <prosody rate="+30%" pitch="+20%">
      这是一段使用 SSML 的语音示例。
    </prosody>
  </voice>
</speak>`

tts.speakText(ssml, true)
tts.endInput()
```

### 动态更新配置

```typescript
const tts = new StreamingTextToSpeech(subscriptionKey, region)

tts.speakText('这是正常语速。')

// 动态更新语速
tts.updateOptions({ rate: 100 })

tts.speakText('这段语速很快。')
tts.endInput()
```

## 注意事项

1. 需要有效的 Azure 语音服务订阅密钥
2. 在浏览器环境中使用时，音频播放需要用户交互触发
3. 使用 [end()](file:///d:/programe%20file/%E6%88%90%E9%83%BD%E6%98%8E%E9%80%94%E7%A7%91%E6%8A%80/mt-utils/packages/microsoft-tts/src/index.ts#L436-L454) 方法标记输入结束以正确触发播放完成事件
4. 使用 [destroy()](file:///d:/programe%20file/%E6%88%90%E9%83%BD%E6%98%8E%E9%80%94%E7%A7%91%E6%8A%80/mt-utils/packages/microsoft-tts/src/index.ts#L456-L483) 方法释放资源