openspeechapi 0.2.9

Unified speech interface for STT/TTS providers

OpenSpeechAPI

Unified speech interface for STT/TTS providers — one API, multiple backends.

OpenSpeechAPI 提供统一的语音接口，通过字符串指定 provider 即可切换不同的 STT/TTS 后端（云端 API、本地模型），无需关心底层实现。

Quick Start

安装

# 安装全部 provider
pip install -e ".[all]"

# 或按需安装
pip install -e ".[openai]"           # OpenAI Whisper STT + TTS
pip install -e ".[faster-whisper]"   # 本地 faster-whisper STT
pip install -e ".[openai,faster-whisper]"  # 指定多个

# 仅核心包（不含任何 provider）
pip install -e .

# 开发环境
pip install -e ".[dev]"

30 秒上手 — TTS

import asyncio
from openspeechapi import create_provider

async def main():
    tts = create_provider("openai-tts", api_key="sk-...")
    await tts.start()

    audio = await tts.synthesize("Hello, OpenSpeechAPI!")

    import wave
    with wave.open("output.wav", "wb") as wf:
        wf.setnchannels(audio.channels)
        wf.setsampwidth(2)
        wf.setframerate(audio.sample_rate)
        wf.writeframes(audio.data)

    await tts.stop()

asyncio.run(main())

30 秒上手 — STT

import asyncio
from openspeechapi import create_provider, AudioData, AudioFormat
from pathlib import Path

async def main():
    stt = create_provider("faster-whisper", model_size="tiny")
    await stt.start()

    audio = AudioData(
        data=Path("output.wav").read_bytes(),
        sample_rate=16000, channels=1, format=AudioFormat.WAV,
    )
    result = await stt.transcribe(audio)
    print(result.text)        # "Hello, OpenSpeechAPI!"
    print(result.language)    # "en"
    print(result.confidence)  # 0.98

    await stt.stop()

asyncio.run(main())

macOS 零依赖快速上手

在 macOS 上无需任何 API Key 或模型下载，开箱即用：

# 1. 克隆项目
git clone https://github.com/wingsfly/OpenSpeechAPI.git
cd OpenSpeechAPI

# 2. 安装（仅核心包 + 服务依赖）
pip install -e ".[server]"

# 3. 启动服务和 WebUI
python -m openspeechapi.cli --config providers.yaml serve

# 4. 浏览器打开 http://127.0.0.1:8600/ui/
#    - TTS：选择 macos_tts → 选择发音人（如 Tingting）→ 输入文本 → Run TTS
#    - STT：前往 Engine Catalog → macOS STT → Install（自动下载预编译包）

macOS STT 安装（通过 WebUI）

macos-stt 默认未写入配置（避免"假可用"），需通过 Engine Catalog 一键安装：

1. WebUI → Engine Catalog → macOS STT → Install
   • 优先下载 CI 预构建的 universal .app（无需 Xcode，通过 gh 自动完成）
   • 若 gh 不可用或资产下载失败，自动回退到本地编译（需 Xcode Command Line Tools）
2. 安装完成后，手动授权语音识别（每台机器一次）：

   open scripts/engines/macos-stt/MacOSSTTHelper.app
   # 弹出对话框后点击"允许"
   

3. 手动下载听写语言模型（每台机器一次）： 系统设置 > 键盘 > 听写 > 下载所需语言模型（中文/英文等）

安装完成后 macos_stt 自动写入配置并热重载，Dashboard 显示 healthy。

授权和听写模型下载是 macOS TCC 系统限制，无法自动化，必须每台机器手动执行一次。 详细机制见 docs/architecture/native-engine-install.md。

CLI Demo

无需写代码，直接在命令行体验：

# TTS：文本 → 语音
python -m openspeechapi.demo tts -t "Hello world" -o output.wav

# STT：语音 → 文本
python -m openspeechapi.demo stt -i output.wav -p faster-whisper

# Roundtrip：文本 → TTS → STT → 文本
python -m openspeechapi.demo roundtrip -t "Hello world"

# Compare：多引擎对比
python -m openspeechapi.demo compare -i output.wav -p openai,faster-whisper

# REPL：交互模式
python -m openspeechapi.demo repl

