zvex 0.1.0__tar.gz

zvex-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+node_modules
+dist
+.DS_Store
+*.swp
+.git/*
+__pycache__/
+*.pyc
+.venv
+*.o
+*.a
+/vendor
+*.egg-info/
+/.env
+.env
+.zcode/
+
+# 视频文件
+*.mp4
+*.avi
+*.mov
+*.wmv
+*.flv
+*.mkv
+*.webm
+*.m4v
+*.mpeg
+*.mpg
+*.3gp
+*.f4v
+*.rmvb
+*.vob
+
+# 音频文件
+*.wav
+*.mp3
+*.flac
+*.ogg
+
+# 模型权重
+models/
+
+# 运行时输出
+outputs/
+uploads/
+*.log
+
+# 第三方源码
+third_party/
+
+# ASD 研究参考代码（4 个克隆仓库，含 demo 输出和大权重，可重新克隆）
+research/
+
+# Claude
+.claude/
+
+# 归档文件
+*.iso
+*.dmg
+*.rar
+*.zip
+*.gz
+
+# 文档类也默认加入
+*.pdf
+*.docx
+*.doc
+*.xlsx
+*.xls
+*.ppt
+*.pptx
+*.xlsx
+*.csv
+
+# Python venv variants
+.venv-qwen3/
+.venv-*/
+.venv-*
+server.pid
+
+# OmniVoice 隔离 venv / 根治迁移备份
+.venvs/
+.venv-omnivoice/
+.venv-kazakhtts/
+.venv-kazemotts/
+kazemotts_src/
+.venv.ntfs-bak/
+.secrets/
+cert_*.zip
+*.pem
+
+# voice bank 本地资产(大体积 wav + 频繁变化的 embeddings,不入库)
+voice_bank_profiles/
+.venv-orpheus/
+scripts/server_freezes/
+.env.bak_*
+
+# 会话规划/评审过程产物（Manus 式工作目录，不入库）
+.planning/
+
+# Codex isolated feature worktrees
+.worktrees/

zvex-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: zvex
+Version: 0.1.0
+Summary: zvex (声桥) MCP server — AI video dubbing: hand it a video URL and get back a dubbed video that keeps the original speakers' voices, billed via zvex credits
+Project-URL: Homepage, https://tts.xalhar.top
+Author: zvex
+License: MIT
+Keywords: dubbing,mcp,translation,tts,video
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=2.2.0
+Description-Content-Type: text/markdown
+
+# zvex MCP server
+
+AI video dubbing as an MCP tool: hand it a video URL, get back a fully dubbed
+video in Russian, English or Spanish — keeping the original speakers' voices
+through per-speaker voice cloning.
+
+Powered by [zvex (声桥)](https://tts.xalhar.top).
+
+The server is a thin stdio client over zvex's HTTP API, so it runs
+anywhere Python does — no GPU, no local models.
+
+## Install
+
+From a checkout:
+
+```bash
+uv tool install ./mcp/zvex
+# or: pip install ./mcp/zvex
+```
+
+## Get an API key
+
+1. Sign in at <https://tts.xalhar.top>
+2. Open **Account → API keys** and create one
+3. Copy the `zvex-…` value — it is shown **only once**
+
+Jobs are billed from the same credit balance as the web app, at a flat
+**10 credits per minute** of video. A failed job is refunded in full.
+
+## Configure your MCP client
+
+Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "zvex": {
+      "command": "zvex",
+      "env": {
+        "ZVEX_API_KEY": "zvex-your-key-here"
+      }
+    }
+  }
+}
+```
+
+| Variable | Required | Default | Meaning |
+|---|---|---|---|
+| `ZVEX_API_KEY` | yes | — | `zvex-…` key from the account page |
+| `ZVEX_BASE_URL` | no | `https://tts.xalhar.top` | API base URL (self-hosted deployments) |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `estimate_cost(minutes, tier)` | Credit cost and current balance |
+| `submit_dubbing_job(video_url, target_language, tier)` | Queue a dubbing job, returns `job_id` |
+| `get_job_status(job_id)` | Poll once; final states carry the output URLs |
+| `wait_for_job(job_id, timeout_seconds)` | Block until the job finishes |
+
+Typical flow:
+
+```
+submit_dubbing_job("https://example.com/episode-01.mp4", target_language="ru")
+  → {"job_id": 42, "credits_cost": 240, "duration_sec": 1441.0, …}
+wait_for_job(42)
+  → {"status": "completed", "final_video_url": "…", "subtitle_url": "…"}
+```
+
+### Notes
+
+- `video_url` must be a publicly reachable `http(s)` link, up to 500 MB.
+- `target_language` depends on the deployment (`ru`, `en`, `es` on the hosted
+  service).
+- `tier` is `fast`, `standard` or `professional` — it selects which features
+  are available, not the price.
+- One job per account runs at a time; a second submission returns HTTP 409.
+- Output links are served from the zvex domain and require being signed
+  in there.
+
+## Development
+
+```bash
+uv venv --python 3.11 .venv-test
+uv pip install --python .venv-test/bin/python -e .
+ZVEX_API_KEY=zvex-… .venv-test/bin/python -m zvex.server
+```

