使用说明

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插件

先决条件

所需软件

OBS工作室29.0+ 使用obswebsocket5.x插件
- 下载：https://obsproject.com/download
- 在工具中启用WebSocket服务器→ WebSocket服务器设置

Docker&Docker编写

docker --version
docker-compose --version

Python 3.11+ （用于地方发展）
```
python3 --version
```
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+故障转移）
所有可播放的视频 具有自动归因覆盖功能
遵守宪法：针对适合年龄段的内容进行时间块过滤

后续步骤

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

路线图

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

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

采用程序化OBS控制的全天候自动流媒体
流健康监控和自动故障转移
所有者直播接管，过渡时间<10s
用于操作可见性的FastAPI健康端点

第二层：Twitch聊天机器人⏳ 下一个

聚焦：观众参与度和人工智能交互

IRC连接到Twitch聊天（读/写消息）
基本机器人命令（！help、！uptime、！commands、！ask）
使用Claude API的AI阳性反应
速率限制和队列管理（50-100个并发观众）
基本聊天审核（超时处理、命令冷却）
为什么选择Tier 2：不需要内容库的独立功能，立即具有查看器价值

第3层：内容库管理✅ 完成

聚焦：具有CC许可视频管理的教育内容库

✅ 第二阶段完成：数据库模式、域模型、存储库、OBS文本覆盖（51个测试）
- 4个数据库表： license_info, content_sources, content_library, download_jobs
- 完全验证的Pydantic模型（覆盖率97%）
- 具有CRUD操作的存储库层（覆盖率95%）
- 用于属性覆盖的OBS文本源代码控制
- CC许可证种子数据（麻省理工学院开放式课程、CS50、可汗学院、Blender）
✅ 第3阶段完成 (2025-10-22):
- 智能内容调度：基于时间的内容块（儿童下午3点至6点，专业人士上午9点至3点，晚上7点至10点），年龄适当性过滤，基于优先级的选择
- 动态视频缩放：自动保持纵横比缩放以适应OBS画布（1920x1080），支持多种分辨率（480x360→ 3.0x比例尺，1280x720→ 1.5x比例）
- 元数据抽取：ffprobe集成，用于持续时间、文件大小和视频分辨率提取
- 74视频准备就绪MIT 6.0001（12次阅读），MIT 6.00（24次阅读），MIT 6.006（24次阅读），CS50（11次阅读），Big Buck Bunny（故障转移）
- WSL2 → OBS访问的Windows UNC路径映射
- 下载用于内容扩展的自动化脚本

第四级：高级人工智能联合主持人⏳ 计划

聚焦：具有视觉和深厚知识的情境感知人工智能

计算机视觉查看当前流内容（OBS输出截图）
带有教育内容索引的RAG系统（内置于Tier 3中）
引用实时内容的上下文感知聊天响应
TTS语音合成在人工智能叙事教学中的应用
独立教学能力（30分钟以上的自主课程）
Max Headroom+鲍勃·罗斯个性融合

第5层：配套基础设施⏳ 计划

聚焦：分析、监控和社区

用于流分析的Web仪表板（Grafana/Prometheus）
Discord警报和通知
高级日志记录和决策跟踪
视频点播/剪辑生成和存档

用户故事（第1层）

US1-继续教育广播（P1） -17项任务

飞行前验证后，全天候流媒体自动启动
自动内容播放和转换（<2秒间隔）
99.9%的正常运行时间目标（每周最多30秒的停机时间）

US2-业主直播接管（P2） -14任务

源检测在10秒内触发所有者实时场景
当所有者停用源时，自动恢复到自动内容
平滑过渡，具有音频淡入淡出和视觉效果

US3-自动故障切换和恢复（P3） -18任务

内容故障检测和5秒内自动故障转移
OBS碰撞检测和自动重启尝试
RTMP重新连接逻辑，重试间隔为10秒

US4-流健康监测（P4） -20个任务

每10秒收集一次健康指标（比特率、丢帧、CPU）
用于实时运行状况快照和正常运行时间报告的REST API
质量检测和警报下降（丢帧率>1%）

实现工作流

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

已完成的阶段

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

当前阶段：实施

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

推荐方法:

Sprint 1：完整MVP（US1）-全天候流媒体工作
Sprint 2：添加US2（所有者中断）
Sprint 3：添加US3（故障转移和恢复）
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

了解更多

许可证

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

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