JF Open Pro Video Record - 杰峰设备录像回放技能

面向开发者的杰峰设备录像回放工具 (Python)

支持设备云存储录像和设备本地录像回放地址获取，包括录像列表查询、回放地址获取、录像下载等功能。

🔒 安全说明

凭据存储：仅支持环境变量

网络访问：

• ✅ 仅访问杰峰官方 API 端点 (api.jftechws.com / api-cn.jftech.com)
• ❌ 不访问第三方服务
• ❌ 不读取敏感系统文件

🚀 快速开始

设置环境变量

# 开放平台凭证（必需）
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 端点（可选）

使用技能

# ========== 云存录像 ==========

# 获取云存视频列表（按时间范围查询）
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

📋 环境变量

🛠️ 功能

1. 云存录像

1.1 获取云存视频列表

查询设备在指定时间段内的云存视频列表。

支持场景：

• 条件查询（时间范围）
• 组合条件查询（分页 + 报警类型过滤）

支持的报警类型：

• HumanDetect - 人形检测
• MotionDetect - 移动侦测
• appEventHumanDetectAlarm - 人形报警
• 更多类型参考 报警消息类型

使用示例：

# 按时间范围查询
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

返回字段：

1.2 获取云存回放地址

获取云存视频回放或下载地址，支持 HLS 在线播放和 MP4 下载。

支持模式：

• 精准查询：根据视频 ID 查询
• 条件查询：根据时间范围查询

使用示例：

# 按时间范围获取回放地址（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

播放方式：

# VLC 播放
vlc "https://xxx.com/xxx.m3u8?Expires=..."

# 网页播放（HLS.js）
\x3Cvideo src="https://xxx.com/xxx.m3u8?Expires=..." controls>\x3C/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）

录像类型说明：

使用示例：

# 查询所有类型录像
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"

返回字段：

2.2 获取本地录像回放地址

获取本地录像文件的回放或下载地址。

支持的协议格式：

使用示例：

# 在线播放（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 字段

⚠️ 错误处理

常见错误

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 (中国大陆)

📁 脚本工具

云存录像脚本：

本地录像脚本：

# 获取帮助
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