OBS MCP bot

OBS_24_7:AI托管教育流媒体

通过程序化OBS控制进行24/7教育Twitch广播

灵感来自Max Headroom（数字智慧）、Bob Ross（耐心教学）和PBS/NPR（公共广播模式）

项目任务

构建一个可靠的24/7流媒体基础设施，以编程方式控制OBS Studio，以保持对Twitch的连续RTMP广播。该系统处理自动故障转移、所有者中断转换、流健康监控和内容回放，实现了项目构成中定义的基本一级要求。

宪法框架: OBS_24_7宪法v1.0.0

开发状态

✅ 第1层完成 -24/7流媒体基金会直播 ✅ 第3级完成 -内容库管理（所有功能生产就绪）

当前状态：第3层100%完成-智能调度✅, 动态视频缩放✅, 74视频可播放

• ✅ 一级：OBS流媒体基础（完成-2025-10-22）-41项测试通过
• ⏳ 第二层：Twitch聊天机器人（已计划-建议下一阶段）
• ✅ 第3级：内容库管理（完成-2025-10-22）

- ✅ 第2阶段：数据库模式、模型、存储库、OBS文本覆盖——51项测试通过 - ✅ 第3阶段：具有时间块和年龄过滤的智能内容调度 - ✅ 第三阶段：保持纵横比的动态视频缩放 - ✅ 第三阶段：74个视频的元数据提取（麻省理工学院开放式课程+CS50+Blender） - ✅ 第3阶段：内容库扩展（MIT 6.00、MIT 6.006、CS50完成）

• ⏳ 第四级：高级人工智能联合主机（已计划）
• ⏳ 第5层：配套基础设施（已规划）

快速链接:

• 📜 宪法 -8个核心原则和4级优先级结构
• 📋 一级规范 -39个功能需求，4个用户故事
• 🚀 快速入门指南 -完整的设置说明
• ✅ 实施任务 -按用户故事组织的110个任务
• 🏗️ 实施计划 -架构和设计决策

技术栈

核心平台：Python 3.11+（用于并发监控的异步）

依赖项:

• obs-websocket-py -通过WebSocket协议进行OBS控制
• FastAPI + uvicorn -运行状况API终结点
• structlog -JSON结构化日志记录
• aiosqlite -SQLite异步状态持久化
• pydantic -配置管理和数据验证

基础设施:

• Docker容器化部署
• SQLite用于度量和状态持久性
• OBS Studio 29+，带OBS websocket 5.x插件

先决条件

所需软件

1. OBS工作室29.0+ 使用obswebsocket5.x插件

- 下载：https://obsproject.com/download - 在工具中启用WebSocket服务器→ WebSocket服务器设置

1. Docker&Docker编写

   docker --version
   docker-compose --version

1. Python 3.11+ （用于地方发展）

   python3 --version

1. Twitch账号 带流键

- 获取流密钥：https://dashboard.twitch.tv/settings/stream

系统资源

• CPU:4+核心推荐（OBS编码+编排）
• RAM：最低8GB，建议16GB
• 网络：1080p流媒体的最低上传速度为10 Mbps
• 磁盘：10GB用于日志、状态持久性、故障转移内容

快速开始

看它跑（5分钟）

有关完整的设置说明，请参阅 快速入门指南.

快速概述：

# 1. Clone and setup
git clone https://github.com/TortoiseWolfe/OBS_MCP_bot.git
cd OBS_MCP_bot
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Configure (edit config/settings.yaml)
# - Set OBS WebSocket connection details
# - Configure owner sources for interrupt detection
# - Set failover content path

# 3. Start OBS Studio (don't click "Start Streaming" - system controls that)

# 4. Run the orchestrator
python -m src.main

# 5. Check health API
curl http://localhost:8000/health | jq

内容库管理（第3层）

状态：100%完成（82项任务中的82项）-所有功能生产就绪

内容库系统通过自动归因、智能调度和动态视频缩放管理CC许可的教育视频，实现全天候流式传输。

特性

• 智能内容调度：基于时间的内容块确保内容适合年龄

- kids-after-school/：工作日下午3点至6点（创意编码，适合初学者） - professional-hours/：工作日上午9点至下午3点（高级CS、专业工具） - evening-mixed/：每天晚上7-10点（算法、问题解决） - general/：所有时间（基础CS内容）

