:speaking_head: aspeak

一个简单的 Azure TTS API 文本转语音客户端。:laughing:

注意事项

自版本 6.0.0 起，aspeak 默认使用 Azure TTS 的 RESTful API。若要使用 WebSocket API，您可以在调用 aspeak 时指定 --mode websocket，或在您的配置文件的 auth 部分设置 mode = "websocket"。

自版本 4.0.0 起，aspeak 已用 Rust 重写。旧版 Python 版本可在 python 分支中找到。

您可以注册一个 Azure 账户，然后 根据需要选择付费方案（或继续使用免费层级）。 免费层级每月提供 50 万个字符的配额，无需付费。

请参阅认证部分，了解如何为 aspeak 设置认证信息。

安装

从 GitHub 发布页面下载（推荐大多数用户）

从这里下载最新版本。

下载后解压，您将获得一个二进制可执行文件。

您可以将其放置在 PATH 环境变量所包含的目录中，以便在任何地方运行它。

从 AUR 安装（推荐 Arch Linux 用户）

自 v4.1.0 起，您可以通过 AUR 安装 aspeak-bin。

从 PyPI 安装

通过 PyPI 安装还会为您安装 aspeak 的 Python 绑定。有关 Python 绑定的更多信息，请参阅 库使用#Python。

pip install -U aspeak==6.0.0

目前预编译的 wheel 文件仅适用于 x86_64 架构。 由于一些技术问题，我尚未将源代码发布到 PyPI。 因此，要从源代码构建 wheel，您需要按照从源码安装中的说明进行操作。

由于 manylinux 兼容性问题，Linux 平台的 wheel 文件目前无法在 PyPI 上获取。（不过您仍然可以从源代码构建它们。）

从源码安装

仅命令行工具

从源码安装 aspeak 最简单的方式是使用 cargo：

cargo install aspeak -F binary

或者，您也可以从 AUR 安装 aspeak。

Python Wheel

要构建 Python wheel，您需要先安装 maturin：

pip install maturin

克隆仓库并进入该目录后，您可以运行以下命令来构建 wheel：

maturin build --release --strip -F python --bindings pyo3 --interpreter python --manifest-path Cargo.toml --out dist-pyo3
maturin build --release --strip --bindings bin -F binary --interpreter python --manifest-path Cargo.toml --out dist-bin
bash merge-wheel.bash

如果一切顺利，您将在 dist 目录下得到一个 wheel 文件。

使用方法

运行 aspeak help 查看帮助信息。

运行 aspeak help <子命令> 查看特定子命令的帮助信息。

认证

认证选项应放在任何子命令之前。

例如，要使用您的订阅密钥和由区域指定的官方端点，可以运行以下命令：

$ aspeak --region <YOUR_REGION> --key <YOUR_SUBSCRIPTION_KEY> text "Hello World"

如果您使用的是自定义端点，可以使用 --endpoint 选项代替 --region。

为了避免重复输入，您可以将认证信息存储在 aspeak 配置文件中。 有关详细信息，请阅读下一节。

自 v5.2.0 起，您还可以通过以下环境变量设置认证凭据：

• ASPEAK_AUTH_KEY 用于使用订阅密钥进行认证
• ASPEAK_AUTH_TOKEN 用于使用授权令牌进行认证

自 v4.3.0 起，您可以让 aspeak 使用代理服务器连接到端点。 目前仅支持 http 和 socks5 代理（暂不支持 https）。例如：

$ aspeak --proxy http://your_proxy_server:port text "Hello World"
$ aspeak --proxy socks5://your_proxy_server:port text "Hello World"

aspeak 也会尊重 HTTP_PROXY（或 http_proxy）环境变量。

配置

aspeak v4 引入了“配置文件”的概念。 配置文件是一个配置文件，您可以在其中为命令行选项指定默认值。

运行以下命令创建您的默认配置文件：

$ aspeak config init

要编辑配置文件，运行：

$ aspeak config edit

如果您在运行上述命令时遇到困难，可以手动编辑配置文件：

首先通过运行以下命令获取配置文件路径：

$ aspeak config where

然后使用您喜欢的文本编辑器编辑该文件。

配置文件是 TOML 格式。默认配置文件如下所示：

请查看配置文件中的注释，以了解可用选项的更多信息。

# aspeak 配置文件
# GitHub: https://github.com/kxxt/aspeak

# 输出冗余度
# 0   - 默认
# 1   - 详细
# 以下输出冗余度级别仅在调试版本中支持
# 2   - 调试
# >=3 - 追踪
verbosity = 0

#
# 认证配置
#

[auth]
# TTS 的端点
# endpoint = "wss://eastus.tts.speech.microsoft.com/cognitiveservices/websocket/v1"

