name: jf-open-pro-device-osd
description: 杰峰设备 OSD 水印设置技能（开发版）。支持设备实时画面水印设置，可配置通道标题、时间标题、隐私区域等 OSD 叠加属性。
metadata:
version: 1.0.0
author: JFTech
category: video
tags:
triggers:
prerequisites:
region:
支持杰峰设备 OSD（On-Screen Display）水印配置功能：
| 变量名 | 说明 | 默认值 | 必需 |
|--------|------|--------|------|
| JF_UUID | 开放平台用户 uuid | - | ✅ |
| JF_APP_KEY | 开放平台应用 appKey | - | ✅ |
| JF_APP_SECRET | 开放平台应用密钥 | - | ✅ |
| JF_MOVE_CARD | 移动卡标识（用于签名） | 2 | ✅ |
| JF_DEVICE_SN | 设备序列号 | - | ✅ |
| JF_DEVICE_TOKEN | 设备接口访问令牌 | - | ✅ |
| JF_ENDPOINT | API 接入地址 | api-cn.jftechws.com | ❌ |
| 功能 | 地址 | 方法 |
|------|------|------|
| 获取单行 OSD 配置 | POST /gwp/v3/rtc/device/getconfig/{token} | POST |
| 设置单行 OSD 配置 | POST /gwp/v3/rtc/device/setconfig/{token} | POST |
| 获取多行 OSD 配置 | POST /gwp/v3/rtc/device/getconfig/{token} | POST |
| 设置多行 OSD 配置 | POST /gwp/v3/rtc/device/setconfig/{token} | POST |
API: POST /gwp/v3/rtc/device/getconfig/{token} / setconfig/{token}
Name: AVEnc.VideoWidget
配置项：
| 字段 | 类型 | 说明 |
|------|------|------|
| ChannelTitle | object | 通道标题配置 |
| ├─ Name | string | 通道名称 |
| ├─ SerialNo | string | 设备序列号 |
| ChannelTitleAttribute | object | 通道标题属性 |
| ├─ BackColor | string | 背景色（RGBA） |
| ├─ FrontColor | string | 前景色（RGBA） |
| ├─ EncodeBlend | bool | 编码叠加使能 |
| ├─ PreviewBlend | bool | 预览叠加使能 |
| ├─ RelativePos | int[] | 相对位置坐标 [x1,y1,x2,y2] |
| TimeTitleAttribute | object | 时间标题属性 |
| ├─ BackColor | string | 背景色 |
| ├─ FrontColor | string | 前景色 |
| ├─ EncodeBlend | bool | 编码叠加使能 |
| ├─ PreviewBlend | bool | 预览叠加使能 |
| ├─ RelativePos | int[] | 相对位置坐标 |
| Covers | object[] | 隐私区域配置 |
| CoversNum | int | 隐私区域个数 |
API: POST /gwp/v3/rtc/device/getconfig/{token} / setconfig/{token}
Name: AVEnc.VideoOSD
配置项： 支持多行文本叠加配置
# 设置环境变量（使用占位符，请替换为实际值）
export JF_UUID="uuidxxxx"
export JF_APP_KEY="appkeyxxxx"
export JF_APP_SECRET="appsecretxxxx"
export JF_MOVE_CARD="2"
export JF_DEVICE_SN="devicesnxxxx"
export JF_DEVICE_TOKEN="devicetokenxxxx"
export JF_ENDPOINT="api-cn.jftechws.com"cd ~/.openclaw/workspace/skills/developer/jf-open-pro-device-osd/scripts
# 查询当前 OSD 配置
python3 osd_config.py --action get-single# 设置通道标题
python3 osd_config.py --action set-channel-title \
--title "大门摄像头" \
--enable
# 关闭通道标题
python3 osd_config.py --action set-channel-title \
--title "大门摄像头" \
--disable# 启用时间标题显示
python3 osd_config.py --action set-time-title --enable
# 设置时间标题位置
python3 osd_config.py --action set-time-title \
--pos-x 100 --pos-y 50 \
--enable# 添加隐私遮挡区域
python3 osd_config.py --action add-cover \
--pos-x 1000 --pos-y 1000 \
--width 500 --height 500# 查询多行 OSD 配置
python3 osd_config.py --action get-multi坐标值按比例转换为 0-8192 范围：
实际像素值
转换公式：坐标值 = (像素值 / 总像素) × 8192
示例：
- 画面宽度 1920 像素
- 标题左上角 X 坐标 100 像素
- 转换后：(100 / 1920) × 8192 ≈ 427坐标格式： [x1, y1, x2, y2]
x1, y1: 左上角坐标（有效）x2, y2: 右下角坐标（仅设置左上角时有效）格式："0xRRGGBBAA"
示例：
"0x000000FF" - 黑色，不透明"0xFFFFFFFF" - 白色，不透明"0x00000080" - 黑色，半透明| code | 说明 | 处理建议 |
|------|------|----------|
| 2000 | 成功 | - |
| 28007 | Header 参数错误 | 检查 uuid、appKey、timeMillis、signature |
| 40103 | 无效 Token | deviceToken 过期，重新获取 |
| 50000 | 服务器内部错误 | 联系杰峰技术支持 |
| Ret | 说明 |
|-----|------|
| 100 | 成功 |
| 文件 | 说明 |
|------|------|
| SKILL.md | 技能文档 |
| scripts/osd_config.py | Python 执行脚本 |
| scripts/crypto.py | 签名/时间戳加密工具（复用） |