录像云存储

录像云存储，指的是设备将录像数据，写入第三方云服务商对象存储服务器的功能。为实现音视频数据的即时备份，涂鸦基于 环形缓存（Ring Buffer） 和云端对象存储服务，实现了录像数据的云端存储（Cloud Storage）功能。

功能特性

录像云存储从环形缓存中读取音视频数据，经过数据加密后，上传至云端对象存储服务器，实现录像数据的云端备份。结合实际的应用场景，涂鸦录像云存储支持以下功能：

• 支持两种存储模式：
  • 事件云存储：在事件触发时上传录像。
  • 连续云存储：自动上传全时录像。
• 支持录像预录功能，在录像上传触发的时间点，预先录取一定时长的录像。
• 提供音频控制开关，关闭、开启音频数据的上传。
• 隐私模式下，可以暂停录像云存储服务。

安全特性

对象云存储服务，采用通道和数据双重加密，有效保证了数据的安全性。

通道加密

录像云存储，通过 HTTPS 协议，向云端对象存储服务器发送录像数据，实现了传输通道的安全性。这里需要特别说明的是，设备会对云端对象存储服务器的 CA 证书进行校验，校验通过后，才会开始上传录像数据。

数据加密

在录像数据上传前，会对视频关键帧 I 帧和音频帧，通过 AES 算法进行加密，保证了数据和通道的双重安全性。

关联组件

svc_cloud_storage

数据结构

订单类型

typedef enum
{
    CLOUD_STORAGE_TYPE_CONTINUE,        // 连续订单类型
    CLOUD_STORAGE_TYPE_EVENT,           // 事件订单类型
    CLOUD_STORAGE_TYPE_INVALID          // 未购买订单
} CLOUD_STORAGE_TYPE_E;

API

初始化

初始化录像云存储服务。主要包括内部缓存空间的申请和录像线程的创建。

/**
 * @brief    initialize cloud storage, which will malloc all needed memory after this
 * @return   error code
 * - OPRT_OK init success
 * - Others  init failed
 */
OPERATE_RET tuya_ipc_cloud_storage_init(VOID);

反初始化

反初始化录像云存储服务。该操作主要执行缓存空间的释放和录像线程的销毁。

/**
 * @brief    uninit cloud storage, free used memory
 * @return   VOID
 */
VOID tuya_ipc_cloud_storage_uninit(VOID);

获取订单类型

该接口可以获取订单类型，判断设备是否开通录像云存储服务。订单类型可分为连续云存储、事件云存储和未购买订单类型。

/**
 * @brief    get current storage type, based on purchase order
 * @return   CLOUD_STORAGE_TYPE_E
 * - CLOUD_STORAGE_TYPE_CONTINUE  continuous record type
 * - CLOUD_STORAGE_TYPE_EVENT     event-based type, only record and store audio/video when there is event happening
 * - CLOUD_STORAGE_TYPE_INVALID   no cloud storage order exist
 */
CLOUD_STORAGE_TYPE_E tuya_ipc_cloud_storage_get_store_mode(VOID);

开始事件录像

设备发生事件时，开始一段事件录像。

/**
 * @brief    start event cloud storage
 * @return   error code
 * - OPRT_OK cloud storage start success
 * - Others cloud storage start failed
 */
OPERATE_RET tuya_ipc_cloud_storage_event_start(VOID);

结束事件录像（同步）

设备当前事件结束时，结束正在进行的事件录像。该接口为同步接口，最长阻塞 30 秒。

/**
 * @brief    stop event cloud storage, synchronous api
 * @return   error code
 * - OPRT_OK cloud storage stop success
 * - Others  cloud storage stop failed
 */
OPERATE_RET tuya_ipc_cloud_storage_event_stop(VOID);

结束事件录像（异步）

设备当前事件结束时，结束正在进行的事件录像。该接口为异步接口，不会发生阻塞。

/**
 * @brief    stop event cloud storage, asynchronous api
 * @return   error code
 * - OPRT_OK cloud storage stop success
 * - Others  cloud storage stop failed
 */
OPERATE_RET tuya_ipc_cloud_storage_event_stop_async(VOID);

获取录像状态

获取录像状态，用于判断录像是否正在进行。

/**
 * @brief    get cloud storage status
 * @return   BOOL_T
 * - TRUE    cloud storage is uploading
 * - FALSE   cloud storage is not uploading
 */
BOOL_T tuya_ipc_cloud_storage_get_status(VOID);

设置音频开关

设置音频开关，关闭音频功能时，录像存储只从环形缓存中读取视频数据，不读取音频数据。

/**
 * @brief    set audio open/close
 * @param[in] is_audio_open
 * @ref       TRUE open audio for cloud storage
 * @ref       FALSE close audio for cloud storage
 * @return    VOID
 */
VOID tuya_ipc_cloud_storage_set_audio_stat(BOOL_T is_audio_open);

设置预录时长

设置预录时长，最大值不超过环形缓存的最大时长。该接口未设置时，默认的预录时长为 2 秒。

/**
 * @brief    set cloud storage pre record time duration
 * @param[in] pre_recode_time  pre record time duration for cloud storage
 * - OPRT_OK set pre record time success
 * - Others  set pre record time failed
 */
OPERATE_RET tuya_ipc_cloud_storage_set_pre_record_time(INT_T pre_record_time);

暂停录像

暂停录像云存储服务，录像线程暂停从环形缓存读取数据，暂停数据的上传。通常，隐私模式下，需要暂停录像。

/**
 * @brief    pause cloud storage, used in privacy mode e.g.
 * @return   VOID
 */
VOID tuya_ipc_cloud_storage_pause(VOID);

恢复录像

恢复录像云存储服务，录像线程恢复工作。通常，退出隐私模式时，需要恢复录像，与 tuya_ipc_cloud_storage_pause 配对使用。

/**
 * @brief    resume cloud storage which is paused by pause API
 * @return   VOID
 */
VOID tuya_ipc_cloud_storage_resume(VOID);

常见问题

内存在什么时候申请与释放，占用多大的内存？

录像云存储 在初始化时即申请连续的内存。是为了减少在运行过程中，占用的内存动态变化导致的 OOM（Out of memory，内存溢出）等问题。整体内存占用大小为，11 秒对应码率 bitrate 的乘积。

录像云存储申请的内存空间，用于缓存加密后的音视频数据，上传至云端对象存储服务器。

录像云存储在反初始化时，释放申请的内存空间。

单次事件录像，中间出现中断的原因？

• 视频实际码率，超过设置的最大码率值。
• 设备网络较差，录像数据上传失败。
• 设备网络较差，录像数据上传耗时很长。
  录像数据读取和录像数据上传，在录像线程中串行进行。如果设备网络较差，录像数据上传耗时超过环形缓存最大时长时，会导致中间的录像数据缺失。

预录时长与设置值为何不一致？

环形缓存定位预录帧，是从最新的数据帧往前frame_num帧起，继续往前查找直到数据帧类型为关键帧 I 帧。frame_num对应预录时长和帧率 fps 的乘积。

因此，预录帧的位置不是一个固定位置，实际的预录时长，与设置值存在一定差异。

录像云存储采用主码流，还是子码流？

录像云存储默认采用主码流，目前暂时不支持子码流录制。