# WebUI（Phase A）
python -m openspeechapi.cli serve --host 0.0.0.0 --port 8600
# 浏览器打开 http://127.0.0.1:8600/ui

# 实时 STT：优先使用 WebSocket PCM 流式（/v1/stt/stream），
# 若浏览器或链路异常会自动回退到分片 HTTP 转写模式。

本地引擎管理（实验特性）

# 1) 下载/更新运行镜像
python -m openspeechapi.cli engine install --name fish-speech --runtime docker --follow

# 2) 启动本地引擎（含健康检查）
python -m openspeechapi.cli engine start --name fish-speech --runtime docker --follow

# 3) 查看运行状态/日志
python -m openspeechapi.cli engine status --name fish-speech --runtime docker
python -m openspeechapi.cli engine logs --name fish-speech --runtime docker --lines 200

# 4) 停止
python -m openspeechapi.cli engine stop --name fish-speech --runtime docker --follow

# 5) 跨进程查询任务
python -m openspeechapi.cli engine task list --name fish-speech --limit 20
python -m openspeechapi.cli engine task status --task-id <TASK_ID>
python -m openspeechapi.cli engine task follow --task-id <TASK_ID>
python -m openspeechapi.cli engine task cancel --task-id <TASK_ID>

进度反馈会显示 task id、阶段、百分比和当前消息，便于追踪长耗时任务。

STT 本地模型引擎（复用已有模型路径）

# faster-whisper 模型资产（native，无常驻服务）
python -m openspeechapi.cli engine install --name faster-whisper --runtime native --follow
python -m openspeechapi.cli engine start   --name faster-whisper --runtime native --follow
python -m openspeechapi.cli engine status  --name faster-whisper --runtime native

# whisper 模型资产（native，无常驻服务）
python -m openspeechapi.cli engine install --name whisper --runtime native --follow
python -m openspeechapi.cli engine start   --name whisper --runtime native --follow
python -m openspeechapi.cli engine status  --name whisper --runtime native

说明：安装会优先读取 ~/.aim/config.json + ~/.aim/registry.json 的 provision 信息来定位模型；若 AIM 未命中，再回退默认本地路径候选。若仍未找到，可按配置走“模拟下载”流程以验证安装进度。

Demo 音频播放

# 合成后直接播放
python -m openspeechapi.demo tts -t "Hello world" --play

# 指定播放参数
python -m openspeechapi.demo tts -t "Hello world" --play \
  --play-backend sounddevice --play-device 2 --play-volume 0.8

Providers

已实现

Provider	类型	说明	执行模式	安装
openai-stt	STT	OpenAI Whisper API（云端）	remote	pip install -e ".[openai]"
faster-whisper	STT	本地 Whisper 推理（GPU/CPU）	subprocess	pip install -e ".[faster-whisper]"
whisper	STT	OpenAI Whisper 本地推理（CPU/GPU）	subprocess	pip install -e ".[whisper]"
whisperlivekit-stt	STT	WhisperLiveKit 本地服务（Deepgram 兼容 WS，支持 MLX 后端）	local	pip install -e ".[whisperlivekit]"
elevenlabs-stt	STT	ElevenLabs Scribe API（云端，支持实时流式 WS + 批量）	remote	pip install -e ".[elevenlabs-stt]"
deepgram	STT	Deepgram API（云端，支持实时流式）	remote	pip install -e ".[deepgram]"
gemma4	STT	Google Gemma 4 多模态 ASR（macOS/MLX 本地，E4B 默认/12B 可选，>30s 自动分段，支持转写/翻译/理解）	subprocess	pip install -e ".[gemma4-stt]"
openai-tts	TTS	OpenAI Speech API（云端，支持流式）	remote	pip install -e ".[openai]"
elevenlabs	TTS	ElevenLabs 高质量语音（云端，支持 HTTP/WS 流式）	remote	pip install -e ".[elevenlabs-tts]"
minimax	TTS	Minimax 语音合成（云端）	remote	pip install -e ".[minimax]"
cosyvoice	TTS	CosyVoice 本地中文语音合成（GPU）	subprocess	需手动安装 CosyVoice
fish-speech	TTS	Fish-Speech 本地多语 TTS + voice clone	local	pip install -e ".[fish-speech]"
piper	TTS	Piper 轻量级本地 TTS（CPU 即可）	in_process	pip install -e ".[piper]"
macos-say	TTS	macOS 内置语音合成（say 命令，零依赖）	in_process	无需安装，macOS 自带
macos-stt	STT	macOS 内置语音识别（SFSpeechRecognizer）	in_process	WebUI Engine Catalog → Install（预编译优先，编译兜底）

