omnivoice-server-api 0.0.1__tar.gz

omnivoice_server_api-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omnivoice_server_api-0.0.1/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: omnivoice-server-api
+Version: 0.0.1
+Summary: A Python async SDK that wraps the OmniVoice TTS server API into a clean, type-safe interface.
+Author-email: Jerry <wujr24@m.fudan.edu.cn>
+License: MIT
+Project-URL: Homepage, https://github.com/Jerry-Wu-GitHub/omnivoice-server-api
+Project-URL: Repository, https://github.com/Jerry-Wu-GitHub/omnivoice-server-api.git
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiofiles
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Requires-Dist: yarl
+Dynamic: license-file
+
+# OmniVoice Server API Python SDK
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+一个**异步**、**类型安全**的 Python SDK，用于调用 [omnivoice-server](https://github.com/Howard-Hou/OmniVoice) 的 OpenAI 兼容 TTS HTTP 服务。
+
+它提供了直观的接口，覆盖语音合成、声音克隆、多角色脚本合成、声音配置管理与模型查询等功能，让您能以 Pythonic 的方式生成语音。
+
+## ✨ 特性
+
+- 🚀 **全异步** – 基于 `httpx.AsyncClient`，支持高并发请求。
+- 📦 **类型安全** – 提供 `AudioFormat`、`ScriptOutputFormat`、`ScriptSegment` 等数据模型，配合 IDE 自动补全。
+- 🎙️ **语音合成** – 支持普通合成（`create_speech`）、一次发音克隆（`create_speech_clone`）与多角色脚本合成（`create_script_audio`）。
+- 🔑 **灵活认证** – 通过 `headers` 或自定义 `http_client` 注入 `Authorization` 头。
+- 🛠️ **开箱即用** – 支持 `.env` 配置，简洁的异步上下文管理。
+
+## 📦 安装
+
+```bash
+pip install omnivoice-server-api
+```
+
+或直接从源码安装：
+
+```bash
+git clone https://github.com/Jerry-Wu-GitHub/omnivoice-server-api.git
+cd omnivoice-server-api
+pip install -e .
+```
+
+## 🚀 快速开始
+
+### 1. 配置服务地址
+
+默认使用 ModelScope 推理地址。若需要自定义，可在项目根目录创建 `.env` 文件：
+
+```env
+OMNIVOICE_BASE_URL=https://studio-jerrywumodelscope-omnivoice-server.api-inference.modelscope.net
+```
+
+### 2. 基础用法
+
+```python
+import asyncio
+from omnivoice_server_api import OmniVoiceClient
+
+async def main():
+    async with OmniVoiceClient() as client:
+        # 合成语音
+        audio = await client.create_speech(
+            "你好，欢迎使用 OmniVoice 语音合成服务。",
+            voice="auto",
+            response_format="mp3",
+        )
+        with open("output.mp3", "wb") as f:
+            f.write(audio)
+
+        # 列出可用声音
+        voices = await client.list_voices()
+        print(voices)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 3. 认证（如服务需要）
+
+通过 `headers` 注入 `Authorization` 头：
+
+```python
+from omnivoice_server_api import OmniVoiceClient
+
+client = OmniVoiceClient(headers={"Authorization": "Bearer <your_token>"})
+```
+
+## 📖 API 概览
+
+SDK 的所有功能通过 `OmniVoiceClient` 提供：
+
+| 方法                    | 说明                       | 对应接口                            |
+| ----------------------- | -------------------------- | ----------------------------------- |
+| `create_speech()`       | 文本合成语音               | `POST /v1/audio/speech`             |
+| `create_speech_clone()` | 一次发音克隆               | `POST /v1/audio/speech/clone`       |
+| `create_script_audio()` | 多角色脚本合成             | `POST /v1/audio/script`             |
+| `list_voices()`         | 列出可用声音               | `GET /v1/voices`                    |
+| `create_profile()`      | 保存声音克隆配置           | `POST /v1/voices/profiles`          |
+| `get_profile()`         | 获取声音克隆配置           | `GET /v1/voices/profiles/{id}`      |
+| `update_profile()`      | 更新声音克隆配置           | `PATCH /v1/voices/profiles/{id}`    |
+| `delete_profile()`      | 删除声音克隆配置           | `DELETE /v1/voices/profiles/{id}`   |
+| `list_models()`         | 列出模型                   | `GET /v1/models`                    |
+| `get_model()`           | 获取模型                   | `GET /v1/models/{id}`               |
+| `health()`              | 就绪检查                   | `GET /health`                       |
+| `metrics()`             | 请求指标与内存使用         | `GET /metrics`                      |
+
+### 详细示例：一次发音克隆
+
+```python
+async def clone_example(client):
+    audio = await client.create_speech_clone(
+        "这是使用克隆音色合成的语音。",
+        ref_audio="reference.wav",      # 支持路径 / bytes / 文件对象
+        ref_text="这是参考音频对应的文本。",
+        response_format="wav",
+    )
+    with open("cloned.wav", "wb") as f:
+        f.write(audio)
+```
+
+### 详细示例：多角色脚本合成
+
+```python
+from omnivoice_server_api import OmniVoiceClient, ScriptSegment, ScriptOutputFormat
+
+async def script_example(client):
+    script = [
+        ScriptSegment(speaker="主持人", text="欢迎来到今天的节目。"),
+        ScriptSegment(speaker="嘉宾", text="大家好，很高兴来到这里。"),
+    ]
+    audio = await client.create_script_audio(
+        script,
+        output_format=ScriptOutputFormat.SINGLE_TRACK,
+        pause_between_speakers=0.8,
+    )
+    with open("script.wav", "wb") as f:
+        f.write(audio)
+```
+
+### 详细示例：声音克隆配置管理
+
+```python
+async def profile_example(client):
+    # 保存配置
+    await client.create_profile("my_voice", ref_audio="reference.wav")
+
+    # 查询配置
+    profile = await client.get_profile("my_voice")
+    print(profile)
+
+    # 更新配置
+    await client.update_profile("my_voice", ref_text="新的参考文本")
+
+    # 删除配置
+    await client.delete_profile("my_voice")
+```
+
+## 🧪 运行测试
+
+项目包含测试用例，位于 `tests/` 目录，需要能访问服务端。运行：
+
+```bash
+python tests/main.py
+```
+
+## 📄 许可证
+
+本项目使用 [MIT](LICENSE) 许可证。

omnivoice_server_api-0.0.1/README.md

@@ -0,0 +1,157 @@
+# OmniVoice Server API Python SDK
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+一个**异步**、**类型安全**的 Python SDK，用于调用 [omnivoice-server](https://github.com/Howard-Hou/OmniVoice) 的 OpenAI 兼容 TTS HTTP 服务。
+
+它提供了直观的接口，覆盖语音合成、声音克隆、多角色脚本合成、声音配置管理与模型查询等功能，让您能以 Pythonic 的方式生成语音。
+
+## ✨ 特性
+
+- 🚀 **全异步** – 基于 `httpx.AsyncClient`，支持高并发请求。
+- 📦 **类型安全** – 提供 `AudioFormat`、`ScriptOutputFormat`、`ScriptSegment` 等数据模型，配合 IDE 自动补全。
+- 🎙️ **语音合成** – 支持普通合成（`create_speech`）、一次发音克隆（`create_speech_clone`）与多角色脚本合成（`create_script_audio`）。
+- 🔑 **灵活认证** – 通过 `headers` 或自定义 `http_client` 注入 `Authorization` 头。
+- 🛠️ **开箱即用** – 支持 `.env` 配置，简洁的异步上下文管理。
+
+## 📦 安装
+
+```bash
+pip install omnivoice-server-api
+```
+
+或直接从源码安装：
+
+```bash
+git clone https://github.com/Jerry-Wu-GitHub/omnivoice-server-api.git
+cd omnivoice-server-api
+pip install -e .
+```
+
+## 🚀 快速开始
+
+### 1. 配置服务地址
+
+默认使用 ModelScope 推理地址。若需要自定义，可在项目根目录创建 `.env` 文件：
+
+```env
+OMNIVOICE_BASE_URL=https://studio-jerrywumodelscope-omnivoice-server.api-inference.modelscope.net
+```
+
+### 2. 基础用法
+
+```python
+import asyncio
+from omnivoice_server_api import OmniVoiceClient
+
+async def main():
+    async with OmniVoiceClient() as client:
+        # 合成语音
+        audio = await client.create_speech(
+            "你好，欢迎使用 OmniVoice 语音合成服务。",
+            voice="auto",
+            response_format="mp3",
+        )
+        with open("output.mp3", "wb") as f:
+            f.write(audio)
+
+        # 列出可用声音
+        voices = await client.list_voices()
+        print(voices)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 3. 认证（如服务需要）
+
+通过 `headers` 注入 `Authorization` 头：
+
+```python
+from omnivoice_server_api import OmniVoiceClient
+
+client = OmniVoiceClient(headers={"Authorization": "Bearer <your_token>"})
+```
+
+## 📖 API 概览
+
+SDK 的所有功能通过 `OmniVoiceClient` 提供：
+
+| 方法                    | 说明                       | 对应接口                            |
+| ----------------------- | -------------------------- | ----------------------------------- |
+| `create_speech()`       | 文本合成语音               | `POST /v1/audio/speech`             |
+| `create_speech_clone()` | 一次发音克隆               | `POST /v1/audio/speech/clone`       |
+| `create_script_audio()` | 多角色脚本合成             | `POST /v1/audio/script`             |
+| `list_voices()`         | 列出可用声音               | `GET /v1/voices`                    |
+| `create_profile()`      | 保存声音克隆配置           | `POST /v1/voices/profiles`          |
+| `get_profile()`         | 获取声音克隆配置           | `GET /v1/voices/profiles/{id}`      |
+| `update_profile()`      | 更新声音克隆配置           | `PATCH /v1/voices/profiles/{id}`    |
+| `delete_profile()`      | 删除声音克隆配置           | `DELETE /v1/voices/profiles/{id}`   |
+| `list_models()`         | 列出模型                   | `GET /v1/models`                    |
+| `get_model()`           | 获取模型                   | `GET /v1/models/{id}`               |
+| `health()`              | 就绪检查                   | `GET /health`                       |
+| `metrics()`             | 请求指标与内存使用         | `GET /metrics`                      |
+
+### 详细示例：一次发音克隆
+
+```python
+async def clone_example(client):
+    audio = await client.create_speech_clone(
+        "这是使用克隆音色合成的语音。",
+        ref_audio="reference.wav",      # 支持路径 / bytes / 文件对象
+        ref_text="这是参考音频对应的文本。",
+        response_format="wav",
+    )
+    with open("cloned.wav", "wb") as f:
+        f.write(audio)
+```
+
+### 详细示例：多角色脚本合成
+
+```python
+from omnivoice_server_api import OmniVoiceClient, ScriptSegment, ScriptOutputFormat
+
+async def script_example(client):
+    script = [
+        ScriptSegment(speaker="主持人", text="欢迎来到今天的节目。"),
+        ScriptSegment(speaker="嘉宾", text="大家好，很高兴来到这里。"),
+    ]
+    audio = await client.create_script_audio(
+        script,
+        output_format=ScriptOutputFormat.SINGLE_TRACK,
+        pause_between_speakers=0.8,
+    )
+    with open("script.wav", "wb") as f:
+        f.write(audio)
+```
+
+### 详细示例：声音克隆配置管理
+
+```python
+async def profile_example(client):
+    # 保存配置
+    await client.create_profile("my_voice", ref_audio="reference.wav")
+
+    # 查询配置
+    profile = await client.get_profile("my_voice")
+    print(profile)
+
+    # 更新配置
+    await client.update_profile("my_voice", ref_text="新的参考文本")
+
+    # 删除配置
+    await client.delete_profile("my_voice")
+```
+
+## 🧪 运行测试
+
+项目包含测试用例，位于 `tests/` 目录，需要能访问服务端。运行：
+
+```bash
+python tests/main.py
+```
+
+## 📄 许可证
+
+本项目使用 [MIT](LICENSE) 许可证。

omnivoice_server_api-0.0.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "omnivoice-server-api"   # 包名，保持与项目仓库名一致
+version = "0.0.1"               # 当前版本
+description = "A Python async SDK that wraps the OmniVoice TTS server API into a clean, type-safe interface." # 简短描述
+readme = "README.md"            # 自述文件，PyPI 会将其渲染为项目首页
+authors = [{name = "Jerry", email = "wujr24@m.fudan.edu.cn"}]  # 作者信息
+license = {text = "MIT"}        # 指定许可证，与 LICENSE 文件一致
+classifiers = [                 # 帮助用户在 PyPI 上找到你的项目
+    # 开发状态
+    "Development Status :: 3 - Alpha",
+
+    # 目标受众
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+
+    # 许可证
+    "License :: OSI Approved :: MIT License",
+
+    # 操作系统
+    "Operating System :: OS Independent",
+
+    # 编程语言 & Python 版本
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.11"
+dependencies = [                # 项目的运行时依赖，从 requirements.txt 移植
+    "aiofiles",
+    "httpx",
+    "python-dotenv",
+    "yarl",
+]
+
+[project.urls]                  # 可选，但推荐，指向你的项目主页或仓库
+Homepage = "https://github.com/Jerry-Wu-GitHub/omnivoice-server-api"
+Repository = "https://github.com/Jerry-Wu-GitHub/omnivoice-server-api.git"

omnivoice_server_api-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

omnivoice_server_api-0.0.1/src/omnivoice_server_api/__init__.py

@@ -0,0 +1,8 @@
+"""
+omnivoice-server API 的 Python 封装。
+"""
+
+__version__ = "0.0.1"
+
+from .data_models import AudioFormat, ScriptOnError, ScriptOutputFormat, ScriptSegment
+from .models import OmniVoiceClient

omnivoice_server_api-0.0.1/src/omnivoice_server_api/config.py

@@ -0,0 +1,24 @@
+"""
+配置
+"""
+
+import os
+
+from dotenv import load_dotenv
+from yarl import URL
+
+
+# 加载 .env 文件
+load_dotenv()
+
+# 基础域名
+OMNIVOICE_BASE_URL: URL = URL(os.getenv(
+    "OMNIVOICE_BASE_URL",
+    "https://studio-jerrywumodelscope-omnivoice-server.api-inference.modelscope.net"
+))
+
+# API 的相对路径（挂在 base_url 之后，例如 /v1 下的接口）
+OMNIVOICE_API_PATH: str = os.getenv(
+    "OMNIVOICE_API_PATH",
+    "v1"
+)

omnivoice_server_api-0.0.1/src/omnivoice_server_api/data_models/__init__.py

@@ -0,0 +1,6 @@
+"""
+数据模型。
+"""
+
+from .enums import AudioFormat, ScriptOutputFormat, ScriptOnError
+from .script import ScriptSegment

omnivoice_server_api-0.0.1/src/omnivoice_server_api/data_models/enums.py

@@ -0,0 +1,36 @@
+"""
+枚举类型。
+"""
+
+from enum import StrEnum
+
+
+class AudioFormat(StrEnum):
+    """
+    合成音频的编码格式。
+    """
+    MP3  = "mp3"
+    OPUS = "opus"
+    AAC  = "aac"
+    FLAC = "flac"
+    WAV  = "wav"
+    PCM  = "pcm"
+
+
+class ScriptOutputFormat(StrEnum):
+    """
+    多角色脚本音频的输出格式。
+    """
+    # 单轨音频，返回带元数据头的二进制音频
+    SINGLE_TRACK = "single_track"
+
+    # 多轨，返回包含每个说话人音轨与时间戳的 JSON
+    MULTI_TRACK  = "multi_track"
+
+
+class ScriptOnError(StrEnum):
+    """
+    多角色脚本合成时遇到错误的处理方式。
+    """
+    ABORT = "abort"
+    SKIP  = "skip"

omnivoice_server_api-0.0.1/src/omnivoice_server_api/data_models/script.py

@@ -0,0 +1,48 @@
+"""
+多角色脚本数据模型。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ..utils.regex import SPEAKER_ID_PATTERN
+
+
+@dataclass(frozen=True)
+class ScriptSegment:
+    """
+    多角色脚本中的单条台词。
+
+    Attributes:
+        speaker: 说话人 ID，须为 1~64 位字母、数字、下划线或横线。
+        text: 台词文本。
+        voice: 该台词使用的声音；缺省时回退到脚本的 default_voice。
+        speed: 该台词的语速（0.25~4）；缺省时回退到脚本的 speed。
+
+    Raises:
+        ValueError: 如果 speaker 不符合 ID 规范。
+    """
+    speaker: str
+    text: str
+    voice: Optional[str] = None
+    speed: Optional[float] = None
+
+    def __post_init__(self):
+        if not SPEAKER_ID_PATTERN.fullmatch(self.speaker):
+            raise ValueError(
+                f"Invalid speaker ID '{self.speaker}': "
+                "must be 1-64 alphanumeric/underscore/hyphen characters"
+            )
+
+    def to_dict(self) -> dict:
+        """
+        转为可 JSON 序列化的字典，并忽略值为 None 的字段。
+        """
+        result = {"speaker": self.speaker, "text": self.text}
+        if self.voice is not None:
+            result["voice"] = self.voice
+        if self.speed is not None:
+            result["speed"] = self.speed
+        return result

omnivoice_server_api-0.0.1/src/omnivoice_server_api/exceptions.py

@@ -0,0 +1,59 @@
+"""
+异常类
+"""
+
+from typing import Any, ClassVar, Dict, Optional
+
+
+class BusinessException(Exception):
+    """
+    业务异常基类，所有业务错误都继承自这里。
+
+    Attributes:
+        code: 错误代码
+        message: 错误消息
+        details: 附加详情（可选）
+    """
+
+    # 默认消息
+    DEFAULT_MESSAGE: ClassVar[str] = "Business Error"
+
+    # 默认错误代码
+    DEFAULT_CODE:    ClassVar[str] = "ERROR"
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        *,
+        code: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        self.message : str = self.DEFAULT_MESSAGE if (message is None) else message
+        self.code    : str = self.DEFAULT_CODE    if (code    is None) else code
+        self.details : Dict[str, Any] = details or {}
+
+        super().__init__(self.message)
+
+
+class UpstreamException(BusinessException):
+    """
+    上游服务端异常。
+    """
+    DEFAULT_MESSAGE: ClassVar[str] = "UpstreamException"
+    DEFAULT_CODE: ClassVar[str] = "UPSTREAM EXCEPTION"
+
+
+class ParseException(UpstreamException):
+    """
+    解析上游的响应失败。
+    """
+    DEFAULT_MESSAGE: ClassVar[str] = "ParseException"
+    DEFAULT_CODE: ClassVar[str] = "PARSE EXCEPTION"
+
+
+class OmniVoiceException(BusinessException):
+    """
+    omnivoice-server 业务错误。
+    """
+    DEFAULT_MESSAGE: ClassVar[str] = "OmniVoiceError"
+    DEFAULT_CODE: ClassVar[str] = "OMNIVOICE ERROR"

omnivoice_server_api-0.0.1/src/omnivoice_server_api/models/__init__.py

@@ -0,0 +1,5 @@
+"""
+封装了 API 的模型。
+"""
+
+from .omnivoice_client import OmniVoiceClient