# 或者，如果您使用官方端点，可以指定区域
# region = "eastus"

# 合成模式，“rest”或“websocket”
# mode = "rest"

# Azure 订阅密钥
# key = "YOUR_KEY"

# 认证令牌
# token = "Your Authentication Token"

# 额外的 HTTP 头部（面向专家）
# headers = [["X-My-Header", "My-Value"], ["X-My-Header2", "My-Value2"]]

# 代理
# proxy = "socks5://127.0.0.1:7890"

# 语音列表 API 地址
# voice_list_api = "Custom voice list API url"

#
# 文本子命令的配置
#

[text]
# 要使用的语音。请注意，它优先于语言区域
# voice = "en-US-JennyNeural"
# 要使用的语言区域
locale = "en-US"
# 语速
# rate = 0
# 音高
# pitch = 0
# 角色
# role = "Boy"
# 风格，默认为“general”
# style = "general"
# 风格程度，介于 0.1 和 2.0 之间的浮点数
# style_degree = 1.0

#
# 输出配置
#

[output]
# 容器格式，仅支持 wav/mp3/ogg/webm。
container = "wav"
# 音质。运行 `aspeak list-qualities` 查看可用音质。
#
# 如果您选择的容器格式不支持此处指定的音质等级，

# 我们将自动为您选择最接近的音质等级。
quality = 0
# 音频格式（面向专家）。运行 `aspeak list-formats` 查看可用格式。
# 请注意，它优先级高于容器和音质！
# format = "audio-16khz-128kbitrate-mono-mp3"

如果您想使用默认配置文件之外的其他配置文件，可以使用 --profile 参数：

aspeak --profile <PATH_TO_A_PROFILE> text "Hello"

如果您想临时禁用配置文件，可以使用 --no-profile 参数：

aspeak --no-profile --region eastus --key <YOUR_KEY> text "Hello"

音高和语速

• rate：语音的语速。
  • 如果您使用浮点值（例如 0.5），该值将乘以 100%，变为 50.00%。
  • 您也可以使用以下值：x-slow、slow、medium、fast、x-fast、default。
  • 您还可以直接使用百分比值：+10%。
  • 您也可以使用相对浮点值（带 f 后缀），例如 1.2f：
    • 根据 Azure 文档，
    • 相对值表示为一个数字，作为默认语速的倍数。
    • 例如，值为 1f 表示语速不变。值为 0.5f 表示语速减半。值为 3f 表示语速提高三倍。
• pitch：语音的音高。
  • 如果您使用浮点值（例如 -0.5），该值将乘以 100%，变为 -50.00%。
  • 您也可以使用以下值：x-low、low、medium、high、x-high、default。
  • 您还可以直接使用百分比值：+10%。
  • 您也可以使用相对值（例如 -2st 或 +80Hz）：
    • 根据 Azure 文档，
    • 相对值表示为一个数字，前面带有 + 或 -，后面跟 Hz 或 st，用于指定音高的变化量。
    • 其中 st 表示变化单位为半音，即标准全音阶上的一半音程。
  • 您也可以使用绝对值：例如 600Hz

注意：不合理的高低值将被 Azure 认知服务裁剪为合理范围。

示例

以下示例假设您已在配置文件中设置好身份验证。

对默认语音合成器说“Hello, world!”。

$ aspeak text "Hello, world"

使用 SSML 进行语音合成。

$ aspeak ssml << EOF
<speak version='1.0' xmlns='http://www.w3.org/2001/10/synthesis' xml:lang='en-US'><voice name='en-US-JennyNeural'>Hello, world!</voice></speak>
EOF

列出所有可用的语音。

$ aspeak list-voices

列出所有适用于中文的语音。

$ aspeak list-voices -l zh-CN

获取某一种语音的信息。

$ aspeak list-voices -v en-US-SaraNeural

Microsoft Server Speech Text to Speech Voice (en-US, SaraNeural)
显示名：Sara
本地名：Sara @ en-US
区域设置：英语（美国）
性别：女性
ID：en-US-SaraNeural
语音类型：神经网络
状态：GA
采样率：48000Hz
每分钟字数：157
风格：["angry", "cheerful", "excited", "friendly", "hopeful", "sad", "shouting", "terrified", "unfriendly", "whispering"]

将合成的语音保存到文件。

$ aspeak text "Hello, world" -o output.wav

如果您更喜欢 mp3/ogg/webm 格式，可以使用 -c mp3/-c ogg/-c webm 选项。

$ aspeak text "Hello, world" -o output.mp3 -c mp3
$ aspeak text "Hello, world" -o output.ogg -c ogg
$ aspeak text "Hello, world" -o output.webm -c webm

列出可用的音质等级。

$ aspeak list-qualities

