# @bestcodes/edge-tts 中文文档

规范地址：https://npmcn.com/package/%40bestcodes/edge-tts/

版本：3\.0\.1
npm 元数据更新时间：2025-12-28T02:35:09.162Z
中文译文更新时间：2026-11-07T23:34:16.068Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bestcodes/edge-tts
原文对照：https://npmcn.com/package/%40bestcodes/edge-tts/?lang=original
项目主页：https://github.com/The-Best-Codes/edge-tts
源码仓库：https://github.com/The-Best-Codes/edge-tts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：26.3 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：typescript ^5\.9\.3
- 首次发布：2024-10-25T22:33:31.466Z
- 最新版本发布：2025-12-28T02:35:08.798Z
- 近 30 天下载量：2210（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 3 个）

## 中文简介

使用 Microsoft Edge TTS 自由文字对语言

## 安装

```sh
npm install @bestcodes/edge-tts
```

也可以使用：`pnpm add @bestcodes/edge-tts`、`yarn add @bestcodes/edge-tts`、`bun add @bestcodes/edge-tts`

## README

# @ bestcodes/ edge- tts (英语)

类型脚本端口 [边点](https://github.com/rany2/edge-tts/). 使用微软Edge的在线服务,实现小而快,简便的文本对语音.

-   小捆绑大小( < 50kb)
-   不需要 API 密钥
-   流出音频或保存到文件
-   生成 SRT 字幕
-   访问所有可用的边缘声音

## 安装

```bash
npm install @bestcodes/edge-tts
# or
bun add @bestcodes/edge-tts
```

## 快速启动

### 获取音频缓冲器

```ts
import { generateSpeech } from "@bestcodes/edge-tts";

const audio = await generateSpeech({
  text: "Hello, world!",
  voice: "en-US-EmmaMultilingualNeural",
});

// Do something with the audio buffer
```

### 保存到文件

```ts
import { generateSpeechToFile } from "@bestcodes/edge-tts";

await generateSpeechToFile({
  text: "Hello, world!",
  outputPath: "./output.mp3",
});
```

### 带字幕

```ts
import { generateSpeechWithSubtitlesToFile } from "@bestcodes/edge-tts";

const { audio, subtitles } = await generateSpeechWithSubtitlesToFile({
  text: "This text will have subtitles.",
  subtitlePath: "./subtitles.srt",
});
```

## 实时流线

### 流出音频块

```ts
import { streamSpeech } from "@bestcodes/edge-tts";

for await (const chunk of streamSpeech({
  text: "Hello, world!",
  voice: "en-US-EmmaMultilingualNeural",
})) {
  if (chunk.type === "audio" && chunk.data) {
    // Process audio chunk in real-time
    console.log(`Received ${chunk.data.length} bytes`);
  }
}
```

### 直接流到带有进度的文件

```ts
import { streamSpeechToFile } from "@bestcodes/edge-tts";

for await (const progress of streamSpeechToFile({
  text: "Hello, world!",
  outputPath: "./output.mp3",
})) {
  console.log(
    `Written: ${progress.bytesWritten} bytes (chunk: ${progress.chunkSize})`,
  );
}
```

### 有字幕的流( 实时更新)

```ts
import { streamSpeechWithSubtitlesToFile } from "@bestcodes/edge-tts";

for await (const chunk of streamSpeechWithSubtitlesToFile({
  text: "This text will have subtitles.",
  subtitlePath: "./subtitles.srt",
})) {
  if (chunk.type === "audio" && chunk.data) {
    // Process audio chunk
  } else if (chunk.subtitles) {
    // Subtitles file updated in real-time
    console.log("Subtitles updated:", chunk.subtitles);
  }
}
```

## 选项

```ts
{
  text: string;                    // Required: text to convert
  voice?: string;                  // Default: "en-US-EmmaMultilingualNeural"
  rate?: string;                   // e.g. "+10%" or "-20%" (default: "+0%")
  volume?: string;                 // e.g. "+50%" or "-10%" (default: "+0%")
  pitch?: string;                  // e.g. "+10Hz" or "-5Hz" (default: "+0Hz")
  boundary?: "WordBoundary" | "SentenceBoundary";
  proxy?: string;                  // Optional proxy URL
  connectTimeoutSeconds?: number;  // Default: 10
  receiveTimeoutSeconds?: number;  // Default: 60
  outputPath?: string;             // For generateSpeechToFile/streamSpeechToFile
  subtitlePath?: string;           // For generateSpeechWithSubtitlesToFile/streamSpeechWithSubtitlesToFile
}
```

## 列表声音

```ts
import { getVoices, findVoices } from "@bestcodes/edge-tts";

// Get all voices
const allVoices = await getVoices();

// Find specific voices
const femaleVoices = await findVoices({ Gender: "Female" });
const englishVoices = await findVoices({ Locale: "en-US" });
```

## 低级 API

```ts
import { Experimental_Raw } from "@bestcodes/edge-tts";

const communicate = new Experimental_Raw.Communicate(
  "Hello!",
  "en-US-EmmaMultilingualNeural",
);

for await (const chunk of communicate.stream()) {
  if (chunk.type === "audio") {
    // Process audio data (chunk.data is a Buffer)
  } else if (chunk.type === "WordBoundary") {
    // Word boundary metadata
  }
}
```

## 许可证

麻省理工学院

## 常见问题

### @bestcodes/edge-tts 是什么？

使用 Microsoft Edge TTS 自由文字对语言

### 如何安装 @bestcodes/edge-tts？

在项目目录运行 npm install @bestcodes/edge-tts，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^5\.9\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bestcodes/edge-tts 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bestcodes/edge-tts 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bestcodes/edge-tts 可以商用吗？

@bestcodes/edge-tts 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bestcodes/edge-tts 的下载量有多少？

根据 npm 官方下载统计，@bestcodes/edge-tts 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,210 次，日均约 74 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bestcodes/edge-tts 还在维护吗？

最新版本 3\.0\.1 发布于 2025/12/28（10 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 3 个；首次发布于 2024/10/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。