乐橙云开发文档
控制台
更新日志
开始使用
核心概念
开发指南
设备能力与事件参考
API 参考
SDK 与工具
行业方案
平台与支持
控制台
更新日志
前往官网
快速入门
  • 开始使用
  • 核心概念
  • 开发指南
  • 设备能力与事件参考
  • API 参考
  • SDK 与工具
    • Android SDK
    • iOS SDK
    • 鸿蒙 SDK
    • PC SDK
    • 轻应用组件 ImouPlayer
    • 小程序插件与半屏小程序
    • 图片解密组件
    • 视频下载工具
      • 使用与集成
      • 排障
    • 服务端示例与签名工具
    • Postman 集合
    • 资源下载
  • 行业方案
  • 平台与支持
本页目录
适用场景与前提
步骤
目录结构
业务流程
创流与解密
FFmpeg 录制约定
配置文件(Python / Java / C++)
各端实现
桌面客户端(Tauri)
Python CLI
Java CLI
C++ CLI
CLI 与界面字段对照
扩展与定制
安全与合规
相关参考

使用与集成

使用与集成

本文与资源包内 docs/DEVELOPER.md 同源,说明目录结构、配置、创流、FFmpeg 录制与各端运行。请求字段与错误码见 createVideoDownloadStreamUrl,本页不重复接口参数表。

适用场景与前提

  • 需要把实时预览、本地录像或云录像拉成 分片 MP4(运维联调或服务器脚本)。
  • 已有开放平台 host、appId、用户 token,以及设备 deviceId、channelId;部分设备需 productId。
  • 已从 资源下载 取得 VideoDownloadTool,hash 为 2ef095398065ead9aafc349ad4053081。
  • 本机或服务器可访问开放平台 HTTPS,以及创流返回的 RTSP 地址。

步骤

  1. 校验 hash 后解压资源包。
  2. 复制工具包根目录 download.config.example.json 为 download.config.json(CLI);或安装桌面客户端后在界面填写。
  3. POST {host}/openapi/createVideoDownloadStreamUrl 创流。businessType 为 real、localRecord 或 cloudRecord;后两种须带 beginTime、endTime(yyyy-MM-dd HH:mm:ss)。
  4. 成功时 result.code 为字符串 "0"。result.data.url 多为 AES-256-GCM 密文(Base64),用创流请求中的 同一 token 解密得到明文 rtsp://...;若已是 rtsp:// 开头则跳过解密。算法与示例见 createVideoDownloadStreamUrl。
  5. 用包内 FFmpeg 拉流:-rtsp_transport tcp、-c copy、segment 分片 MP4。墙钟到达总时长后向 FFmpeg stdin 发送 q 并等待收尾,不要立刻 kill,否则最后一片常无法播放。
  6. 创流后尽快拉流(URL 常带 expire)。生产环境在 system 中按 签名 追加 sign;包内 Demo 联调可省略 sign。

目录结构

open-video-download/                   # 解压后的工具包根目录
├── download.config.example.json
├── download.config.json               # 本地配置,勿提交
├── binaries/
├── docs/
├── open-video-download-tauri/
├── open-video-download-python/
├── open-video-download-java/
└── open-video-download-cpp/
形态创流FFmpeg典型部署
Tauri桌面应用内 HTTP工具包根 binaries/ffmpeg-{target};安装包只打当前平台 sidecarWindows 安装包
Pythondownload.py上级目录 binaries/,按 OS 选择服务器
Java主类入口从工作目录向上查找 binaries/服务器
C++主程序入口同上服务器 / C++ 栈

四种实现的请求体字段与 FFmpeg 参数对齐。平台 API 变更时四处同步,或只 fork 一种语言。

业务流程

sequenceDiagram
  participant App as Demo
  participant Open as 开放平台 Host
  participant Proxy as RTSP 代理
  participant FF as FFmpeg

  App->>Open: POST /openapi/createVideoDownloadStreamUrl
  Open-->>App: result.data.url
  App->>FF: -i rtsp://...
  FF->>Proxy: RTSP over TCP
  Proxy-->>FF: 音视频
  FF-->>App: 分片 MP4
  Note over App,FF: 墙钟到达总时长后向 FFmpeg 发送 q 并等待收尾

停止策略以 进程启动后的墙钟秒数 为准,不依赖 RTSP 时间戳。墙钟到点立刻 kill 会导致最后一片 MP4 未写完文件尾。

创流与解密

  • 方法:POST {host}/openapi/createVideoDownloadStreamUrl(桌面版路径写死,界面不展示)。
  • Content-Type:application/json。
  • Demo:system 含 appId、time、nonce,联调可不含 sign;上线必须签名。
  • 请求 id:随机 UUID。
  • params:token、deviceId、channelId、businessType、streamType(Demo 默认 "0"),录像加 beginTime / endTime,可选 productId。完整约束见接口页。

businessType

值含义额外
real实时预览不需 begin/end
localRecord本地录像须 begin/end
cloudRecord云录像须 begin/end

解密(与接口页一致):

  • 密钥:SHA-256(token + "ENCRYPTKEY")(UTF-8),token 与 params.token 相同。
  • 密文:Base64 解码后为 12 字节 IV + GCM 密文(含 16 字节 auth tag)。
  • Tauri / Python / Java / C++ 均在创流成功后解密再交给 FFmpeg。

创流成功不等于一定有媒体:无片源或会话结束会导致 FFmpeg End of file,见 排障。

FFmpeg 录制约定

四种实现参数一致:

