MCP Media Transcription Pipeline (媒体内容语音转文本处理流程)

English | 中文

概述

MCP Media Transcription Pipeline 是一套用于多源视频内容深度处理的服务组件。本组件的核心职能是从广域的流媒体源（包括但不限于 YouTube, Bilibili, TikTok, Twitter 等）中抓取音频数据，并将其通过配置的多个尖端语音识别（STT）服务提供商转化为可编辑的文本内容。该系统高度灵活，允许用户根据预设的密钥管理策略，在 Deepgram、Gladia、Speechmatics 和 AssemblyAI 等引擎间进行智能调度和切换。(此项目旨在作为熟悉 MCP 架构设计、开发流程及部署实践的初始参考实现)

核心能力

覆盖超过1000个主流视频站点的内容捕获与音频分离功能
内建多引擎转录能力支持，包括：
Deepgram
Gladia
Speechmatics
AssemblyAI
动态服务选择机制，依据环境变量中密钥的可用性自动优化引擎调用路径
采用异步架构设计，以最大化系统吞吐量和并发处理效率
全面的异常捕获、详尽的事件日志记录体系
内置说话人身份分离（Diarization）功能
× 暂不支持本地部署模型（CPU/GPU加速）的集成运行

结构速览

. ├── src/ # 核心业务逻辑源文件区 │ ├── services/ # 各项具体服务实现模块 │ │ ├── download/ # 媒体流捕获服务 │ │ └── transcription/ # 语音识别服务实现 │ ├── main.py # 启动及入口控制点 │ └── init.py # Python 包标识文件 ├── config/ # 外部化配置参数存放区 ├── test.py # 自动化验证脚本 ├── run.py # 服务启动封装脚本 ├── pyproject.toml # 项目元数据与依赖声明文件 ├── uv.lock # UV 包管理器依赖版本锁定快照 └── .env # 敏感凭证和环境参数存储（示例）

演示快照

部署初始化指南

1. 环境工具准备 (UV 安装)

若您的环境中尚未安装 uv 包管理器，可执行以下命令获取： bash curl -LsSf https://astral.sh/uv/install.sh | sh

2. 代码仓库获取：

bash git clone https://github.com/R-lz/mcp-video-digest.git cd mcp-video-digest

3. 虚拟环境构建与激活：

bash uv venv source .venv/bin/activate # 适用于类 Unix 系统

或

.venv\Scripts\activate # 适用于 Windows 系统

4. 依赖包安装：

bash uv pip install -e .

附注：在初次使用 Speechmatics SDK 时，调试过程遇到若干 HTTP 请求相关挑战（问题根源在于开发者对请求机制的理解不足），因此最终采用了其官方提供的专用 SDK 库进行集成。

配置要点

在项目根目录下，请复制或重命名 .env.example 文件为 .env，并在其中填入您的密钥凭证： bash mv .env.example .env

# 填写您的凭证信息 DEEPGRAM_API_KEY=your_deepgram_key GLADIA_API_KEY=your_gladia_key SPEECHMATICS_API_KEY=your_speechmatics_key ASSEMBLYAI_API_KEY=your_assemblyai_key

要求：至少需提供一个有效 API 密钥方可启动。

服务引擎调用优先级设置：
Deepgram（对中文内容的转录效果通常被认为更优，建议首选）
Gladia
Speechmatics
AssemblyAI

操作流程

服务启动指令： bash uv run src/main.py

或以调试模式启动： bash UV_DEBUG=1 uv run src/main.py

服务接口调用示例（通过 MCP 客户端）： python from mcp.client import MCPClient

async def process_video(): client = MCPClient() result = await client.call( "get_video_content", url="https://www.youtube.com/watch?v=video_id" ) print(result)

客户端通过 Server-Sent Events (SSE) 连接示例配置： bash { "mcpServers": { "video_digest": { "url": "http://:8000/sse" } } }

亦可在客户端调用时动态注入特定密钥

"env": { "DEEPGRAM_API_KEY":"your_deepgram_key" }

针对 STDIO 模式的启动命令修改尚未经过严格验证和测试。请参考 MCP 官方文档了解标准输入输出的交互细节。

验证测试

执行系统内置的自动化测试套件： bash uv run test.py

或

python test.py

测试脚本将依次执行以下验证步骤： - 校验环境变量的设置和读取是否正确 - 验证 YouTube 媒体流的下载功能可靠性 - 分别对所有集成转录引擎进行连通性和功能性测试 - 模拟端到端的完整视频处理流水线测试

开发者指南

接入新的转录引擎：
请在 src/services/transcription/ 路径下创建新的服务实现文件
确保新类继承自 BaseTranscriptionService 抽象基类
必须实现 transcribe 核心处理方法
调整或扩展媒体捕获器：
针对 src/services/download/ 目录进行修改或新增下载器模块
参照 YouTubeDownloader 类的结构进行继承或重构

依赖与包管理

