WorldCupVoice：开源实时体育AI解说系统，画面同步生成多语种赛事语音播报

一、WorldCupVoice是什么

WorldCupVoice 是开源实时体育AI直播解说项目，核心依托声网Agora RTC实时音视频能力，实现画面驱动的全自动赛事AI语音解说，世界杯为标杆应用场景，同时兼容足球、篮球等全部体育直播流。

项目核心定位为无障碍观赛辅助工具，而非替代真人解说：AI通过实时识别直播画面，输出人类常规解说容易忽略的球场空间、球员跑动、皮球位置等细节内容，服务视障、低视力球迷；同时面向体育自媒体、小型赛事直播间、开发者提供可私有化部署的AI解说底层方案。

项目技术栈分为两大模块：前端基于Next.js（TypeScript开发）、后端AI服务基于Python FastAPI，整体为前后端分离开源工程，单开发者维护，全部代码开放可二次修改、私有化部署，无闭源组件绑定。

二、功能特色

1. 画面原生驱动实时解说

AI后端持续采样RTC直播帧，依托视觉模型识别场上动作、球员、球路，完全基于画面内容生成口播，不单纯依赖赛事文字数据，解说内容与直播画面高度同步。

2. 多厂商TTS语音引擎自由切换

内置三套成熟语音合成方案，适配不同语种解说需求：

• OpenAI TTS：项目默认兜底方案，开箱即用无需额外音色配置；

• ElevenLabs：专业英/法体育广播音色，支持自定义热血赛事解说声线；

• Fish Audio：专为中文赛事优化，提供趣味玩梗、专业战术两套解说人设。

3. 多语言、多风格解说人设

内置标准化解说配置模板，覆盖英文专业播报、法语赛事解说、中文搞笑解说、中文深度战术解说四种角色，可通过环境变量一键切换音色与解说话术风格。

4. 精细化AI成本管控体系

内置多重机制避免AI接口无效消耗，解决长时间直播高额Token开销问题：

• 手动启停接口：Start AI/Stop AI面板一键控制AI运行；

• 观众心跳保活：无在线观众时自动暂停AI推理；

• 会话超时自动销毁：设置最大直播时长，超时强制关停；

• 独立API密钥鉴权，外部无法随意调用AI服务。

5. 完整直播配套能力

1. RTC实时音频回流：AI生成语音同步推送直播间，与原直播画面混音；

2. 同步字幕展示：直播间实时展示AI解说文字稿；

3. 直播间状态监控面板：展示AI空闲、采样、运行、停止等工作状态；

4. 自定义赛事素材库：data/matches目录存放单场赛事JSON，录入球队、球衣、球员、赛事背景，大幅提升解说精准度。

6. 多渠道RTMP直播推流兼容

支持三种主流直播源接入，适配本地测试、线上长时直播、专业导播场景：FFmpeg本地循环视频、OBS专业推流、StreamFlow云托管录播推流。

三、技术细节

3.1 整体数据流架构

直播源→RTMP推流→Agora媒体网关→Agora RTC实时频道

1. 观众端：Web前端接入RTC频道，播放直播画面+AI解说音频+实时字幕；

2. AI后端：Python服务作为RTC频道参与者，持续截取视频帧送入视觉模型，生成解说文案，经TTS转为语音，再推回RTC频道同步播放。

3.2 代码技术栈与项目占比

3.3 核心目录分工

1. app/：Next.js前端主目录，直播间页面、鉴权令牌接口、会话管理API；

2. components/：直播间UI组件、字幕面板、AI状态监控、登录大厅；

3. data/matches/：赛事配置库，单场赛事JSON模板，定义球队、球员信息；

4. lib/：解说提示词封装、赛事数据加载、多语言人设逻辑；

5. server/：Python后端核心，AI视觉推理、TTS语音合成、声网SDK交互；

6. scripts/samples：FFmpeg本地推流脚本、媒体网关流密钥生成工具；

7. 配置文件：Docker、Vercel、Railway部署配置、环境变量模板。

3.4 第三方依赖服务

1. 实时音视频：Agora声网RTC、Agora媒体网关（RTMP转RTC）；

2. 语音合成：OpenAI TTS、ElevenLabs、Fish Audio；

3. 视频处理：FFmpeg（本地视频循环推流）；

4. 部署平台：Vercel（前端）、Railway（后端容器）。

3.5 部署底层逻辑

• 前端：基于Next.js SSR，pnpm包管理器，环境变量统一管理密钥；

• 后端：Python虚拟环境+uvicorn启动FastAPI服务，独立.env.local存放密钥；

• 媒体网关：通过Agora REST API生成专属RTMP流密钥，禁止硬编码密钥；

• 安全规范：所有API密钥、流密钥、客户凭证禁止提交代码仓库，本地/线上分别配置。

四、应用场景

1. 体育无障碍观赛（核心场景）
   为盲人、低视力球迷提供精细化画面解说，补充真人解说缺失的空间、跑动、球位细节，搭建无障碍观赛直播间。

2. 自媒体小型赛事直播
   业余足球、校园联赛、民间赛事直播间，无专职解说人员时，自动生成实时赛事语音，降低直播人力成本。

3. 海外多语种体育转播
   中小型体育媒体、跨境赛事直播间，一键切换英/法/中文AI解说，低成本实现多语种全球同步直播。