Stub（待实现）

coqui

查看所有 provider

from openspeechapi import list_providers
print(list_providers())
# ['coqui', 'cosyvoice', 'deepgram', 'elevenlabs', 'faster-whisper',
#  'fish-speech', 'minimax', 'openai-stt', 'openai-tts', 'piper', 'whisper',
#  'whisperlivekit-stt']

Provider 参数

openai-stt

create_provider("openai-stt",
    api_key="sk-...",         # 必填，OpenAI API Key
    model="whisper-1",        # 模型名称
)

转录选项通过 STTOptions 传入：

from openspeechapi import STTOptions
result = await stt.transcribe(audio, STTOptions(
    language="zh",            # 语言提示
    prompt="技术会议记录",     # 上下文提示
    temperature=0.0,          # 0.0-1.0
))

faster-whisper

create_provider("faster-whisper",
    model_size="base",        # tiny / base / small / medium / large-v3
    device="auto",            # auto / cuda / cpu
    compute_type="default",   # default / int8 / float16
    beam_size=5,              # beam search 宽度
    download_root=None,       # 模型缓存目录
)

openai-tts

create_provider("openai-tts",
    api_key="sk-...",         # 必填，OpenAI API Key
    model="tts-1",            # tts-1 / tts-1-hd
    voice="alloy",            # alloy / echo / fable / onyx / nova / shimmer
    response_format="pcm",    # 输出格式
)

合成选项通过 TTSOptions 传入：

from openspeechapi import TTSOptions
audio = await tts.synthesize("Hello", TTSOptions(
    voice="nova",             # 覆盖默认声音
    speed=1.2,                # 语速倍率
))

deepgram

create_provider("deepgram",
    api_key="...",            # 必填，Deepgram API Key
    model="nova-2",           # 模型名称
    language="en",            # 默认语言
    punctuate=True,           # 自动标点
    smart_format=True,        # 智能格式化
)

支持实时流式转录（transcribe_stream），详见流式 STT 章节。

elevenlabs

create_provider("elevenlabs",
    api_key="...",            # 必填，ElevenLabs API Key
    voice_id="21m00Tcm4TlvDq8ikWAM",  # 声音 ID
    model_id="eleven_monolingual_v1",  # 模型
    stability=0.5,            # 声音稳定性
    similarity_boost=0.75,    # 相似度增强
)

minimax

create_provider("minimax",
    api_key="...",            # 必填，Minimax API Key
    group_id="...",           # 必填，Minimax Group ID
    model="speech-01-turbo",  # 模型
    voice_id="male-qn-qingse", # 声音 ID
    speed=1.0,                # 语速
)

cosyvoice

create_provider("cosyvoice",
    model_dir="/path/to/model",  # 必填，本地模型目录
    device="auto",               # auto / cuda / cpu
    spk_id="中文女",              # 说话人 ID
)

fish-speech

create_provider("fish-speech",
    api_url="http://localhost:8080",  # Fish-Speech 本地服务地址
    reference_audio=None,            # 参考音频路径（voice clone）
)

piper

create_provider("piper",
    model_path="/path/to/model.onnx",  # 必填，模型文件路径
    config_path="/path/to/config.json", # 必填，配置文件路径
    use_cuda=False,           # 是否使用 GPU
    length_scale=1.0,         # 语速（越大越慢）
    noise_scale=0.667,        # 噪声比例
)

macos-say（macOS 原生 TTS）

零额外依赖，使用 macOS 内置 say 命令，支持系统所有发音人。

create_provider("macos-say",
    default_voice="Tingting",  # 默认发音人（say -v '?' 查看全部）
    default_rate=200,          # 默认语速（words per minute）
)

