乐橙云录像回放实战：用云存储 API 做录像查询与按时间段回放

---

物业项目上线第三周，业主投诉「昨晚有人撬门，怎么查不到录像」。运维同事在 App 里能看到云存套餐生效，我们的工单系统却返回空列表。最后发现两件事：通道云存状态没进同步任务，以及开发直接拿「实时直播接口」去播历史——查询和回放，在平台里是两条不同的 API 链路。

---

为什么云录像值得单独做一套后端

门店巡店、社区安防、考试留痕——业务要的不是「能直播」，而是按时间轴查证据。乐橙侧云录像落在平台云存储上，OpenAPI 侧典型是 「先 list，再 play」：

listDeviceDetailsByPage  →  确认 csStatus = using（云存生效）
        ↓
getCloudRecords          →  倒序分页查片段（recordId、起止时间、缩略图）
        ↓
createDeviceRecordHls    →  按时间段签发 cloudRecord 的 m3u8
   （或 createDeviceFlvLive type=playback 走 FLV + 倍速）

这与实时预览的 bindDeviceLive 不是一条线。混用会出现：直播能看，回放永远 404。

云存 vs 本地 SD（别在 PRD 里混）

来源	列表接口	播放	典型 recordType
云录像	getCloudRecords	createDeviceRecordHls / FLV 回放	cloudRecord
本地 SD	queryLocalRecords 等	同上	localRecord

本文聚焦 云存储；SD 卡走「本地录像」模块，接口不同但播放层可复用同一套 recordType 分支。

前置条件（踩坑高发）

1. 通道已开通云存且 csStatus 为 using（分页查设备详情时可见；notExist / expired 时列表常为空）。
2. 使用现行 OpenAPI，勿引用「旧版本协议」栏目下已停维护接口。
3. appSecret、签名、accessToken 仍在服务端完成（与实时流文章相同，不赘述）。

---

1. 确认云存可用

从 listDeviceDetailsByPage 同步结果里读通道字段：

channelList[].csStatus
  notExist  — 未开通
  using     — 生效中（可查云录像）
  expired   — 已过期

我们工单系统若 csStatus !== 'using'，直接提示「云存未生效」，不再调 getCloudRecords，避免无意义报错。

2. 查询云录像片段：getCloudRecords

作用：在 [beginTime, endTime] 内倒序返回最多 count 条片段（单次 count 最大 30）。

const page = await platformCall('getCloudRecords', {
  token,
  deviceId: 'TESTQWERXXXX',
  channelId: '0',
  beginTime: '2026-05-20 14:00:00',
  endTime: '2026-05-20 15:00:00',
  count: 30,
});
// page.records[]: recordId, beginTime, endTime, thumbUrl, type, size...

录像类型 type（节选）：

type	含义
1000	事件云录像
2000	连续云录像
10001	人形检测云录像

倒序分页遍历（官方策略，适合时间轴 UI）：

async function fetchAllCloudRecords(token, deviceId, channelId, rangeStart, rangeEnd) {
  const all = [];
  let endTime = rangeEnd;
  for (;;) {
    const data = await platformCall('getCloudRecords', {
      token, deviceId, channelId,
      beginTime: rangeStart,
      endTime,
      count: 30,
    });
    const batch = data.records || [];
    if (!batch.length) break;
    all.push(...batch);
    const minBegin = batch.reduce((m, r) =>
      r.beginTime < m ? r.beginTime : m, batch[0].beginTime);
    if (batch.length < 30 || minBegin <= rangeStart) break;
    endTime = subtractOneSecond(minBegin); // 官方：最小 beginTime 减 1 秒作下次 endTime
  }
  return all;
}

前端时间轴：用 thumbUrl 做缩略条，点击某片段再带 beginTime / endTime 去播放（不必只信 recordId，播放接口按时间段工作）。

踩坑 A：时间格式必须 yyyy-MM-dd HH:mm:ss，与设备时区策略不一致会导致「查不到昨晚」。我们统一用北京时间入库，查询前不做 silently 转换。

踩坑 B：子账号 token 需具备 RecordReplay 权限（文档对子账户有最小权限说明），否则列表为空或鉴权失败。

3. 按时间段回放：createDeviceRecordHls

用户选中片段或拖动时间轴后，用 同一段起止时间 换播放地址：

const play = await platformCall('createDeviceRecordHls', {
  token,
  deviceId: 'TESTQWERXXXX',
  channelId: '0',
  beginTime: '2026-05-20 14:32:10',
  endTime: '2026-05-20 14:35:40',
  recordType: 'cloudRecord',  // 云录像；本地 SD 用 localRecord
  streamId: 1,                // 可选，0 主码流 1 辅码流
});
const m3u8 = play.url;

