Cloud Storage

Cloud storage stores the recording data on object storage servers provided by third-party cloud vendors. The ring buffer combined with the cloud object storage service enables you to back up recording data to the cloud instantly.

Features

Cloud storage reads audio and video data from the ring buffer and then uploads it to the cloud object storage server after encryption. Cloud storage features:

• Cloud storage comes in two flavors:
  • Event-based cloud storage: Record and upload videos to the cloud when an event is detected.
  • Continuous cloud storage: Record and upload videos to the cloud 24/7 automatically.
• Pre-record: Record a video for a few seconds before the occurrence of an event.
• Turn on/off audio, and enable/disable audio upload.
• In privacy mode, recording cloud storage will be temporarily disabled.

Security

Both the channel and data are encrypted to secure transmission.

Channel encryption

HTTPS protocol secures transferring the data between a device and a cloud object storage server. The device uploads the recording data only after the certificate authority (CA) certificate of the object storage server is verified successfully.

Data encryption

Before the recording data is uploaded, the video I-frames and audio frames will be encrypted with AES algorithms.

Components

svc_cloud_storage

Data structure

Order type

typedef enum
{
    CLOUD_STORAGE_TYPE_CONTINUE,        // Continuous cloud storage.
    CLOUD_STORAGE_TYPE_EVENT,           // Event-based cloud storage.
    CLOUD_STORAGE_TYPE_INVALID          // No subscription.
} CLOUD_STORAGE_TYPE_E;

APIs

Initialization

Initialize the cloud storage service, including the initialization of internal functional resources and creation of recording threads.

