✨ feat: update api and document (#12)

.dumirc.ts

@@ -52,7 +52,10 @@ export default defineConfig({
     'process.env': process.env,
   },
   favicons: ['https://npm.elemecdn.com/@lobehub/assets-favicons/assets/favicon.ico'],
-  locales: [{ id: 'en-US', name: 'English' }],
+  locales: [
+    { id: 'en-US', name: 'English' },
+    { id: 'zh-CN', name: '简体中文' },
+  ],
   // mfsu: isWin ? undefined : {},
   mfsu: false,
   npmClient: 'pnpm',

CHANGELOG.md

@@ -2,6 +2,82 @@
 
 # Changelog
 
+## [Version 1.20.0-beta.3](https://github.com/lobehub/lobe-tts/compare/v1.20.0-beta.2...v1.20.0-beta.3)
+
+<sup>Released on **2023-11-17**</sup>
+
+#### ✨ Features
+
+- **misc**: Update OpenAITTS api.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **misc**: Update OpenAITTS api ([1a14f4b](https://github.com/lobehub/lobe-tts/commit/1a14f4b))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+## [Version 1.20.0-beta.2](https://github.com/lobehub/lobe-tts/compare/v1.20.0-beta.1...v1.20.0-beta.2)
+
+<sup>Released on **2023-11-17**</sup>
+
+#### ✨ Features
+
+- **misc**: Update MicrosoftSpeech api.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **misc**: Update MicrosoftSpeech api ([105e2d0](https://github.com/lobehub/lobe-tts/commit/105e2d0))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+## [Version 1.20.0-beta.1](https://github.com/lobehub/lobe-tts/compare/v1.19.1...v1.20.0-beta.1)
+
+<sup>Released on **2023-11-17**</sup>
+
+#### ✨ Features
+
+- **misc**: Update api, update api.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **misc**: Update api ([884f844](https://github.com/lobehub/lobe-tts/commit/884f844))
+- **misc**: Update api ([bfa78b1](https://github.com/lobehub/lobe-tts/commit/bfa78b1))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ### [Version 1.19.1](https://github.com/lobehub/lobe-tts/compare/v1.19.0...v1.19.1)
 
 <sup>Released on **2023-11-16**</sup>

docs/api/edge-speech-tts.md

@@ -0,0 +1,91 @@
+---
+group: TTS
+title: EdgeSpeechTTS
+apiHeader:
+  pkg: '@lobehub/tts'
+---
+
+`EdgeSpeechTTS` is a class for text-to-speech conversion based on Edge Speech Service.
+
+This class supports converting text to speech and provides a set of methods to retrieve voice options and create speech synthesis requests.
+
+```ts
+constructor(options: EdgeSpeechAPI & { locale?: string }): EdgeSpeechTTS
+```
+
+## Parameters
+
+- `options`: Object, optional.
+  - `serviceUrl`: String, specifies the URL of the Edge Speech Service. If provided, requests will be sent to this URL.
+  - `locale`: String, specifies the voice locale to use. If provided, it will be used to filter the available voice list.
+
+## Examples
+
+```js
+// index.js
+import { EdgeSpeechTTS } from '@lobehub/tts';
+import { Buffer } from 'buffer';
+import fs from 'fs';
+import path from 'path';
+
+// Instantiate EdgeSpeechTTS
+const tts = new EdgeSpeechTTS({ locale: 'en-US' });
+
+// Create speech synthesis request payload
+const payload = {
+  input: 'This is a speech demonstration',
+  options: {
+    voice: 'en-US-GuyNeural',
+  },
+};
+
+const speechFile = path.resolve('./speech.mp3');
+
+// Call create method to synthesize speech
+const response = await tts.create(payload);
+const mp3Buffer = Buffer.from(await response.arrayBuffer());
+
+fs.writeFileSync(speechFile, mp3Buffer);
+```
+
+Run with Bun:
+
+```shell
+$ bun index.js
+```
+
+Run in Node.js:
+
+As the Node.js environment lacks the `WebSocket` instance, we need to polyfill WebSocket. This can be done by importing the ws package.
+
+```js
+// Import at the top of the file
+import WebSocket from 'ws';
+
+global.WebSocket = WebSocket;
+```
+
+## Static Properties
+
+- `localeOptions`: Get all supported voice locale options.
+- `voiceList`: List of all available voices.
+- `voiceName`: Object containing all voice names.
+- `createRequest`: Static method used to create speech synthesis requests.
+
+## Methods
+
+### `voiceOptions`
+
+Get the voice options for the current instance, based on the `locale` specified during instantiation. Returns an object containing the currently available voice options.
+
+### `createAudio(payload: EdgeSpeechPayload): Promise<AudioBuffer>`
+
+Create speech synthesis using the given request payload.
+
+#### Parameters
+
+- `payload`: `EdgeSpeechPayload` type, containing the necessary information for the speech synthesis request.
+
+#### Return Value
+
+Returns a `Promise` that resolves to an `AudioBuffer` object containing the synthesized audio data.

docs/api/edge-speech-tts.zh-CN.md

@@ -0,0 +1,91 @@
+---
+group: TTS
+title: EdgeSpeechTTS
+apiHeader:
+  pkg: '@lobehub/tts'
+---
+
+`EdgeSpeechTTS` 是一个基于 Edge 语音服务的文本转语音方法类。
+
+该类支持将文本转换为语音，并提供了一系列方法来获取语音选项，创建语音合成请求。
+
+```ts
+constructor(options: EdgeSpeechAPI & { locale?: string }): EdgeSpeechTTS
+```
+
+## 参数
+
+- `options`: 对象，可选。
+  - `serviceUrl`: 字符串，指定 Edge 语音服务的 URL。如果提供，将使用此 URL 发送请求。
+  - `locale`: 字符串，指定要使用的语音区域设置。如果提供，将用于过滤可用语音列表。
+
+## 示例
+
+```js
+// index.js
+import { EdgeSpeechTTS } from '@lobehub/tts';
+import { Buffer } from 'buffer';
+import fs from 'fs';
+import path from 'path';
+
+// 实例化 EdgeSpeechTTS
+const tts = new EdgeSpeechTTS({ locale: 'zh-CN' });
+
+// 创建语音合成请求负载
+const payload = {
+  input: '这是一段语音演示',
+  options: {
+    voice: 'zh-CN-XiaoxiaoNeural',
+  },
+};
+
+const speechFile = path.resolve('./speech.mp3');
+
+// 调用 create 方法来合成语音
+const response = await tts.create(payload);
+const mp3Buffer = Buffer.from(await response.arrayBuffer());
+
+fs.writeFileSync(speechFile, mp3Buffer);
+```
+
+使用 Bun 运行：
+
+```shell
+$ bun index.js
+```
+
+在 Node.js 中运行:
+
+由于 Nodejs 环境缺少 `WebSocket` 实例，所以我们需要 polyfill WebSocket。通过引入 ws 包即可。
+
+```js
+// 在文件顶部引入
+import WebSocket from 'ws';
+
+global.WebSocket = WebSocket;
+```
+
+## 静态属性
+
+- `localeOptions`: 获取所有支持的语音区域选项。
+- `voiceList`: 包含所有可用语音的列表。
+- `voiceName`: 包含所有语音名称的对象。
+- `createRequest`: 用于创建语音合成请求的静态方法。
+
+## 方法
+
+### `voiceOptions`
+
+获取当前实例的语音选项，这些选项基于实例化时指定的 `locale`。 返回一个包含当前可用语音选项的对象。
+
+### `createAudio(payload: EdgeSpeechPayload): Promise<AudioBuffer>`
+
+使用给定的请求负载创建语音合成。
+
+#### 参数
+
+- `payload`: `EdgeSpeechPayload` 类型，包含语音合成请求的必要信息。
+
+#### 返回值
+
+返回一个 `Promise`，该 `Promise` 解析为 `AudioBuffer` 对象，包含合成的音频数据。

docs/api/index.zh-CN.md

@@ -0,0 +1,14 @@
+---
+title: API Reference
+nav:
+  title: API
+  order: 10
+---
+
+# API 参考指南
+
+## TTS
+
+- [EdgeSpeechTTS](./edge-speech-tts.zh-CN.md)
+- [MicrosoftSpeechTTS](microsoft-speech-tts.zh-CN.md)
+- [OpenaiTTS](openai-tts.zh-CN.md)

docs/api/microsoft-speech-tts.md

@@ -0,0 +1,103 @@
+---
+group: TTS
+title: MicrosoftSpeechTTS
+apiHeader:
+  pkg: '@lobehub/tts'
+---
+
+`MicrosoftSpeechTTS` is a class for text-to-speech using Microsoft Speech Services.
+
+This class supports converting text to speech and provides a series of methods to retrieve speech options and create speech synthesis requests.
+
+```ts
+constructor(options: MicrosoftSpeechAPI & { locale?: string }): MicrosoftSpeechTTS
+```
+
+## Parameters
+
+- `options`: Object, optional.
+  - `backendUrl`: String, specifies the URL of Microsoft Speech Services. If provided, requests will be sent to this URL.
+  - `locale`: String, specifies the language region to use. If provided, it will be used to filter the available voices.
+
+## Examples
+
+```js
+// index.js
+// index.js
+import { MicrosoftSpeechTTS } from '@lobehub/tts';
+
+// get MicrosoftSpeechTTS instance
+const tts = new MicrosoftSpeechTTS({ locale: 'zh-CN' });
+
+// create payload
+const payload: MicrosoftSpeechPayload = {
+  input: 'this is a message',
+  options: {
+    voice: 'en-US-JacobNeural',
+    style: 'embarrassed',
+  },
+};
+
+const speechFile = path.resolve('./speech.mp3');
+
+// create speech
+const response = await tts.create(payload);
+const mp3Buffer = Buffer.from(await response.arrayBuffer());
+
+fs.writeFileSync(speechFile, mp3Buffer);
+```
+
+Run with Bun:
+
+```shell
+$ bun index.js
+```
+
+Run in Node.js:
+
+Due to the lack of `WebSocket` instance in Nodejs environment, we need to polyfill WebSocket. By importing the ws package.
+
+```js
+// import at the top of the file
+import WebSocket from 'ws';
+
+global.WebSocket = WebSocket;
+```
+
+## Static Properties
+
+- `localeOptions`: Get all supported language region options.
+- `voiceList`: List of all available voices.
+- `voiceName`: Object containing all voice names.
+- `styleList`: List of all available voice styles.
+- `createRequest`: Static method for creating speech synthesis requests.
+
+## Methods
+
+### `voiceOptions`
+
+Get the voice options for the current instance, based on the `locale` specified during instantiation. Returns an object containing the current available voice options.
+
+### `create(payload: MicrosoftSpeechPayload): Promise<Response>`
+
+Create speech synthesis using the given request payload.
+
+#### Parameters
+
+- `payload`: `MicrosoftSpeechPayload` type, containing the necessary information for the speech synthesis request.
+
+#### Return Value
+
+Returns a `Promise` that resolves to a `Response` object containing the synthesized speech data.
+
+### `createAudio(payload: MicrosoftSpeechPayload): Promise<AudioBuffer>`
+
+Create speech synthesis using the given request payload and convert it to an `AudioBuffer` object.
+
+#### Parameters
+
+- `payload`: `MicrosoftSpeechPayload` type, containing the necessary information for the speech synthesis request.
+
+#### Return Value
+
+Returns a `Promise` that resolves to an `AudioBuffer` object containing the synthesized audio data.