文档备注：录播 HLS 地址有时效，每次请求都是新 URL，拿到后尽快播放；不要当永久链接写进数据库。

踩坑 C（重要）：beginTime / endTime 不支持跨自然日。业主查「昨天 23:50 到今天 00:10」时，后端要 按天拆成两次请求，前端无缝拼接或分两段播。

踩坑 D：样例里曾有人把 recordType 写成 localRecord，云存套餐明明有效却播不出来——类型必须与存储位置一致。

播放器：HLS 用 hls.js / Safari 原生；HTTPS 页面优先用返回 url 里带 proto=https 的地址。

4. 备选路径：FLV 回放 + 倍速

若要 Web 端更低延迟或 倍速播放，可用 createDeviceFlvLive，type: 'playback'：

const flv = await platformCall('createDeviceFlvLive', {
  token,
  deviceId, channelId,
  type: 'playback',
  beginTime: '2026-05-20 14:32:10',
  endTime: '2026-05-20 14:35:40',
  recordType: 'cloudRecord',
  speed: 2,  // 云录像可选 2/4/8/16 倍速
});
// flv.flv / flv.flvHD

HLS 录播与 FLV 回放我们并存：列表页缩略图 + HLS 默认可播；运营复核要 2 倍速时用 FLV。

5. 端到端流程（架构）

┌──────────┐    ┌─────────────────┐    ┌──────────────────────┐
│ 业务前端  │───▶│ 录像中台（自建）  │───▶│ 乐橙 OpenAPI          │
│ 时间轴/UI │◀───│ 权限/审计/缓存   │◀───│ getCloudRecords      │
└──────────┘    └─────────────────┘    │ createDeviceRecordHls │
                                        └──────────────────────┘
  用户选 14:32–14:36  →  后端校验门店权限  →  换 m3u8  →  播放器

5 分钟验收清单：

□ csStatus = using
□ getCloudRecords 在测试时段返回 records.length > 0
□ createDeviceRecordHls + cloudRecord 返回 url
□ 浏览器能播；跨天场景已拆分
□ 播放 URL 短效，不写死在前端配置

6. 与「云转存 MP4」的边界

若要 下载归档（工单附件、法务留痕），平台另有 云转存 能力：创建转录任务生成 MP4 文件，适合「非实时、要文件」场景。实时查回放仍走 getCloudRecords + createDeviceRecordHls 更轻；我们规定：72 小时内纠纷用 HLS 回放，超期归档才触发转存任务。

---

性能

• 列表：不要对同一时间窗每秒轮询 getCloudRecords；用户打开页拉一次，下拉再分页。
• 播放：同一 (deviceId, channelId, begin, end) 短缓存 m3u8 URL（在官方有效期内），避免重复签发。
• 大时间跨度：先按小时/天分段查列表，再懒加载缩略图。

安全与合规

• 回放与下载写 审计日志（谁、何时、哪路、哪段时间）。
• encryptMode 非 0 时，确认设备加密密钥策略，避免播放器 silent fail。
• 缩略图 thumbUrl 也当敏感资源，走自家鉴权代理可选。

常见返回与处理

现象	可能原因	处理
records 空	云存未生效 / 该时段无录像 / 时间格式错	查 csStatus；核对时区
有列表无 url	recordType 错 / 跨天未拆分	cloudRecord；按天切
url 过期	地址超时未播	重新 createDeviceRecordHls
子账号失败	无 RecordReplay 权限	调整授权

---

小结

乐橙云录像回放可以记成两句话：用 getCloudRecords 把时间段内的云片段查出来；用 createDeviceRecordHls（recordType: cloudRecord）按起止时间换 m3u8 播放。 先确认 csStatus 为 using，再区分云存与 SD，别用直播接口硬播历史。

若你在做安防 SaaS、物业工单或教育留痕，建议先用一台已开云存的 IPC 走通「查列表 → 点一条 → 出画」；再接入权限、审计与跨天拆分。乐橙开放平台以视频技术与安全为核心，提供低代码组件与 OpenAPI，帮助开发者较低成本落地视频场景——实时看与事后查，往往在同一套设备资产上叠加即可。

注册与文档：在 乐橙开放平台 完成开发者注册并创建应用；在平台 在线开发文档 中查阅「倒序查询设备云录像片段」「创建设备 hls 录播地址」「本地录像说明」等章节。以上为项目实践记录，生产以最新文档与控制台为准。