/**
 * @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);

Deinitialization

Deinitialize the cloud storage service. This deallocates the buffer memory and destroys the recording threads.

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

Get the order type

Get the order type to determine if the device has subscribed to the cloud storage service. The order type can be continuous cloud storage, event-based cloud storage, and no subscription.

/**
 * @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);

Start event recording

The device records a video clip when an event occurs.

/**
 * @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);

Stop event recording (synchronous)

The device stops recording when an event ends. This is a synchronous API, with a maximum blocking time of 30 seconds.

/**
 * @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);

Stop event recording (asynchronous)

The device stops recording when an event ends. This is a non-blocking asynchronous API.

/**
 * @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);

Get recording status

Get the current recording status to determine if the device is recording a video.

/**
 * @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);

Turn on/off audio

When audio is turned off, only video data is read from the ring buffer for cloud storage.

/**
 * @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);

Set pre-record duration

The maximum pre-record duration cannot exceed the maximum ring buffer duration. If you do not specify a value, the default duration is two seconds.

/**
 * @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);

Pause recording

Temporarily disable recording cloud storage. The recording thread stops reading data from the ring buffer and uploading data to the server. This feature is typically triggered when the user turns on privacy mode.

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

Resume recording

Resume recording cloud storage and the recording thread. Used with tuya_ipc_cloud_storage_pause, this feature is triggered when the user turns off privacy mode.

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

FAQs

Why is it essential to maintain a consistent flow when pushing audio/video frames into the ring buffer?

Consistent flow means that, temporally, the interval between pushing each frame into the ring buffer should be 1000 ms/fps.

Example:

• For a video stream with 20 fps, push a video frame into the ring buffer approximately every 50 ms.
• For an audio stream with 40 fps, push an audio frame into the ring buffer approximately every 25 ms.

When should I allocate and deallocate memory? How much memory is required?

The video cloud storage module allocates a contiguous block of memory when the SDK obtains a valid cloud storage subscription service. Once allocated, this memory is neither released nor reallocated during the entire runtime. The total memory footprint is calculated as the product of the bitrate and a duration of 11 seconds.

The allocated memory is used to buffer the encrypted audio and video data to be uploaded to the cloud object storage server.

The allocated memory is freed when the cloud storage is deinitialized.

How to reduce the memory footprint of cloud storage?

• The memory footprint within the SDK is significantly influenced by the bitrate. Therefore, it is recommended to prioritize reducing the bitrate as the primary method to address high memory consumption.
• The sub-stream’s ring buffer is used infrequently, typically only during preview. It is advised to reduce the max_buffer_seconds parameter to a range of 4 to 6 seconds.
• For event recording with a pre-record duration of 2 seconds or less, and an I-frame interval of 2 seconds, the max_buffer_seconds for the main stream can be set to 6 or 8 seconds.
• Reducing the max_buffer_seconds for the main stream might increase the risk of cloud storage data loss in environments with poor network conditions.

Why is the recording of an event interrupted?

• The actual bitrate exceeds the set maximum bitrate.
• Recording data fails to be uploaded due to poor network conditions.
• Recording data upload is slow due to poor network conditions.
  The device reads and uploads recording data in the recording thread serially. If the recording upload time exceeds the maximum ring buffer duration due to poor network conditions, data loss might occur.

SDK error log

The following are some common error logs:

ring buffer delay too much

• Q: Why does this log appear?

• A: This log is generated when, from the perspective of the module reading the ring buffer, the index difference between the data frame node currently pointed to by the read pointer of the recording module and the latest data frame node written into the ring buffer exceeds 95% of the maximum cached frame capacity of the ring buffer. This condition is identified as delay too much.

  For example, If the ring buffer has a max_buffer_seconds of 10s and the fps is 20, then the total node capacity is 200 frames. Suppose the reading module is currently at node index 3, but the latest written frame is at index 198. The index difference is: 198 - 3 = 195, and 95% of the maximum capacity is: 200 × 0.95 = 190. Since 195 > 190, the delay too much condition is triggered.

  Another extreme scenario involves the write operation being significantly faster than the read operation, potentially causing the write pointer to overwrite the node index currently held by the reading module.

• Q: What scenarios can cause the read node index to lag significantly behind the write node index?

• A: There are two possible scenarios:

  • Poor network conditions: The time required to upload a cloud storage segment exceeds the maximum buffer duration of the ring buffer. Example: Uploading an 11-second cloud storage cache segment takes 12 seconds. During these 12 seconds, data continues to be written into the ring buffer at the normal rate. Consequently, the time difference between the most recently written frame and the most recently read frame becomes very large.
  • Inconsistent data flow. Example: The device itself has an internal buffer and pushes a large number of data frames into the ring buffer within a very short period.

memory insufficient to buffer data:

The device’s actual bitrate exceeds the bitrate configured via tuya_ipc_media_adapter_set_media_info. A single continuous event recording splits into two segments, with a portion of the video missing in between, directly resulting from the buffer being unable to accommodate the high data rate.

Why doesn’t the actual pre-record duration match the set value?

To locate the pre-frame in the ring buffer, starting from the latest frame, search backward for frame_num frame and then continue the search until the I-frame is reached. frame_num is calculated by the formula: pre-record duration × frame rate in fps.

Therefore, the pre-frame is not at a fixed position, so the actual pre-record duration might deviate from the set value.
If sync stream failed is displayed, it indicates inconsistent data flow into the ring buffer. In this case, check whether both audio and video frames are being fed into the ring buffer at a consistent, uniform rate in terms of time.

Is the mainstream or substream used for cloud storage?

The mainstream is used by default. Substream recording is not supported currently.

Why does tuya_ipc_cloud_storage_get_status still return 1 after calling tuya_ipc_cloud_storage_event_stop_async?

This issue can occur due to the following two scenarios:

Value	Reason
tuya_ipc_cloud_storage_get_status returns 1 for a few seconds, then changes to 0	The tuya_ipc_cloud_storage_event_stop_async function returns immediately. However, cloud recording continues until it captures the video stream at the exact time tuya_ipc_cloud_storage_event_stop_async was called. Finalizing the recording requires additional time to complete the upload of the cloud storage file. Example: If tuya_ipc_cloud_storage_event_stop_async is called at 18:31:30, the system might still be recording video from 18:31:28. It will only truly stop after recording the video stream for 18:31:30 is completed.
tuya_ipc_cloud_storage_get_status still returns 1 after over a minute	As mentioned above, this is likely because the device stopped pushing the video stream to the ring buffer after the Stop call. For instance, if the stream stopped being pushed to the ring buffer after 18:31:30, the storage module cannot obtain the video stream for 18:31:30. Consequently, it cannot finalize a complete recording and remains in a state of waiting and retrying to acquire the necessary data. Alternatively, this could be caused by network errors, preventing the complete and successful upload of the cloud recording file.

Why does tuya_ipc_cloud_storage_event_stop time out or fail to stop successfully?

As explained in the table above under the scenario where the status remains 1 for over a minute, this most frequently occurs because the video stream is not continued to be pushed to the ring buffer after the Stop function is called.

Why does tuya_ipc_cloud_storage_get_ready sometimes return 0 and sometimes return 1?

The tuya_ipc_cloud_storage_get_ready function gets the status of whether the cloud storage service is ready and initialized. Crucially, the device must be online to obtain the cloud storage order information.

• If a cloud storage service plan is active for the device:
  • It returns 0 before the device comes online.
  • It returns 1 after the device comes online and successfully gets the cloud storage order details.
• It returns 0 if no cloud storage service plan is active.
• It returns 0 if, after startup, there is no network connection or the cloud storage order details cannot be obtained for any reason.

When are cloud storage recordings deleted?

Cloud storage recordings are deleted after the video file’s retention period expires.

Example:

If a device activates a 7-day event cloud storage service for one month on August 16, 2025, videos recorded on September 15, 2025 will be deleted from the cloud storage on September 22, 2025. Videos recorded before the deletion are still available and will not be affected by the service expiration on September 16, 2025.