ffmpeg -hide_banner -loglevel info \
  -rtsp_transport tcp \
  -fflags +genpts+discardcorrupt \
  -t {totalDuration} \
  -i "{streamUrl}" \
  -c copy \
  -bsf:a aac_adtstoasc \
  -avoid_negative_ts make_zero \
  -f segment -segment_time {segmentDuration} -segment_format mp4 \
  -reset_timestamps 1 -strftime 0 \
  "{saveDir}/{deviceId}_{yyyyMMdd_HHmmss}_%03d.mp4"
选项作用
-rtsp_transport tcpRTSP 走 TCP
-t 在 -i 之前辅助限制读流时长
-c copy不重编码
-bsf:a aac_adtstoascAAC ADTS → MP4 ASC;不要链式 hevc/h264 视频 BSF(HEVC 会 exit -22)
-f segment按分片时长切 MP4
墙钟 stop应用层计时 ≥ 总时长后发 q,等待正常退出(约 30s)

输出名:{saveDir}/{deviceId}_{yyyyMMdd_HHmmss}_001.mp4、002.mp4 …(%03d 从 1 递增)。不翻转、不旋转画面。

共享 FFmpeg(工具包根 binaries/)

文件平台
ffmpeg-x86_64-pc-windows-msvc.exeWindows x64
ffmpeg-x86_64-unknown-linux-gnuLinux x64(需可执行权限)
  • Tauri 开发时使用工具包根 binaries/;发布安装包只打当前平台 sidecar。桌面版不可自定义 FFmpeg 路径。
  • Python / Java / C++ 按 OS 选择上述文件;可用环境变量 FFMPEG 或 CLI --ffmpeg 覆盖(须指向包内 sidecar)。
  • 分发安装包须遵守 FFmpeg 许可证,见包内 open-video-download-tauri/THIRD_PARTY_NOTICES.md(桌面安装目录下文件名仍为 THIRD_PARTY_NOTICES.md)。

配置文件(Python / Java / C++)

默认读取工具包根 download.config.json。CLI 参数覆盖文件。 可选 --config 指定其它 JSON。

字段说明
host、appId、token平台与鉴权;host 无末尾 /
deviceId、channelId、productId设备;channelId 常见 "0"
businessTypereal / localRecord / cloudRecord
beginTime、endTime录像时段
saveDir可写输出目录(支持中文路径)
totalDurationSecs、segmentDurationSecs墙钟总时长、分片秒数;分片不得大于总时长
apiPath、streamType默认创流路径与码流类型
ffmpeg留空则用 binaries/ 当前平台文件

Windows:

copy download.config.example.json download.config.json

Linux / macOS:

cp download.config.example.json download.config.json

校验:必填非空;时长大于 0;录像类型必须有时间范围。

各端实现

桌面客户端(Tauri)

cd open-video-download-tauri
npm install
npm run verify-sidecars
npm run tauri dev
npm run tauri build

Windows x64 典型产物:open-video-download_0.1.0_x64_en-US.msi、open-video-download_0.1.0_x64-setup.exe。界面中/英切换,默认英文。必填项缺失会弹窗,不只写日志。录制时 FFmpeg 不弹出黑色控制台。

Python CLI

cd open-video-download-python
pip install -r requirements.txt
python download.py --host ... --app-id ... --token ... \
  --device-id ... --save-dir /data/out \
  --total-duration 60 --segment-duration 10

退出码:0 成功;1 创流或逻辑错误;130 Ctrl+C。

Java CLI

cd open-video-download-java
mvn package
java -jar target/open-video-download-java-0.1.0.jar \
  --host ... --app-id ... --token ... \
  --device-id ... --save-dir /data/out \
  --total-duration 60 --segment-duration 10

JDK 11+。-h 打印参数摘要。

C++ CLI

cd open-video-download-cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/video-download

C++17。Windows 使用 WinHTTP;Linux 需 libcurl。URL 解密需 OpenSSL。CLI 选项名与 Python/Java 相同(--config、--host、--app-id 等)。

CLI 与界面字段对照

配置CLI默认说明
Host--host—无末尾 /
appId--app-id—
token--token—勿写入公开仓库
deviceId--device-id—
channelId--channel-id0
productId--product-id空可选
businessType--business-typereal
beginTime / endTime--begin-time / --end-time—录像必填
saveDir--save-dir—需可写
totalDuration--total-duration300墙钟秒
segmentDuration--segment-duration60分片秒
apiPath--api-path/openapi/createVideoDownloadStreamUrl
streamType--stream-type0
ffmpeg--ffmpeg / FFMPEGbinaries/ sidecar仅 CLI

扩展与定制

需求改哪里
创流 URL / Body各语言创流函数(集中构造 JSON)
FFmpeg 参数各语言 ffmpeg 参数组装
总时长 / 停止墙钟循环 + stdin q
增加 signsystem 节点按签名文档追加

生产常见增量:token 用环境变量或配置文件;cron / systemd / K8s Job 调 CLI;容器镜像带 FFmpeg 与 Python 或 JRE,挂载 saveDir。无头服务器不要用 Tauri。

对齐检查:录像时间格式;仅音频 BSF、无错误视频 BSF;墙钟总时长停止;输出 {deviceId}_{timestamp}_%03d.mp4。

安全与合规

  • token、appId 视为敏感信息。
  • 仅请求 HTTPS 的开放平台 host。
  • 日志中的 RTSP URL 应脱敏。
  • FFmpeg GPL:分发 sidecar 时保留许可证说明。

相关参考

  • 概述
  • 排障
  • createVideoDownloadStreamUrl
  • 签名
  • 资源下载

商务合作:cloud_openteam@imou.com · 工单 · 获取帮助(公众号、小程序试用中心)

Copyright © 2015-2026 IMOU. All Rights Reserved. 浙ICP备16023676号

错误码与排障
排障