• 动态视频缩放：自动保持纵横比缩放以适应OBS画布

- 麻省理工学院开放式课程480x360→ 缩放3.0倍至1440x1080 - CS50 1280x720→ 缩放1.5倍至1920x1080 - 保留纵横比，将视频居中，根据需要添加信箱

• 自动归因：根据CC许可证要求，实时文本覆盖了信用内容创作者

• 许可证合规性：所有内容均正确记录在CC-BY-NC-SA或CC-BY许可证中

- 麻省理工学院开放式课程（12节Python讲座） - 哈佛大学CS50（6场入门讲座） - 可汗学院（规划中） - Big Buck Bunny（故障转移内容）

快速设置

# 1. Download educational content (WSL2 terminal, NOT Docker)
cd /home/turtle_wolfe/repos/OBS_bot
source .venv/bin/activate
pip install yt-dlp ffmpeg

# 2. Download content (manual CDN downloads recommended)
cd scripts
./download_all_content.sh  # Or download from CDN mirrors

# 3. Extract metadata
python3 add_content_metadata.py

# 4. Verify in OBS
# Open media source → Browse to:
# \\wsl.localhost\Debian\home\turtle_wolfe\repos\OBS_bot\content\failover\default_failover.mp4

# 5. Start orchestrator (Docker)
docker compose -f docker-compose.prod.yml up -d obs-orchestrator

文档

• 安装指南: scripts/SETUP.md -下载和配置
• 建筑: 文档/内容_架构.md -WSL2/Docker/OBS数据流
• 故障排除: docs/CONTENT_TRUBLESHOOTING.md -常见问题和解决方案
• 内容自述: 内容/README.md -许可证合规性和归属
• 规格说明: specs/003内容库管理/spec.md -完整的功能规格

当前内容库

• 74视频 跨越6个来源（约70-75小时的内容）
• 约37GB 磁盘使用率（MIT OCW+CS50+故障转移）
• 所有可播放的视频 具有自动归因覆盖功能
• 遵守宪法：针对适合年龄段的内容进行时间块过滤

后续步骤

1. 下载其他内容来源（可汗学院、会议讲座）
2. 启用字幕覆盖（数据库模式就绪，MCP配置）
3. 扩展到50+小时的教育内容

路线图

第1层：OBS流媒体基础✅ 完成

状态：生产准备就绪（2025-10-22）

• 采用程序化OBS控制的全天候自动流媒体
• 流健康监控和自动故障转移
• 所有者直播接管，过渡时间\1%）

实现工作流

此项目使用 规格套件 在人工智能的帮助下进行规范驱动的开发。

已完成的阶段

1. ✅ /speckit.constitution -确立了8项核心原则和1-4级优先结构
2. ✅ /speckit.specify -创建了包含39个功能要求的Tier 1规范
3. ✅ /speckit.clarify -解决了4个关键的架构问题
4. ✅ /speckit.plan -生成的体系结构、数据模型和API合同
5. ✅ /speckit.tasks -创建了110个按用户故事组织的实施任务
6. ✅ /speckit.analyze -验证了跨工件一致性（零关键问题）

当前阶段：实施

MVP范围：44项任务（第一阶段设置+第二阶段基础+第三阶段US1）

推荐方法:

1. Sprint 1：完整MVP（US1）-全天候流媒体工作
2. Sprint 2：添加US2（所有者中断）
3. Sprint 3：添加US3（故障转移和恢复）
4. Sprint 4：添加US4（健康监测）+波兰语

看 tasks.md 用于完整的任务分解和依赖关系图。

项目结构

规划工件（规格/）

specs/001-tier1-obs-streaming/
├── spec.md              # Feature specification with 39 functional requirements
├── plan.md              # Implementation plan with architecture decisions
├── tasks.md             # 110 implementation tasks organized by user story
├── research.md          # Technology stack research and decisions
├── data-model.md        # 9 domain entities with SQLite schema
├── quickstart.md        # Complete development setup guide
├── contracts/
│   └── health-api.yaml  # OpenAPI 3.0 specification for health API
└── checklists/
    ├── requirements.md  # Spec quality validation (PASSED)
    └── tasks.md         # Task completeness validation (PASSED)

源代码结构（计划中）

