使用与集成
使用与集成
本文与资源包内 docs/DEVELOPER.md 同源,说明目录结构、配置、创流、FFmpeg 录制与各端运行。请求字段与错误码见 createVideoDownloadStreamUrl,本页不重复接口参数表。
适用场景与前提
- 需要把实时预览、本地录像或云录像拉成 分片 MP4(运维联调或服务器脚本)。
- 已有开放平台 host、appId、用户 token,以及设备 deviceId、channelId;部分设备需 productId。
- 已从 资源下载 取得 VideoDownloadTool,hash 为
2ef095398065ead9aafc349ad4053081。 - 本机或服务器可访问开放平台 HTTPS,以及创流返回的 RTSP 地址。
步骤
- 校验 hash 后解压资源包。
- 复制工具包根目录
download.config.example.json为download.config.json(CLI);或安装桌面客户端后在界面填写。 POST {host}/openapi/createVideoDownloadStreamUrl创流。businessType为real、localRecord或cloudRecord;后两种须带beginTime、endTime(yyyy-MM-dd HH:mm:ss)。- 成功时
result.code为字符串"0"。result.data.url多为 AES-256-GCM 密文(Base64),用创流请求中的 同一 token 解密得到明文rtsp://...;若已是rtsp://开头则跳过解密。算法与示例见 createVideoDownloadStreamUrl。 - 用包内 FFmpeg 拉流:
-rtsp_transport tcp、-c copy、segment 分片 MP4。墙钟到达总时长后向 FFmpeg stdin 发送q并等待收尾,不要立刻 kill,否则最后一片常无法播放。 - 创流后尽快拉流(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};安装包只打当前平台 sidecar | Windows 安装包 |
| Python | download.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 tcp | RTSP 走 TCP |
-t 在 -i 之前 | 辅助限制读流时长 |
-c copy | 不重编码 |
-bsf:a aac_adtstoasc | AAC 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.exe | Windows x64 |
ffmpeg-x86_64-unknown-linux-gnu | Linux 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" |
| businessType | real / 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-id | 0 | |
| productId | --product-id | 空 | 可选 |
| businessType | --business-type | real | |
| beginTime / endTime | --begin-time / --end-time | — | 录像必填 |
| saveDir | --save-dir | — | 需可写 |
| totalDuration | --total-duration | 300 | 墙钟秒 |
| segmentDuration | --segment-duration | 60 | 分片秒 |
| apiPath | --api-path | /openapi/createVideoDownloadStreamUrl | |
| streamType | --stream-type | 0 | |
| ffmpeg | --ffmpeg / FFMPEG | binaries/ sidecar | 仅 CLI |
扩展与定制
| 需求 | 改哪里 |
|---|---|
| 创流 URL / Body | 各语言创流函数(集中构造 JSON) |
| FFmpeg 参数 | 各语言 ffmpeg 参数组装 |
| 总时长 / 停止 | 墙钟循环 + stdin q |
| 增加 sign | system 节点按签名文档追加 |
生产常见增量: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 时保留许可证说明。