OBS Script Workspace

本仓库用于存放个人编写的 OBS Studio Python 脚本，以及与之配套的技能参考文档。

环境要求：OBS Studio 28+，Python 3.8+。

项目结构

obs_script/
├── README.md                           # 本文件
├── .gitignore                          # Git 排除规则
├── skills/                             # Agent Skill 目录
│   ├── obs-studio-scripting/
│   │   └── SKILL.md                    # OBS 脚本编写技能速查
│   └── obs-script-review/
│       └── SKILL.md                    # OBS 脚本审查修复技能
├── scripts/                            # 脚本目录
│   └── current_time_display/           # 当前时间显示插件
│       ├── current_time_display.py
│       └── README.md
└── Streaming-Software-Scripting-Reference/  # 第三方参考仓库（已忽略）

已有脚本

• current_time_display — 在场景中实时显示当前时间的文本源插件，支持多种时间格式和样式配置。详见 scripts/current_time_display/README.md。

使用 Skill 辅助开发脚本

本项目配套了两个 QoderWork Agent Skill，可用于快速开发、审查和修复 OBS 脚本。

已安装的 Skill

Skill	用途	触发场景
obs-studio-scripting	编写 OBS Python 脚本	当需要创建新脚本、管理场景/源/滤镜/热键/事件时
obs-script-review	审查和修复脚本崩溃问题	当脚本导致 OBS 崩溃、出现内存泄漏、或需要排查 API 误用时

如何使用 Skill 创建新脚本

在 QoderWork 中，直接描述你想要的 OBS 脚本功能，系统会自动调用 obs-studio-scripting skill 来生成代码。例如：

"帮我创建一个 OBS 脚本，每隔 30 秒自动切换一次场景"

"写一个 OBS 插件，按下热键时隐藏/显示某个源"

"创建一个脚本，在推流开始时自动播放音效"

Skill 会自动注入 OBS Python API 的最佳实践，包括：

• 正确的生命周期钩子（script_load、script_update 等）
• 内存管理（引用计数与释放规则）
• UI 属性面板构建
• 热键注册与保存
• 事件与信号监听

如何使用 Skill 审查现有脚本

如果你的脚本导致 OBS 崩溃、内存泄漏或行为异常，直接让 QoderWork 审查代码：

"检查一下这个脚本为什么会让 OBS 崩溃"

"这段代码有内存泄漏吗？"

"帮我优化这个脚本的稳定性"

obs-script-review skill 会自动执行以下检查清单：

• obs_source_create_private 与全局查找是否冲突
• 是否存在对 obs_scene_from_source 返回值误调用 obs_scene_release
• 定时器是否重复注册
• 对象创建后是否正确释放
• 颜色格式（RGB → BGRA）是否正确转换
• 字体对象字段名是否正确

开发规范

• 必须释放的对象：obs_get_source_by_name → obs_source_release、obs_data_create → obs_data_release、obs_enum_sources → source_list_release
• 禁止释放：obs_scene_from_source 和 obs_scene_find_source 的返回值（不增加引用计数）
• 定时器：每次 script_update 中先 timer_remove 再 timer_add
• 颜色格式：UI 颜色选择器返回 RGB，text_gdiplus 等源需要 BGRA，需做转换

参考资源

• OBS Scripting Docs
• Frontend API
• Properties Reference
• Streaming-Software-Scripting-Reference — 本项目 Skill 与脚本API参考的支撑来源（本地副本已加入 .gitignore）