Edge TTS (Browser Extension & Server)

English | 中文

---

Edge TTS

A powerful Text-to-Speech solution with multi-engine support. Consists of a Python Backend (FastAPI), a Chrome Extension (Vue 3), and an OpenAI-compatible API.

Features

• 🚀 Multi-Engine: Microsoft Edge Neural voices + Volcengine (ByteDance) TTS
• 🤖 OpenAI Compatible: Drop-in replacement for POST /v1/audio/speech — works with OpenAI SDK
• ⚡ Streaming: Low latency audio streaming
• 🧩 Smart Chunking: Automatically splits long articles into paragraphs
• 🔁 Preloading: Automatically fetches the next paragraph for smooth playback
• ⏯️ Controls: Play, Pause, Resume, Stop, Click-to-play, Retry failed chunks
• ⚙️ Customizable: Adjust speed, volume, voice, format
• 🔒 Secure: JWT authentication with localhost bypass

API Endpoints

OpenAI Compatible (Recommended)

Method	Path	Description
POST	/v1/audio/speech	TTS synthesis (model=tts-1 for Edge, volcengine for Volcengine)
GET	/v1/models	List available models
GET	/v1/audio/voices	List all voices across engines

from openai import OpenAI

client = OpenAI(api_key="dummy", base_url="http://localhost:8000/v1")

# Edge engine
response = client.audio.speech.create(model="tts-1", voice="zh-CN-XiaoxiaoNeural", input="Hello")

# Volcengine engine
response = client.audio.speech.create(model="volcengine", voice="alloy", input="你好")

Legacy (Backward Compatible)

Method	Path	Description
POST	/api/v1/tts/stream	Original TTS endpoint
GET	/api/v1/tts/voices	Voice list
POST	/api/v1/text/chunk	Text chunking

Authentication & Security

• Localhost Bypass: If you are running both the backend and the extension on the same machine (127.0.0.1), you do not need a JWT token.
• Remote Usage: If the backend is on a different server, you must provide the JWT token generated by the server.
• Secret Key & Token Validity:
  • The server generates a unique SECRET_KEY on first run and saves it to config/config.env.
  • This key is used to sign JWT tokens.
  • Important: Even though the server prints a new "Admin Token" string in the logs on every restart, previously issued tokens remain valid as long as the SECRET_KEY in config/config.env stays the same.
  • You only need to update the token in your extension if you delete/change the config.env file.

Installation Methods

Method 1: Docker (Recommended)

1. Start Backend:

   docker compose up -d

   Note: A config directory will be created in your current folder containing config.env with the generated SECRET_KEY.

2. Get Token: View logs to find the Admin Token:

   docker logs edge-tts-backend

   Note: Logs are limited to 20MB with 3 rotations.

Method 2: Python Direct Run

1. Install Dependencies:

   cd backend
   pip install -r requirements.txt

2. Start Server:

   uvicorn app.main:app --host 0.0.0.0 --port 8000

3. Get Token: Copy the Admin Token printed in the terminal.

---

Extension Setup

1. Download/Build Extension:
   • Users: Download edge-tts-extension.zip from Releases and unzip it.
   • Developers: Run npm install && npm run build in the extension folder.
2. Load into Chrome:
   1. Go to chrome://extensions/.
   2. Enable Developer mode (top right).
   3. Click Load unpacked and select the dist folder (or unzipped folder).

How to Use