zvex-0.1.0/README.md

@@ -0,0 +1,87 @@
+# zvex MCP server
+
+AI video dubbing as an MCP tool: hand it a video URL, get back a fully dubbed
+video in Russian, English or Spanish — keeping the original speakers' voices
+through per-speaker voice cloning.
+
+Powered by [zvex (声桥)](https://tts.xalhar.top).
+
+The server is a thin stdio client over zvex's HTTP API, so it runs
+anywhere Python does — no GPU, no local models.
+
+## Install
+
+From a checkout:
+
+```bash
+uv tool install ./mcp/zvex
+# or: pip install ./mcp/zvex
+```
+
+## Get an API key
+
+1. Sign in at <https://tts.xalhar.top>
+2. Open **Account → API keys** and create one
+3. Copy the `zvex-…` value — it is shown **only once**
+
+Jobs are billed from the same credit balance as the web app, at a flat
+**10 credits per minute** of video. A failed job is refunded in full.
+
+## Configure your MCP client
+
+Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "zvex": {
+      "command": "zvex",
+      "env": {
+        "ZVEX_API_KEY": "zvex-your-key-here"
+      }
+    }
+  }
+}
+```
+
+| Variable | Required | Default | Meaning |
+|---|---|---|---|
+| `ZVEX_API_KEY` | yes | — | `zvex-…` key from the account page |
+| `ZVEX_BASE_URL` | no | `https://tts.xalhar.top` | API base URL (self-hosted deployments) |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `estimate_cost(minutes, tier)` | Credit cost and current balance |
+| `submit_dubbing_job(video_url, target_language, tier)` | Queue a dubbing job, returns `job_id` |
+| `get_job_status(job_id)` | Poll once; final states carry the output URLs |
+| `wait_for_job(job_id, timeout_seconds)` | Block until the job finishes |
+
+Typical flow:
+
+```
+submit_dubbing_job("https://example.com/episode-01.mp4", target_language="ru")
+  → {"job_id": 42, "credits_cost": 240, "duration_sec": 1441.0, …}
+wait_for_job(42)
+  → {"status": "completed", "final_video_url": "…", "subtitle_url": "…"}
+```
+
+### Notes
+
+- `video_url` must be a publicly reachable `http(s)` link, up to 500 MB.
+- `target_language` depends on the deployment (`ru`, `en`, `es` on the hosted
+  service).
+- `tier` is `fast`, `standard` or `professional` — it selects which features
+  are available, not the price.
+- One job per account runs at a time; a second submission returns HTTP 409.
+- Output links are served from the zvex domain and require being signed
+  in there.
+
+## Development
+
+```bash
+uv venv --python 3.11 .venv-test
+uv pip install --python .venv-test/bin/python -e .
+ZVEX_API_KEY=zvex-… .venv-test/bin/python -m zvex.server
+```