支持通过 list_voices() 获取所有可用发音人（按语言分组）。合成时通过 TTSOptions(voice="Samantha", speed=1.5) 指定发音人和语速。

macos-stt（macOS 原生 STT）

使用 macOS 内置 SFSpeechRecognizer，通过 Swift CLI 助手（.app bundle）实现。 推荐通过 WebUI Engine Catalog 一键安装（自动下载预编译 universal 包，无需 Xcode）。

create_provider("macos-stt",
    language="zh-CN",          # 默认识别语言
    binary_path="",            # Swift 工具路径，空则自动检测
)

安装方式（推荐）： WebUI → Engine Catalog → macOS STT → Install

安装流程：B 预编译优先（gh release download），B 不可用时自动 C 兜底（bash install.sh，需 Xcode CLT）。 详见 docs/architecture/native-engine-install.md。

每台机器必须手动完成一次（无法自动化）：

# 1. 授权语音识别权限（安装后运行，弹出对话框后点击"允许"）
open scripts/engines/macos-stt/MacOSSTTHelper.app

# 2. 验证授权状态
scripts/engines/macos-stt/MacOSSTTHelper.app/Contents/MacOS/macos-stt-helper --check --language en-US

• 系统设置 > 键盘 > 听写 → 下载对应语言的离线听写模型（中文、英文等）
• macOS 13+ 支持完全离线识别，旧版本需联网

高级 / 离线手动安装（不依赖 WebUI 或 gh）：

# 需要 Xcode Command Line Tools（xcode-select --install）
bash scripts/engines/macos-stt/install.sh

HTTP 服务 + Client 模式

启动服务

openspeechapi serve --config providers.yaml --port 8600

Python Client（与 Library 模式接口一致）

from openspeechapi import Client

async with Client("http://localhost:8600") as c:
    # STT
    result = await c.stt.transcribe("faster-whisper", audio)

    # TTS
    audio = await c.tts.synthesize("openai-tts", "Hello world")

    # FanOut
    result = await c.stt.fanout(["openai", "faster-whisper"], audio, strategy="collect_all")

    # 管理
    providers = await c.list_providers()
    health = await c.health()

REST API

# STT
curl -X POST http://localhost:8600/v1/stt/transcribe \
  -F audio=@audio.wav -F provider=faster-whisper

# TTS
curl -X POST http://localhost:8600/v1/tts/synthesize \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "provider": "openai-tts"}' --output out.wav

# 管理
curl http://localhost:8600/v1/providers
curl http://localhost:8600/v1/health
curl http://localhost:8600/v1/metrics

高级用法

Config-Driven（YAML 配置）

# providers.yaml
providers:
  cloud-stt:
    provider: openai-stt
    exec_mode: remote
    settings:
      api_key: ${OPENAI_API_KEY}

  local-stt:
    provider: faster-whisper
    exec_mode: subprocess      # 独立进程，隔离 GPU 内存
    settings:
      model_size: large-v3
      device: cuda

exec_mode 约定：

• subprocess：子进程模型推理（IPC）
• local：本地服务引擎（HTTP/HTTPS）
• remote：云端服务 API
• in_process：预留给真正进程内推理（兼容旧配置，建议迁移）

from openspeechapi import ServiceDispatcher, ProviderRegistry
from openspeechapi.providers.stt.openai import OpenAISTT
from openspeechapi.providers.stt.faster_whisper import FasterWhisperSTT

registry = ProviderRegistry()
registry.register("openai-stt", OpenAISTT)
registry.register("faster-whisper", FasterWhisperSTT)

dispatcher = ServiceDispatcher.from_config("providers.yaml", registry)
await dispatcher.start()

result = await dispatcher.stt.transcribe("cloud-stt", audio)
await dispatcher.stop()

FanOut — 多引擎并发

from openspeechapi.dispatch.fanout import FirstCompleted, CollectAll

# 取最快返回的结果
result = await dispatcher.stt.fanout(
    ["cloud-stt", "local-stt"], audio, strategy=FirstCompleted()
)

# 收集所有结果对比
results = await dispatcher.stt.fanout(
    ["cloud-stt", "local-stt"], audio, strategy=CollectAll()
)
for name, t in results.successes.items():
    print(f"{name}: {t.text}")