引入新依赖包时，请使用 uv pip install package_name 命令
定期导出当前依赖列表至标准文件：uv pip freeze > requirements.txt
项目依赖定义集中于 pyproject.toml，版本锁定文件为 uv.lock

异常处理策略

本服务已部署机制以应对以下常见故障场景： - 启动时关键 API 密钥缺失或被认证服务拒绝 - 源视频文件的网络捕获作业失败 - 音频流数据在传输至 STT 服务过程中中断或失败 - 通讯层面的网络连接中断问题 - 目标服务提供商的速率限制或配额耗尽

重要提示

确保系统具备足够的瞬时磁盘空间，以缓存下载和处理过程中的中间文件。
务必审慎监控各 STT 服务商的 API 调用频率与费用限额。
推荐环境配置：Python 版本 3.11 或更高版本。
临时生成的文件将在任务结束后自动进行清理销毁。
选用 uv 进行依赖管理可显著提升安装速度和环境隔离的精确性。
针对 YouTube 视频，内容下载可能需要用户身份验证凭证。您可将浏览器导出的 cookies 文件命名为 cookies.txt 并置于项目根目录，或利用 cookies-from-browser 等工具辅助 yt-dlp 完成授权。

语音转文本服务商的免费额度与定价信息

Speechmatics：每月提供8小时的免费处理时长 - 费用详情
Gladia：每月提供10小时的免费处理时长 - 费用详情
AssemblyAI：总计提供50美元的起始免费试用额度 - 费用详情
Deepgram：总计提供200美元的起始免费试用额度 - 费用详情

以上数据仅供参考，请以官方公布信息为准。

软件许可

本项目采用宽松的 MIT 协议进行发布和使用。 WIKIPEDIA: XMLHttpRequest (XHR) 是一种以 JavaScript 对象形式存在的应用程序接口，其方法允许应用程序从网页浏览器向 Web 服务器发送 HTTP 请求。这些方法使得基于浏览器的应用能够在页面加载完成后与服务器通信并接收回传信息。XMLHttpRequest 是 Ajax 编程范式中的一个核心组成部分。在 Ajax 出现之前，超链接和表单提交是与服务器交互的主要手段，且通常会导致当前页面被新内容完全替换。

== 发展历程 == XMLHttpRequest 的基本构想最早由微软 Outlook 的开发人员于 2000 年提出。该概念随后在 Internet Explorer 5 浏览器（1999 年发布）中得以实现。然而，早期的实现并未直接使用 XMLHttpRequest 这个标识符，而是通过 ActiveXObject("Msxml2.XMLHTTP") 和 ActiveXObject("Microsoft.XMLHTTP") 进行实例化。直到 Internet Explorer 7 (2006 年) 发布后，所有主流浏览器才统一采用 XMLHttpRequest 这一标准标识。如今，该标识已成为所有主流浏览器事实上的标准，包括 Mozilla 的 Gecko 渲染引擎（2002 年）、Safari 1.2 (2004 年) 以及 Opera 8.0 (2005 年)。

=== 标准化进程 === 万维网联盟 (W3C) 于 2006 年 4 月 5 日发布了 XMLHttpRequest 对象的第一个工作草案规范。2008 年 2 月 25 日，W3C 发布了 Level 2 工作草案规范。Level 2 标准新增了用于事件进度监控、支持跨域请求以及处理字节流的方法。到 2011 年底，Level 2 的增强特性被合并回最初的核心规范。自 2012 年末起，WHATWG 接管了该规范的维护工作，并使用 Web IDL 持续维护一个动态的文档。

== 应用方法 == 通常情况下，使用 XMLHttpRequest 发起请求需要遵循以下几个编程步骤。

通过调用构造函数创建一个 XMLHttpRequest 对象：调用 "open" 方法来定义请求的方法类型、指定目标资源 URI，并选择同步或异步操作模式：对于异步请求，必须设置一个事件监听器，以便在请求状态发生变化时得到通知：通过调用 "send" 方法来启动实际的请求：在事件监听器中响应状态变化。如果服务器返回了响应数据，默认情况下它会被存储在 "responseText" 属性中。当对象完成响应处理时，其状态会变为 4（即 "done" 状态）。除了上述基本步骤外，XMLHttpRequest 提供了诸多选项来精细控制请求的发送方式和响应的处理流程。可以向请求中添加自定义的 HTTP 头部字段，以指导服务器如何处理该请求；数据也可以通过在 "send" 调用中提供内容被上传至服务器。响应内容可以被解析为 JSON 格式，从而直接转换为可用的 JavaScript 对象，或者在数据尚未完全到达时就进行渐进式处理。此外，请求可以被提前中止，或者设置一个超时时间以防请求无限期挂起。

== 跨域请求的限制 ==

在万维网的早期发展阶段，人们发现直接从一个域名的网页向另一个域名发起请求存在安全阻碍，这为后续的跨域解决方案埋下了伏笔。

mcp-media-transcription-pipeline

Author

R-lz

Quick Info

Actions

Tags