zvex-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "zvex"
+version = "0.1.0"
+description = "zvex (声桥) MCP server — AI video dubbing: hand it a video URL and get back a dubbed video that keeps the original speakers' voices, billed via zvex credits"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "zvex" }]
+keywords = ["mcp", "video", "dubbing", "translation", "tts"]
+dependencies = [
+    # 2.x 起 FastMCP 更名为 MCPServer(mcp.server.mcpserver),本包按 2.x API 编写
+    "mcp>=2.2.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+zvex = "zvex.server:main"
+
+[project.urls]
+Homepage = "https://tts.xalhar.top"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zvex"]

zvex-0.1.0/src/zvex/__init__.py

@@ -0,0 +1,3 @@
+"""zvex (声桥) MCP server package."""
+
+__version__ = "0.1.0"

zvex-0.1.0/src/zvex/server.py

@@ -0,0 +1,222 @@
+"""声桥( zvex / zvex ) MCP server。
+
+把声桥的 AI 视频译制能力暴露给任意 MCP 客户端(Claude Desktop / Cursor / …):
+给一个视频链接,拿回多语种配音成片。全自动——服务端一阶段(识别/翻译)完成后
+自动衔接二阶段(配音/合成),不需要人工校正环节。
+
+鉴权走声桥 API Key(网页「账户设置 → API 密钥」创建,zvex- 开头),与网页端
+共用同一个账户积分池;提交时按服务端 ffprobe 实测时长预扣,任务失败全额退款。
+
+环境变量:
+    ZVEX_API_KEY   必填,形如 zvex-xxxxxxxx
+    ZVEX_BASE_URL  可选,默认 https://tts.xalhar.top(自建部署改这里)
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import sys
+
+import httpx
+from mcp.server.mcpserver import MCPServer
+
+DEFAULT_BASE_URL = "https://tts.xalhar.top"
+_REQUEST_TIMEOUT = 120.0  # 提交含服务端下载视频,给足时间
+_CONNECT_TIMEOUT = 15.0
+_POLL_INTERVAL = 15.0
+
+# HTTP 状态码 → 给调用方(通常是 LLM)的可执行提示
+_STATUS_HINTS = {
+    401: "API key is missing, invalid, or revoked. Create a new one at "
+         "https://tts.xalhar.top/app/settings (Account → API keys).",
+    402: "Not enough credits. Top up at https://tts.xalhar.top/app/pricing.",
+    409: "Another job of this account is still running — wait for it to finish "
+         "(one concurrent job per account).",
+    400: "The request was rejected by the server; see the detail above.",
+}
+
+mcp = MCPServer("zvex")
+
+
+def _api_key() -> str:
+    key = os.getenv("ZVEX_API_KEY", "").strip()
+    if not key:
+        raise RuntimeError(
+            "ZVEX_API_KEY is not set. Create a key at "
+            "https://tts.xalhar.top/app/settings and pass it via the MCP server env."
+        )
+    return key
+
+
+def _base_url() -> str:
+    return os.getenv("ZVEX_BASE_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def _client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        base_url=_base_url(),
+        headers={"Authorization": f"Bearer {_api_key()}"},
+        timeout=httpx.Timeout(_REQUEST_TIMEOUT, connect=_CONNECT_TIMEOUT),
+    )
+
+
+# 服务端返回的是同源相对路径(/uploads/xxx.mp4),调用方(通常是别的机器上的
+# LLM)需要能直接点开的绝对 URL。
+_ABSOLUTE_KEYS = ("final_video_url", "subtitle_url", "poll")
+
+
+def _absolutize(data: dict) -> dict:
+    if not isinstance(data, dict):
+        return data
+    base = _base_url()
+    for key in _ABSOLUTE_KEYS:
+        value = data.get(key)
+        if isinstance(value, str) and value.startswith("/"):
+            data[key] = base + value
+    return data
+
+
+def _error_text(resp: httpx.Response) -> str:
+    """把 HTTP 错误翻成调用方能据以行动的文本(而不是抛异常中断会话)。"""
+    try:
+        detail = resp.json().get("detail")
+    except Exception:
+        detail = resp.text[:300]
+    text = f"HTTP {resp.status_code}: {detail}"
+    hint = _STATUS_HINTS.get(resp.status_code)
+    return f"{text} — {hint}" if hint else text
+
+
+def _dump(payload: dict) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+async def estimate_cost(minutes: float, tier: str = "standard") -> str:
+    """Estimate the credit cost of dubbing a video and check the credit balance.
+
+    Pricing is a flat 10 credits per minute for every tier (a tier only changes
+    which features are available, not the price).
+
+    Args:
+        minutes: Video length in minutes (0 < minutes <= 600).
+        tier: "fast", "standard" or "professional".
+
+    Returns:
+        JSON with credits, current balance and whether the balance is enough.
+    """
+    async with _client() as client:
+        resp = await client.get("/api/v1/estimate", params={"minutes": minutes, "tier": tier})
+    if resp.status_code >= 400:
+        return _error_text(resp)
+    return _dump(resp.json())
+
+
+@mcp.tool()
+async def submit_dubbing_job(
+    video_url: str,
+    target_language: str = "ru",
+    tier: str = "standard",
+) -> str:
+    """Submit a fully automatic dubbing job: a video URL in, a dubbed video out.
+
+    The server downloads the video, then runs speech recognition, speaker
+    separation, translation, voice cloning/TTS and composition — no manual
+    review step. Credits are charged up front based on the server-measured
+    duration and refunded in full if the job fails.
+
+    The job runs in the background: use get_job_status to poll it, or
+    wait_for_job to block until it finishes. Only one job per account may run
+    at a time (a second submission returns HTTP 409).
+
+    Args:
+        video_url: Publicly reachable http(s) video link (max 500 MB).
+        target_language: Dubbing language, e.g. "ru", "en", "es"
+            (depends on the deployment's supported set).
+        tier: "fast", "standard" or "professional".
+
+    Returns:
+        JSON with job_id, run_id, measured duration and the charged credits.
+    """
+    async with _client() as client:
+        resp = await client.post(
+            "/api/v1/jobs",
+            json={"video_url": video_url, "target_language": target_language, "tier": tier},
+        )
+    if resp.status_code >= 400:
+        return _error_text(resp)
+    return _dump(_absolutize(resp.json()))
+
+
+@mcp.tool()
+async def get_job_status(job_id: int) -> str:
+    """Check a dubbing job's status.
+
+    Once the status is "completed" the response also carries the dubbed video
+    and subtitle download URLs. "failed" carries the error and means the
+    credits were refunded.
+
+    Args:
+        job_id: The job_id returned by submit_dubbing_job.
+
+    Returns:
+        JSON with status ("processing" / "completed" / "failed" / "cancelled")
+        and, for a completed job, final_video_url and subtitle_url.
+    """
+    async with _client() as client:
+        resp = await client.get(f"/api/v1/jobs/{job_id}")
+    if resp.status_code >= 400:
+        return _error_text(resp)
+    return _dump(_absolutize(resp.json()))
+
+
+@mcp.tool()
+async def wait_for_job(job_id: int, timeout_seconds: int = 1800) -> str:
+    """Block until a dubbing job reaches a final state, then return its result.
+
+    Convenience wrapper around get_job_status for callers that just want the
+    finished video. Dubbing typically takes a small multiple of the video's own
+    length, so keep the timeout generous.
+
+    Args:
+        job_id: The job_id returned by submit_dubbing_job.
+        timeout_seconds: Give up after this long (default 1800, max 7200).
+
+    Returns:
+        JSON with the final status and, when completed, the output URLs.
+    """
+    timeout_seconds = max(30, min(int(timeout_seconds), 7200))
+    deadline = asyncio.get_running_loop().time() + timeout_seconds
+    last = ""
+    async with _client() as client:
+        while True:
+            resp = await client.get(f"/api/v1/jobs/{job_id}")
+            if resp.status_code >= 400:
+                return _error_text(resp)
+            data = resp.json()
+            last = data.get("status", "")
+            if last in ("completed", "failed", "cancelled"):
+                return _dump(_absolutize(data))
+            if asyncio.get_running_loop().time() >= deadline:
+                return _dump({
+                    "job_id": job_id,
+                    "status": last,
+                    "note": f"Still {last} after {timeout_seconds}s. "
+                            "Call wait_for_job or get_job_status again to keep waiting.",
+                })
+            await asyncio.sleep(_POLL_INTERVAL)
+
+
+def main() -> None:
+    """Entry point declared in pyproject ([project.scripts])."""
+    # stdio 传输下 stdout 是 JSON-RPC 协议通道:任何多余输出都会破坏协议。
+    # 显式把日志钉到 stderr,并关掉 httpx 的逐请求输出。
+    logging.basicConfig(stream=sys.stderr, level=logging.WARNING)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()