src/
├── models/              # 9 domain entities (StreamSession, HealthMetric, etc.)
├── services/            # Business logic services
│   ├── obs_controller.py
│   ├── stream_manager.py
│   ├── health_monitor.py
│   ├── failover_manager.py
│   ├── owner_detector.py
│   ├── content_scheduler.py
│   └── startup_validator.py
├── api/
│   └── health.py        # FastAPI health endpoints
├── persistence/
│   ├── db.py            # SQLite schema and connection
│   └── repositories/    # CRUD operations
├── config/
│   ├── settings.py      # Pydantic configuration management
│   └── defaults.py      # Default OBS scene definitions
└── main.py              # Entry point and orchestration

tests/
├── unit/                # Service unit tests
├── integration/         # OBS integration tests
└── contract/            # API contract tests

状态：源代码尚未实现-结构在plan.md中定义

开发命令

SpecKit Slash命令（克劳德代码）

• /speckit.implement -从tasks.md执行实现任务
• /speckit.analyze -重新运行跨工件一致性分析
• /speckit.checklist -生成质量检查表

直接CLI使用

./specify --help           # Show SpecKit help
./specify check            # Check required tools
./specify update           # Update SpecKit to latest version

宪法原则

一级范围：OBS+Twitch流媒体基金会（封锁所有其他层）

此实现满足：

• 原则I（广播连续性）：24/7流媒体、故障转移、自动恢复
• 原则四（业主响应性）：10秒所有者中断转换
• 原则五（系统可靠性）：Docker部署、优雅降级、监控

不在一级范围内:

• ❌ 内容决策引擎（第2层：智能内容管理）
• ❌ AI教学人格（第三层：AI教学人格）
• ❌ Discord集成（第4层：支持基础设施）

看 宪法 完整的原则定义和层次规范。

成功标准

在以下情况下，系统符合Tier 1要求：

• SC-001：任何7天内99.9%的正常运行时间（最多30秒的停机时间）
• SC-002：启动后60秒内自动开始流媒体播放
• SC-003：所有者转换在≤10秒内完成（95%的转换）
• SC-004：在任何7天的时间内，零死空气>5秒
• SC-005：故障转移在5秒内恢复（成功率100%）
• SC-006：正常运行期间丢帧\<1%
• SC-007：内容转换\<2秒
• SC-008：正常运行时间指标精确到1秒以内
• SC-009：所有者每天可以中断5次以上而不会降级

看 规格.md 完整的成功标准定义。

Git工作流

承诺什么

提交这些:

• 中的所有文件 specs/ （规范、计划、任务）
• .specify/memory/constitution.md （项目构成）
• docker-compose.yml, Dockerfile, requirements.txt
• src/ 和 tests/ （实施时）
• config/ 示例和文档
• 这 README.md

不要承诺 （已在.gitignore中）：

• .speckit/ -SpecKit安装文件（自动重新生成）
• .venv/ -Python虚拟环境
• data/ -SQLite数据库和状态文件
• logs/ -结构化日志输出
• __pycache__/ -Python字节码

分支策略

• main -规划工件和文件
• 001-tier1-obs-streaming -一级实施（110项任务）
• 未来的功能分支如下 NNN-feature-name 模式

故障排除

飞行前验证失败

错误: obs_connectivity: fail

• ✅ OBS工作室正在运行
• ✅ WebSocket服务器已启用（工具→ WebSocket服务器设置）
• ✅ 可到达4455港： nc -zv localhost 4455

错误: failover_content: fail

• ✅ 故障转移文件存在并且可以播放
• ✅ 路径在 config/settings.yaml 是正确的

看 快速入门指南 查看完整的故障排除部分。

Docker问题

“无法连接到Docker守护进程”

• 确保Docker桌面正在运行

文件权限错误

• 跑 ./specify update 清洁并重新安装SpecKit

了解更多

• OBS工作室文档
• obs websocket协议
• Twitch流媒体指南
• SpecKit文档
• FastAPI文档

许可证

\[指定许可证-例如MIT、Apache 2.0或指向许可证文件的链接\]

______________________________________________________________________

版本：1.1.0（完成第1层+完成第3层第3阶段主要功能） 最后更新: 2025-10-22 维护者：\[频道所有者\] 框架：GitHub的SpecKit+Rasmus Widing的PRP（产品需求提示）