back
loading skill details...
杰峰设备录像回放技能。支持获取设备云存储录像和设备本地录像回放地址，包括录像列表查询、回放地址获取、录像下载等功能。使用场景：云存回放、本地卡录像回放、录像下载、历史视频查看。
---
name: jf-open-pro-video-record
description: 杰峰设备录像回放技能。支持获取设备云存储录像和设备本地录像回放地址，包括录像列表查询、回放地址获取、录像下载等功能。使用场景：云存回放、本地卡录像回放、录像下载、历史视频查看。
# 必需凭证声明 - 平台元数据
credentials:
required:
- name: JF_UUID
type: string
description: 杰峰开放平台用户唯一标识
source: https://open.jftech.com/
- name: JF_APPKEY
type: string
description: 杰峰开放平台应用 Key
source: https://open.jftech.com/
- name: JF_APPSECRET
type: string
description: 杰峰开放平台应用密钥
source: https://open.jftech.com/
- name: JF_MOVECARD
type: integer
description: 签名算法偏移量 (0-9)
source: https://open.jftech.com/
optional:
- name: JF_SN
type: string
description: 设备序列号
- name: JF_USERNAME
type: string
description: 设备登录用户名
default: admin
- name: JF_PASSWORD
type: string
description: 设备登录密码
- name: JF_ENDPOINT
type: string
description: API 端点
default: api.jftechws.com
# 网络端点声明
endpoints:
- url: https://api.jftechws.com
description: 杰峰官方 API (国际)
- url: https://api-cn.jftech.com
description: 杰峰官方 API (中国大陆)
# 安全声明
security:
credentials_required: true
env_vars_only: true
language: python
network_access:
- api.jftechws.com
- api-cn.jftech.com
file_access: none
---
# JF Open Pro Video Record - 杰峰设备录像回放技能
> **面向开发者的杰峰设备录像回放工具 (Python)**
>
> 支持设备云存储录像和设备本地录像回放地址获取，包括录像列表查询、回放地址获取、录像下载等功能。
---
## 🔒 安全说明
**凭据存储：仅支持环境变量**
| 方式 | 支持 | 说明 |
|------|------|------|
| **环境变量** | ✅ 支持 | 推荐方式，避免凭据出现在进程列表或日志中 |
| **命令行参数** | ❌ 不支持 | 避免凭据泄露风险 |
| **配置文件** | ❌ 不支持 | 避免明文存储凭据 |
**网络访问：**
- ✅ 仅访问杰峰官方 API 端点 (`api.jftechws.com` / `api-cn.jftech.com`)
- ❌ 不访问第三方服务
- ❌ 不读取敏感系统文件
---
## 🚀 快速开始
### 设置环境变量
```bash
# 开放平台凭证（必需）
export JF_UUID="your-uuid" # 开放平台用户唯一标识
export JF_APPKEY="your-appkey" # 开放平台应用 Key
export JF_APPSECRET="your-appsecret" # 开放平台应用密钥
export JF_MOVECARD=5 # 签名算法偏移量 (0-9)
# 设备信息
export JF_SN="your-device-sn" # 设备序列号
export JF_USERNAME="admin" # 设备登录用户名（可选，默认：admin）
export JF_PASSWORD="your-password" # 设备登录密码（本地录像必需）
export JF_ENDPOINT="api.jftechws.com" # API 端点（可选）
```
### 使用技能
```bash
# ========== 云存录像 ==========
# 获取云存视频列表（按时间范围查询）
python scripts/cloud_video_list.py --start-time "2026-04-07 10:00:00" --stop-time "2026-04-07 18:00:00"
# 获取云存视频列表（带报警类型过滤）
python scripts/cloud_video_list.py --start-time "2026-04-07 10:00:00" --stop-time "2026-04-07 18:00:00" --events "HumanDetect"
# 获取云存回放地址（按时间范围）
python scripts/cloud_playback_url.py --start-time "2026-04-07 15:23:26" --stop-time "2026-04-07 15:23:36"
# 获取云存回放地址（按视频 ID 精准查询）
python scripts/cloud_playback_url.py --video-id "xxxxxxxxxx"
# 获取云存回放地址（下载 MP4 格式）
python scripts/cloud_playback_url.py --start-time "2026-04-07 15:23:26" --stop-time "2026-04-07 15:23:36" --format MP4
# ========== 本地录像 ==========
# 获取本地录像回放列表
python scripts/local_video_list.py --start-time "2026-04-07 10:00:00" --stop-time "2026-04-07 18:00:00"
# 获取本地录像回放地址
python scripts/local_playback_url.py --file-name "/idea0/2026-04-07/001/15.23.26-15.23.36[R][@39733][2].h264" --start-time "2026-04-07 15:23:26" --stop-time "2026-04-07 15:23:36"
# 本地录像下载（MP4 格式）
python scripts/local_playback_url.py --file-name "xxx.h264" --start-time "2026-04-07 15:23:26" --stop-time "2026-04-07 15:23:36" --download
```
---
## 📋 环境变量
| 变量名 | 说明 | 必需 | 默认值 |
|--------|------|------|--------|
| `JF_UUID` | 开放平台用户唯一标识 | 是 | - |
| `JF_APPKEY` | 开放平台应用 Key | 是 | - |
| `JF_APPSECRET` | 开放平台应用密钥 | 是 | - |
| `JF_MOVECARD` | 签名算法偏移量 (0-9) | 是 | - |
| `JF_SN` | 设备序列号 | 云存必需 | - |
| `JF_USERNAME` | 设备登录用户名 | 本地录像必需 | `admin` |
| `JF_PASSWORD` | 设备登录密码 | 本地录像必需 | - |
| `JF_ENDPOINT` | API 端点 | 否 | `api.jftechws.com` |
---
## 🛠️ 功能
### 1. 云存录像
#### 1.1 获取云存视频列表
查询设备在指定时间段内的云存视频列表。
**支持场景：**
- 条件查询（时间范围）
- 组合条件查询（分页 + 报警类型过滤）
**支持的报警类型：**
- `HumanDetect` - 人形检测
- `MotionDetect` - 移动侦测
- `appEventHumanDetectAlarm` - 人形报警
- 更多类型参考 [报警消息类型](https://docs.jftech.com/docs?menusId=54582398fd8d4248962354e92ac2e47a&siderId=ba50abdc08e84216bf8e3d3742df8922&lang=zh)
**使用示例：**
```bash
# 按时间范围查询
python scripts/cloud_video_list.py \
--start-time "2026-04-07 10:00:00" \
--stop-time "2026-04-07 18:00:00"
# 带报警类型过滤
python scripts/cloud_video_list.py \
--start-time "2026-04-07 10:00:00" \
--stop-time "2026-04-07 18:00:00" \
--events "HumanDetect"
# 分页查询
python scripts/cloud_video_list.py \
--start-time "2026-04-07 10:00:00" \
--stop-time "2026-04-07 18:00:00" \
--page-start 1 \
--page-size 50
```
**返回字段：**
| 字段 | 说明 | 示例 |
|------|------|------|
| `StartTime` | 录像开始时间 | `2026-04-07 13:12:34` |
| `StopTime` | 录像结束时间 | `2026-04-07 13:12:51` |
| `IndexFile` | 录像文件名 | `xxx.m3u8` |
| `PicFlag` | 是否有缩略图 (1=有，0=无) | `1` |
| `VideoSize` | 视频大小（字节） | `339014` |
| `thumbURL` | 缩略图 URL | `http://...` |
| `events` | 报警类型列表 | `["HumanDetect"]` |
| `videoId` | 视频 ID（精准查询用） | `0...9a...z` |
#### 1.2 获取云存回放地址
获取云存视频回放或下载地址，支持 HLS 在线播放和 MP4 下载。
**支持模式：**
- 精准查询：根据视频 ID 查询
- 条件查询：根据时间范围查询
**使用示例：**
```bash
# 按时间范围获取回放地址（HLS 在线播放）
python scripts/cloud_playback_url.py \
--start-time "2026-04-07 15:23:26" \
--stop-time "2026-04-07 15:23:36"
# 按视频 ID 精准查询
python scripts/cloud_playback_url.py \
--video-id "xxxxxxxxxx"
# 获取下载链接（MP4 格式）
python scripts/cloud_playback_url.py \
--start-time "2026-04-07 15:23:26" \
--stop-time "2026-04-07 15:23:36" \
--format MP4
# 多目设备（多镜头摄像头）
python scripts/cloud_playback_url.py \
--start-time "2026-04-07 15:23:26" \
--stop-time "2026-04-07 15:23:36" \
--multi-video
```
**播放方式：**
```bash
# VLC 播放
vlc "https://xxx.com/xxx.m3u8?Expires=..."
# 网页播放（HLS.js）
<video src="https://xxx.com/xxx.m3u8?Expires=..." controls></video>
# 下载 MP4
curl -o video.mp4 "https://xxx.com/xxx.mp4?Expires=..."
# 或
ffmpeg -i "https://xxx.com/xxx.mp4?Expires=..." -c copy video.mp4
```
**注意事项：**
- 回放地址有效期：**24 小时**
- MP4 下载按**文件大小流量计费**
- 多目设备返回多个地址，以分号 `;` 分隔
---
### 2. 本地录像（TF 卡/硬盘）
#### 2.1 获取本地录像回放列表
查询设备本地存储（TF 卡或硬盘）中的录像文件列表。
**前置条件：**
- 设备支持卡存录像（有 TF 卡或硬盘）
- 需配置设备登录凭据（`JF_USERNAME`、`JF_PASSWORD`）
**录像类型说明：**
| 类型 | 说明 |
|------|------|
| `*` | 所有类型的录像 |
| `R` | 常规录像（无报警时的连续录像，含 AOV 录像） |
| `A` | 非视频类报警（如 IO 口报警） |
| `M` | 视频类报警（移动侦测、人形检测等） |
| `H` | 手动录像 |
| `C` | 卡号录像 |
| `V` | AOV 录像（低功耗全时录像） |
| `I` | 入侵报警 |
| `S` | 盗移/滞留报警 |
| `F` | 人脸识别录像 |
| `N` | 车牌识别录像 |
| `K` | 关键录像 |
**使用示例：**
```bash
# 查询所有类型录像
python scripts/local_video_list.py \
--start-time "2026-04-07 10:00:00" \
--stop-time "2026-04-07 18:00:00"
# 只查询报警录像（移动侦测 + 人形检测 + 常规）
python scripts/local_video_list.py \
--start-time "2026-04-07 10:00:00" \
--stop-time "2026-04-07 18:00:00" \
--event "AMRH"
# 只查询常规录像
python scripts/local_video_list.py \
--start-time "2026-04-07 10:00:00" \
--stop-time "2026-04-07 18:00:00" \
--event "R"
```
**返回字段：**
| 字段 | 说明 | 示例 |
|------|------|------|
| `BeginTime` | 录像开始时间 | `2026-04-07 20:00:00` |
| `EndTime` | 录像结束时间 | `2026-04-07 21:00:00` |
| `FileName` | 录像文件路径 | `/idea0/2026-04-07/002/20.00.00-21.00.00[R][@2dcc5][0].h264` |
| `FileLength` | 文件大小（KB） | `123456` |
#### 2.2 获取本地录像回放地址
获取本地录像文件的回放或下载地址。
**支持的协议格式：**
| 协议 | 格式 | 说明 |
|------|------|------|
| `flv` | FLV | 标准 FLV 封装（H.265 采用国内行业 FLV 标准） |
| `flv-enhanced` | FLV-Enhanced | H.265 标准 FLV-Enhanced 封装 |
| `hls-ts` | HLS-TS | HLS 协议，TS 格式切片 |
| `hls-fmp4` | HLS-fMP4 | HLS 协议，fMP4 格式切片 |
| `mp4` | MP4 | HTTP 协议，MP4 格式（用于下载） |
| `rtsp-sdp` | RTSP-SDP | RTSP 标准协议（默认） |
| `rtsp-pri` | RTSP-PRI | RTSP 私有协议 |
**使用示例：**
```bash
# 在线播放（FLV 格式）
python scripts/local_playback_url.py \
--file-name "/idea0/2026-04-07/001/15.23.26-15.23.36[R][@39733][2].h264" \
--start-time "2026-04-07 15:23:26" \
--stop-time "2026-04-07 15:23:36" \
--protocol flv
# HLS 播放
python scripts/local_playback_url.py \
--file-name "xxx.h264" \
--start-time "2026-04-07 15:23:26" \
--stop-time "2026-04-07 15:23:36" \
--protocol hls-ts
# 录像下载（MP4 格式）
python scripts/local_playback_url.py \
--file-name "xxx.h264" \
--start-time "2026-04-07 15:23:26" \
--stop-time "2026-04-07 15:23:36" \
--protocol mp4 \
--download
# 指定码流类型（0=主码流/高清，1=辅码流/标清）
python scripts/local_playback_url.py \
--file-name "xxx.h264" \
--start-time "2026-04-07 15:23:26" \
--stop-time "2026-04-07 15:23:36" \
--stream-type 0
```
**注意事项：**
- 回放地址有效期：**10 小时**
- 同时只支持**一路回放或下载**
- 本地录像回放和下载**按流量计费**
- 必须先获取录像文件列表，使用返回的 `FileName` 字段
---
## ⚠️ 错误处理
| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| `2000` | 成功 | - |
| `12504` | 授权失败 - 设备未开通服务 | 登录开放平台为设备绑定对应套餐 |
| `10001` | 参数错误 | 检查请求参数格式 |
| `10002` | 签名失败 | 检查 appKey/appSecret 和时间戳 |
| `200` | 设备响应成功 | - |
| `401` | 设备认证失败 | 检查设备用户名/密码 |
### 常见错误
**1. 云存服务未开通**
```
code: 12504
msg: authorize failed, Please check it in the open platform
```
→ 登录杰峰开放平台，为设备购买并绑定云存套餐卡
**2. 本地录像文件不存在**
```
Ret: 404
msg: File not found
```
→ 检查文件名是否正确，确认设备 TF 卡/硬盘中有录像
**3. 设备登录失败**
```
Ret: 401
msg: Authentication failed
```
→ 检查 `JF_USERNAME` 和 `JF_PASSWORD` 是否正确
---
## 📚 官方参考资料
- **杰峰开放平台**: https://open.jftech.com/
- **API 文档**: https://docs.jftech.com/
- **云存视频列表**: https://docs.jftech.com/docs?menusId=54582398fd8d4248962354e92ac2e47a&siderId=66142b2ca13c418d84085772a627d650
- **云存回放地址**: https://docs.jftech.com/docs?menusId=54582398fd8d4248962354e92ac2e47a&siderId=2e08468f46564602d01ae8a244661672
- **本地录像列表**: https://docs.jftech.com/docs?menusId=54582398fd8d4248962354e92ac2e47a&siderId=4b1516da5763439a9bc7175d7ac7d246
- **本地录像回放**: https://docs.jftech.com/docs?menusId=54582398fd8d4248962354e92ac2e47a&siderId=4b1516da5763439a9bc7175d7ac7d246
- **API 端点**: `api.jftechws.com` (国际) / `api-cn.jftech.com` (中国大陆)
---
## 📁 脚本工具
**云存录像脚本：**
| 脚本 | 功能 |
|------|------|
| `cloud_video_list.py` | 获取云存视频列表 |
| `cloud_playback_url.py` | 获取云存回放地址 |
**本地录像脚本：**
| 脚本 | 功能 |
|------|------|
| `local_video_list.py` | 获取本地录像回放列表 |
| `local_playback_url.py` | 获取本地录像回放地址 |
```bash
# 获取帮助
python scripts/cloud_video_list.py --help
python scripts/cloud_playback_url.py --help
python scripts/local_video_list.py --help
python scripts/local_playback_url.py --help
```
---
**技能版本：** v1.0.1
**语言：** Python
**最后更新：** 2026-04-08
don't have the plugin yet? install it then click "run inline in claude" again.