MP3 的音质等级：
  3：audio-48khz-192kbitrate-mono-mp3
  2：audio-48khz-96kbitrate-mono-mp3
 -3：audio-16khz-64kbitrate-mono-mp3
  1：audio-24khz-160kbitrate-mono-mp3
 -2：audio-16khz-128kbitrate-mono-mp3
 -4：audio-16khz-32kbitrate-mono-mp3
 -1：audio-24khz-48kbitrate-mono-mp3
  0：audio-24khz-96kbitrate-mono-mp3

WAV 的音质等级：
 -2：riff-8khz-16bit-mono-pcm
  1：riff-24khz-16bit-mono-pcm
  0：riff-24khz-16bit-mono-pcm
 -1：riff-16khz-16bit-mono-pcm

OGG 的音质等级：
  0：ogg-24khz-16bit-mono-opus
 -1：ogg-16khz-16bit-mono-opus
  1：ogg-48khz-16bit-mono-opus

WEBM 的音质等级：
  0：webm-24khz-16bit-mono-opus
 -1：webm-16khz-16bit-mono-opus
  1：webm-24khz-16bit-24kbps-mono-opus

列出可用的音频格式（面向专家用户）

$ aspeak list-formats

amr-wb-16000hz
audio-16khz-128kbitrate-mono-mp3
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
raw-8khz-16bit-mono-pcm
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
riff-16khz-16bit-mono-pcm
riff-22050hz-16bit-mono-pcm
riff-24khz-16bit-mono-pcm
riff-44100hz-16bit-mono-pcm
riff-48khz-16bit-mono-pcm
riff-8khz-16bit-mono-pcm
riff-8khz-8bit-mono-alaw
riff-8khz-8bit-mono-mulaw
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus

调整音频音质

# 低于默认音质。
$ aspeak text "Hello, world" -o output.mp3 -c mp3 -q=-1
# 最佳 MP3 音质。
$ aspeak text "Hello, world" -o output.mp3 -c mp3 -q=3

从文件读取文本并朗读。

$ cat input.txt | aspeak text

或者

$ aspeak text -f input.txt

使用自定义编码：

$ aspeak text -f input.txt -e gbk

从标准输入读取并朗读。

$ aspeak text

或者您也可以这样：

$ aspeak text -l zh-CN << EOF
我能吞下玻璃而不伤身体。
EOF

用中文朗读。

$ aspeak text "你好，世界！" -l zh-CN

使用自定义语音。

$ aspeak text "你好，世界！" -v zh-CN-YunjianNeural

自定义音高、语速和风格

$ aspeak text "你好，世界！" -v zh-CN-XiaoxiaoNeural -p 1.5 -r 0.5 -S sad
$ aspeak text "你好，世界！" -v zh-CN-XiaoxiaoNeural -p=-10% -r=+5% -S cheerful
$ aspeak text "你好，世界！" -v zh-CN-XiaoxiaoNeural -p=+40Hz -r=1.2f -S fearful
$ aspeak text "你好，世界！" -v zh-CN-XiaoxiaoNeural -p=high -r=x-slow -S calm
$ aspeak text "你好，世界！" -v zh-CN-XiaoxiaoNeural -p=+1st -r=-7% -S lyrical

高级用法

使用自定义音频格式进行输出

注意：某些音频格式在输出到扬声器时不受支持。

$ aspeak text "Hello World" -F riff-48khz-16bit-mono-pcm -o high-quality.wav

库使用

Python

aspeak 的新版本是用 Rust 编写的，Python 绑定由 PyO3 提供。

以下是一个简单的示例：

from aspeak import SpeechService

service =  SpeechService(region="eastus", key="YOUR_AZURE_SUBSCRIPTION_KEY")
service.speak_text("Hello, world")

首先需要创建一个 SpeechService 实例。

在创建 SpeechService 实例时，可以指定以下参数：

• audio_format（位置参数）：输出音频的音频格式。默认为 AudioFormat.Riff24KHz16BitMonoPcm。
  • 可以通过提供容器格式和质量等级来获取音频格式：AudioFormat("mp3", 2)。
• endpoint：语音服务的端点。
• region：也可以指定语音服务的区域，而不用输入冗长的端点 URL。
• key：语音服务的订阅密钥。
• token：语音服务的认证令牌。如果提供了令牌，则会忽略订阅密钥。
• headers：语音服务的额外 HTTP 头。
• mode：选择要使用的合成器。可以是 rest 或 websocket。
  • 在 websocket 模式下，合成器会在创建 SpeechService 实例时连接到端点。

之后，可以调用 speak_text() 来朗读文本，或调用 speak_ssml() 来朗读 SSML。也可以调用 synthesize_text() 或 synthesize_ssml() 来获取音频数据。