1. Open Panel: Click the extension icon to open the Side Panel.
2. Configure (If needed):
   • Click the Settings (⚙️) button.
   • Set Backend URL (default is http://localhost:8000).
   • Paste the JWT Token (only required if not using localhost).
   • Click "Refresh Voice List".
3. Start Reading:
   • Open any web page and click "Read Page".
   • Tip: Select specific text on the page to read only that part.

---

Edge TTS (浏览器插件与服务端)

一个多引擎文本转语音解决方案。包含 Python 后端 (FastAPI)、Chrome 插件 (Vue 3) 和 OpenAI 兼容 API。

功能特性

• 🚀 多引擎: 微软 Edge Neural 语音 + 火山引擎（字节跳动）TTS
• 🤖 OpenAI 兼容: 可直接用 OpenAI SDK 调用 (POST /v1/audio/speech)
• ⚡ 流式传输: 极低延迟的音频流式播放
• 🧩 智能分块: 自动将长文章切分为段落，支持逐段播放
• 🔁 自动预加载: 播放当前段落时自动下载下一段，实现无缝衔接
• ⏯️ 播放控制: 播放、暂停、恢复、停止，点击跳转，失败重试
• ⚙️ 个性化: 语速、音量、音色、格式可调
• 🔒 安全: JWT 鉴权 + 本地免密

API 端点

OpenAI 兼容接口（推荐）

方法	路径	说明
POST	/v1/audio/speech	TTS 合成 (model=tts-1 用 Edge, volcengine 用火山引擎)
GET	/v1/models	模型列表
GET	/v1/audio/voices	所有引擎音色列表

from openai import OpenAI

client = OpenAI(api_key="dummy", base_url="http://localhost:8000/v1")

# Edge 引擎
response = client.audio.speech.create(model="tts-1", voice="zh-CN-XiaoxiaoNeural", input="你好")

# 火山引擎
response = client.audio.speech.create(model="volcengine", voice="alloy", input="你好")

原有接口（向后兼容）

方法	路径	说明
POST	/api/v1/tts/stream	原有 TTS 接口
GET	/api/v1/tts/voices	音色列表
POST	/api/v1/text/chunk	文本分块

CLI 工具

# 直接合成 Markdown 文件
python tts_demo.py document.md --output output.mp3

# 指定引擎参数
python tts_demo.py doc.md --voice zh_female_vv_uranus_bigtts --speech-rate 20

认证与安全说明

• 本地免密: 如果您的后端和插件运行在同一台机器上（即通过 127.0.0.1 访问），您 无需设置 JWT Token 即可直接使用。
• 远程访问: 如果后端部署在远程服务器，必须在插件设置中填入服务器生成的 JWT Token。
• 密钥与 Token 有效期:
  • 后端首次运行时会随机生成 SECRET_KEY 并保存至 config/config.env 文件中。
  • 重要: 虽然每次重启服务时日志都会打印一个新的 Token 字符串，但只要 config/config.env 中的 SECRET_KEY 保持不变，之前生成的 Token 依然有效。
  • 除非您手动删除了 config 目录或修改了密钥，否则无需在插件中频繁更新 Token。

安装方式

方法一：Docker 部署 (推荐)

1. 启动后端:

   docker compose up -d

   注：项目根目录下会自动生成 config 目录，其中 config.env 文件包含生成的 SECRET_KEY。

2. 获取 Token: 查看容器日志以获取 Admin Token:

   docker logs edge-tts-backend

   注：日志文件限制为最大 20MB，保留 3 个历史文件。

方法二：Python 直接运行

1. 安装依赖:

   cd backend
   pip install -r requirements.txt

2. 启动服务:

   uvicorn app.main:app --host 0.0.0.0 --port 8000

3. 获取 Token: 复制终端中打印出来的 Admin Token。

---

插件安装与配置

1. 准备插件包:
   • 普通用户: 从 Releases 页面下载 edge-tts-extension.zip 并解压。
   • 开发者: 在 extension 目录下运行 npm install && npm run build。
2. 加载到 Chrome:
   1. 打开 Chrome 浏览器，访问 chrome://extensions/。
   2. 开启右上角的 开发者模式 (Developer mode)。
   3. 点击 加载已解压的扩展程序 (Load unpacked)，选择 dist 文件夹（或解压后的文件夹）。

使用说明

1. 打开面板: 点击浏览器工具栏中的插件图标打开侧边栏。
2. 配置 (可选):
   • 点击右上角的 设置 (⚙️) 按钮。
   • 设置 Backend URL (默认为 http://localhost:8000)。
   • 粘贴 JWT Token (仅当非本地访问时需要)。
   • 点击 "Refresh Voice List" 同步语音列表。
3. 开始朗读:
   • 打开任意网页，点击 "Read Page" 开始朗读。
   • 提示: 如果只想朗读某一段，可以在网页上先选中那段文字。