4. 开发者二次开发实训
   实时音视频、多模态AI、体育视觉识别学习项目，基于开源代码改造自有体育AI解说平台。

5. 录播循环演示场景
   本地/云服务器循环播放赛事视频素材，自动生成AI解说，用于赛事短视频素材、展厅演示。

五、使用方法

5.1 本地环境前置准备

1. 工具安装：Node.js+pnpm、Python3.10+、FFmpeg、OpenSSL；

2. 第三方账号注册：Agora声网（获取AppID、证书、客户ID）、OpenAI/第三方TTS平台（获取API密钥）；

3. 自备16:9 MP4赛事视频素材（项目无内置视频，规避版权风险）。

5.2 前端部署步骤

1. 克隆仓库，执行pnpm install安装依赖；

2. 复制.env.example生成.env.local，填入声网凭证、后端地址、全局API密钥；

3. 执行pnpm dev启动前端，访问http://localhost:3000进入直播间。

5.3 Python后端部署步骤

1. 进入server目录，创建Python虚拟环境并激活；

2. 安装全部依赖pip install -r requirements.txt -r requirements-dev.txt；

3. 复制.env.example为.env.local，配置声网、TTS、全局密钥（前后端密钥保持一致）；

4. 启动服务：python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000。

5.4 生成RTMP推流地址

1. 声网控制台开启媒体网关，复制客户ID、客户密钥、区域标识；

2. 将凭证填入前端环境变量，执行pnpm run media-gateway:key生成RTMP服务器地址与流密钥；

3. 将生成地址填入OBS/FFmpeg/StreamFlow完成推流配置。

5.5 三种直播源启动方式

1. 本地FFmpeg循环视频：配置视频路径与流密钥，执行推流脚本，本地循环播放自备赛事素材；

2. OBS专业推流：自定义直播服务，填入RTMP地址、流密钥，支持摄像头、屏幕捕捉、视频文件；

3. StreamFlow云推流：VPS部署StreamFlow，上传赛事视频，配置RTMP信息实现7×24小时无人值守直播。

5.6 直播间操作流程

打开前端页面输入访问密码进入直播间，启动上游RTMP推流，点击面板Start AI开启自动解说，可实时查看字幕、AI运行状态，直播结束点击Stop AI关闭推理。

六、竞品对比

选取3款同赛道AI体育解说产品，从开源属性、部署方式、视觉驱动、多TTS、无障碍适配、成本控制六大维度对比：

七、常见问题解答（FAQ）

Q1：WorldCupVoice是否自带赛事视频素材？

A：项目仓库不包含任何比赛视频，赛事转播素材存在版权风险，需要用户自行准备16:9 MP4视频文件进行本地推流，素材版权责任由使用者自行承担。

Q2：运行项目必须使用声网Agora吗，能否更换其他RTC厂商？

A：项目底层媒体链路基于Agora Media Gateway与RTC SDK深度开发，原生不支持其他实时音视频厂商；有开发能力的用户可修改后端RTC交互代码适配ZEGO、火山引擎等其他RTC服务。

Q3：可以脱离第三方TTS，使用本地开源语音模型吗？

A：原生代码仅对接OpenAI、ElevenLabs、Fish Audio三大云端TTS接口，未内置本地语音模型；开发者可自行修改TTS调用模块，接入CosyVoice、ChatTTS等本地开源语音模型。

Q4：部署后AI解说延迟很高，该如何优化？

A：优先选择距离部署服务器最近的Agora媒体网关区域；降低后端视频帧采样频率；选用低延迟TTS服务商；同时优化推流码率、关键帧间隔，减少直播源本身延迟。

Q5：多人同时观看直播间，AI会重复多次生成解说吗？

A：不会，AI后端是RTC频道单一参与者，无论多少观众在线，仅运行一套视觉推理与TTS流程，仅当所有观众下线、心跳断开后，AI自动暂停，不会重复消耗AI接口费用。

Q6：本地部署时报错API密钥不匹配是什么原因？

A：前后端环境变量中的BACKEND_API_SECRET必须为完全一致的字符串，该密钥用于前端与后端接口鉴权，两处密钥不一致会直接拒绝AI会话操作。

Q7：项目是否支持篮球、电竞等非足球赛事？

A：底层架构无体育类型限制，仅需在data/matches目录新建对应赛事JSON文件，录入运动项目、球员、场地信息，即可适配篮球、电竞、网球等各类直播流。

Q8：免费使用这个项目会产生哪些费用？

A：项目代码本身完全免费无授权费；产生费用的环节为Agora RTC音视频服务费、OpenAI/ElevenLabs/Fish Audio TTS调用费用、云服务器部署费用，本地单机测试无服务器成本。

八、相关链接

• GitHub仓库地址：https://github.com/zicojiao/worldcupvoice

九、总结

WorldCupVoice是一套完整、可私有化落地的开源实时体育AI直播解说解决方案，依托声网RTC搭建低延迟直播链路，通过视觉模型实现画面同步的赛事语音解说，兼顾视障球迷无障碍观赛、中小赛事直播降本、多语种跨境转播等多元需求，项目技术栈完整开放、配套完善的成本管控机制，同时兼容多种推流渠道与语音合成服务商，开发者可基于MIT协议自由二次改造，无需支付软件授权费用，仅需承担第三方音视频、TTS接口基础开销，是市面上稀缺的全链路开源体育实时AI解说工程。