对于 synthesize_text() 和 synthesize_ssml()，如果提供了 output 参数，音频数据将会被写入该文件，并且函数会返回 None。否则，函数会返回音频数据。

以下是 speak_text() 和 synthesize_text() 的常见选项：

• locale：语音的语言环境。默认为 en-US。
• voice：语音名称。默认为 en-US-JennyNeural。
• rate：语音的语速。必须是一个符合本节文档中要求的字符串：音高和语速。
• pitch：语音的音高。必须是一个符合本节文档中要求的字符串：音高和语速。
• style：语音的风格。
  • 可以通过执行 aspeak -L -v <VOICE_ID> 来获取特定语音的可用风格列表。
  • 默认值为 general。
• style_degree：风格的程度。
  • 根据 Azure 文档 ，风格程度指定了说话风格的强度。 它是一个介于 0.01 和 2 之间的浮点数，包括 0.01 和 2。
  • 截至撰写本文时，风格程度调整仅适用于中文（普通话，简体）神经网络语音。
• role：语音的角色。
  • 根据 Azure 文档 ，role 指定了语音扮演的角色。语音会表现出不同的年龄和性别特征，但语音名称不会改变。
  • 截至撰写本文时，角色调整仅适用于以下中文（普通话，简体）神经网络语音： zh-CN-XiaomoNeural、zh-CN-XiaoxuanNeural、zh-CN-YunxiNeural 和 zh-CN-YunyeNeural。

Rust

将 aspeak 添加到你的 Cargo.toml 中：

$ cargo add aspeak

然后按照 aspeak crate 的 文档 进行操作。

这里有 4 个示例供快速参考：

• RestSynthesizer 的简单用法
• WebsocketSynthesizer 的简单用法
• 合成给定目录中的所有 txt 文件
• 读取-合成-朗读循环：逐行从标准输入读取文本并朗读

aspeak 快速上手指南

aspeak 是一个基于 Rust 开发的轻量级命令行工具，用于调用 Azure 文本转语音 (TTS) API。它支持 RESTful 和 WebSocket 模式，提供灵活的语音配置和多种音频格式输出。

环境准备

• 操作系统：Linux (x86_64), macOS, Windows
• 前置依赖：
  • 若使用预编译二进制文件：无需额外依赖
  • 若从源码安装：需安装 Rust (推荐通过 rustup 安装)
  • 若构建 Python Wheel：需安装 maturin (pip install maturin)
• Azure 账号：需注册 Azure 账号并获取订阅密钥（Subscription Key）或授权令牌。免费额度包含每月 50 万字符。

安装步骤

方法一：下载预编译二进制文件（推荐）

1. 访问 GitHub Releases 下载对应系统的最新版本压缩包。
2. 解压后得到可执行文件 aspeak。
3. （可选）将文件移动到系统 PATH 目录以便全局调用：

   # Linux/macOS 示例
   chmod +x aspeak
   sudo mv aspeak /usr/local/bin/
   

方法二：通过 Cargo 从源码安装（适合开发者）

确保已安装 Rust，然后运行：

cargo install aspeak -F binary

方法三：通过 PyPI 安装（含 Python 绑定）

pip install -U aspeak==6.0.0

注意：目前 PyPI 仅提供 x86_64 架构的预编译轮子。Linux 用户若遇兼容性问题，建议使用方法一或从源码构建。

方法四：Arch Linux 用户 (AUR)

yay -S aspeak-bin
# 或
paru -S aspeak-bin

基本使用

1. 配置认证信息

为避免每次命令都输入密钥，建议初始化配置文件：

aspeak config init

运行上述命令后，编辑配置文件（路径可通过 aspeak config where 查看），在 [auth] 部分填入你的区域和密钥：

[auth]
region = "eastus"
key = "YOUR_SUBSCRIPTION_KEY"

提示：也可通过环境变量设置认证信息：

• export ASPEAK_AUTH_KEY="YOUR_KEY"
• export ASPEAK_AUTH_TOKEN="YOUR_TOKEN"

2. 合成语音并播放

最简单的用法，将文本转换为语音并通过默认扬声器播放：

aspeak text "你好，世界！"

若未配置默认 Profile，需在命令中指定参数：

aspeak --region eastus --key <YOUR_KEY> text "Hello World"

3. 保存音频文件

将合成结果保存为 WAV 文件：

aspeak text "Hello World" -o output.wav

支持其他格式（MP3, OGG, WEBM）：

aspeak text "Hello World" -o output.mp3 -c mp3

4. 查看可用语音列表

列出所有支持的语音：

aspeak list-voices

筛选特定语言（如中文）：

aspeak list-voices -l zh-CN

查看特定语音详情：

aspeak list-voices -v zh-CN-XiaoxiaoNeural