Result Filters

providers:
  my-stt:
    provider: faster-whisper
    exec_mode: subprocess
    settings:
      model_size: base
    filters:
      - type: confidence
        min: 0.8              # 过滤低置信度结果
      - type: language
        allow: ["zh", "en"]   # 只保留中英文

Observers（可观测性）

from openspeechapi.observe.metrics import MetricsObserver
from openspeechapi.observe.debug import DebugLogObserver

dispatcher.add_observer(MetricsObserver())    # TTFB、耗时、吞吐
dispatcher.add_observer(DebugLogObserver())   # 详细日志

内置 5 个 Observer：MetricsObserver LatencyObserver DebugLogObserver UsageObserver TracingObserver

数据模型

AudioData(data=bytes, sample_rate=int, channels=int, format=AudioFormat, duration_ms=int|None)
Transcription(text=str, language=str|None, confidence=float|None, words=list[Word]|None)
Word(text=str, start_ms=int, end_ms=int, confidence=float|None)
STTOptions(language=str|None, prompt=str|None, temperature=float|None)
TTSOptions(voice=str|None, speed=float, output_format=AudioFormat)
AudioFormat: PCM_16K | PCM_44K | WAV | AIFF | MP3 | OGG | FLAC | OPUS

项目结构

openspeechapi/
  core/           # L1: Provider 抽象层（models, enums, base, registry）
  providers/      # Provider 适配器（stt/ 5个含macos, tts/ 8个含macos）
  utils/           # 工具模块（audio_converter, audio_playback）
  dispatch/       # L2: 调度层（dispatcher, executors, fanout, filters）
  observe/        # 可观测性（metrics, latency, debug, usage, tracing）
  server/         # L3: FastAPI HTTP/WebSocket 服务
  client/         # Python 薄客户端
  factory.py      # create_provider() 工厂函数
  config.py       # YAML 配置加载
  cli.py          # openspeechapi list / check / serve
  demo.py         # 交互式 demo CLI
examples/         # 示例脚本（Library 模式 + Client 模式）
tests/            # 332 tests（unit + integration + E2E）
Dockerfile        # 容器化部署
docker-compose.yml
.github/workflows/ci.yml  # GitHub Actions CI

环境变量

变量	用途
OPENAI_API_KEY	OpenAI STT/TTS 所需的 API Key
DEEPGRAM_API_KEY	Deepgram STT 所需的 API Key
ELEVENLABS_API_KEY	ElevenLabs TTS 所需的 API Key
MINIMAX_API_KEY	Minimax TTS 所需的 API Key
OPENSPEECH_API_KEY	HTTP 服务 Bearer token 认证 Key

支持 .env 文件自动加载（需 python-dotenv）。

部署

Docker:

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# GPU 支持（编辑 docker-compose.yml 取消注释 openspeechapi-gpu 服务）

直接启动:

openspeechapi serve --config providers.yaml --port 8600

认证

在 providers.yaml 中配置 API Key 认证：

server:
  auth:
    enabled: true
    api_keys:
      - ${OPENSPEECH_API_KEY}

启用后所有 REST 请求需携带 Bearer token：

curl -H "Authorization: Bearer your-key" http://localhost:8600/v1/providers

WebSocket 通过查询参数传递：

ws://localhost:8600/v1/stt/stream?provider=deepgram&token=your-key

/v1/health 端点免认证。不配置 server.auth 则无认证（开发模式）。

流式 STT

Deepgram 支持实时流式转录：

async with Client("http://localhost:8600") as c:
    async def audio_source():
        # 从麦克风或文件读取 PCM 音频块
        yield pcm_chunk

    async for transcription in c.stt.transcribe_stream("deepgram", audio_source()):
        print(transcription.text)

WebSocket 方式：

ws://localhost:8600/v1/stt/stream?provider=deepgram
# 发送: binary PCM audio frames
# 接收: {"type": "partial", "text": "..."}

CI

项目使用 GitHub Actions 自动化测试。每次 push 到 main 或 PR 时自动运行：

• ruff lint
• 单元测试 + 集成测试
• 代码覆盖率检查（≥70%）

License

Private — personal multi-project reuse.