companion-module-cuipi-media-control

Bitfocus Companion 官方模块 - 用于控制脆皮媒体控制应用

📖 简介

这是一个用于 Bitfocus Companion 的官方连接模块，可以控制脆皮媒体控制 (Cuipi Media Control) 应用程序，实现对PPT、音乐、视频、图片等媒体文件的远程控制。

✨ 功能特性

媒体播放控制

• 按索引播放任意媒体文件
• 按类型和编号播放 (PPT、图片、音乐、视频)
• 支持动态媒体库

PPT演示控制

• ▶️ 开始/结束放映
• ➡️ 下一页/上一页
• ⏮️ 第一页/最后一页
• 🎯 跳转到指定页码

基础控制

• ⏸️ 暂停
• ⏹️ 停止
• ❄️ 冻结画面控制

实时反馈

• ✅ 媒体播放状态 (按钮变色)
• ✅ PPT放映状态
• ✅ 服务器在线状态
• ✅ 冻结帧状态

动态变量

• $(cuipi-media:current_media_name) - 当前媒体名称
• $(cuipi-media:current_media_type) - 当前媒体类型
• $(cuipi-media:current_media_index) - 当前媒体索引
• $(cuipi-media:media_total) - 媒体总数
• $(cuipi-media:server_running) - 服务器运行状态
• $(cuipi-media:uptime) - 运行时间

📋 系统要求

脆皮媒体控制应用

• macOS: 10.14+
• 应用版本: v1.0.0+
• 下载地址: GitHub Release

Companion

• 版本: v3.0.0+
• 平台: Windows / macOS / Linux

🚀 快速开始

1. 安装脆皮媒体控制应用

1. 下载并安装脆皮媒体控制应用
2. 启动应用，确保服务器正在运行
3. 默认监听地址: localhost:8080

2. 在Companion中添加连接

1. 打开 Bitfocus Companion
2. 点击 Connections 标签
3. 点击 + Add Connection
4. 搜索 "Cuipi Media Control" 或 "脆皮媒体控制"
5. 点击 Add

3. 配置连接

| 配置项 | 说明 | 默认值 | |--------|------|--------| | 主机地址 | 脆皮媒体控制运行的地址 | localhost | | HTTP端口 | HTTP API 端口 | 8080 | | 状态更新间隔 | 轮询间隔(毫秒) | 1000 |

4. 使用预设按钮

模块提供了丰富的预设按钮，可以直接拖拽使用：

PPT控制

• 🟢 开始放映
• 🔴 结束放映
• 🔵 下一页
• 🔵 上一页
• 🔵 第一页
• 🔵 最后一页

快速播放

• 播放媒体1-10 (自动按钮反馈)

基础控制

• ⏸️ 暂停
• ⏹️ 停止

冻结控制

• ❄️ 设置冻结帧
• 🔥 清除冻结帧

🎯 使用示例

示例1: 创建PPT控制页面

1. 在 Companion 中创建新页面
2. 从预设中拖入:
   • "开始放映" 按钮
   • "下一页" 按钮
   • "上一页" 按钮
   • "结束放映" 按钮
3. 按钮会自动根据PPT状态变色

示例2: 创建媒体库快速访问

1. 拖入 "播放媒体1" 到 "播放媒体10" 预设
2. 当对应媒体播放时,按钮自动变绿
3. 可以在按钮上显示媒体名称: $(cuipi-media:current_media_name)

示例3: 使用变量显示状态

在按钮文本中使用变量:

正在播放:
$(cuipi-media:current_media_name)

类型: $(cuipi-media:current_media_type)
索引: $(cuipi-media:current_media_index)

🔧 高级配置

自定义动作

除了预设,你还可以手动创建按钮并配置动作:

播放特定编号的PPT

Action: 播放PPT (按编号)
PPT编号: 3

跳转到PPT特定页

Action: PPT - 跳转到指定页
页码: 5

反馈配置

在按钮的 Feedbacks 中添加:

显示当前播放的媒体

Feedback: 媒体正在播放
媒体索引: 2
样式: 背景色 #00FF00

📡 API接口

模块通过HTTP API与脆皮媒体控制通信,主要端点:

GET /api/play/{index}          - 播放指定索引的媒体
GET /api/ppt/{number}           - 播放指定编号的PPT
GET /api/image/{number}         - 播放指定编号的图片
GET /api/music/{number}         - 播放指定编号的音乐
GET /api/video/{number}         - 播放指定编号的视频
GET /api/ppt/control/start      - 开始放映
GET /api/ppt/control/stop       - 结束放映
GET /api/ppt/control/next       - 下一页
GET /api/ppt/control/prev       - 上一页
GET /api/ppt/control/first      - 第一页
GET /api/ppt/control/last       - 最后一页
GET /api/ppt/goto/{slide}       - 跳转到指定页
GET /api/pause                  - 暂停
GET /api/stop                   - 停止
GET /api/freeze/set             - 设置冻结帧
GET /api/freeze/clear           - 清除冻结帧
GET /api/status                 - 获取状态
GET /api/media/list             - 获取媒体列表

🐛 故障排除

连接失败

1. 检查应用是否运行

   • 确保脆皮媒体控制应用已启动
   • 检查应用界面是否显示"服务器运行中"

2. 检查端口配置

   • 默认端口: 8080
   • 如果修改过端口,确保Companion配置一致

3. 检查防火墙

   • macOS可能会阻止连接
   • 在"系统偏好设置 > 安全性与隐私 > 防火墙"中允许应用

按钮无反应

1. 检查连接状态

   • Companion界面中连接状态应显示为 ✅ OK

2. 查看日志

   • 在 Companion 的 Log 标签中查看错误信息

3. 测试API

   • 在浏览器中访问: http://localhost:8080/api/status
   • 应该返回JSON格式的状态信息

🤝 贡献

欢迎提交问题和功能建议:

• GitHub Issues: https://github.com/cuipi/companion-module-cuipi-media
• 讨论区: https://github.com/cuipi/companion-module-cuipi-media/discussions

📄 许可证

MIT License

🙏 致谢

• Bitfocus Companion - 优秀的控制台软件
• Companion 开发社区的支持和帮助

作者: 脆皮工作室
版本: 1.0.0
更新日期: 2025-01-08