Local Storage

Local storage, a basic feature of an IP camera (IPC), manages the SD card. It stores audios, videos, and images to the SD card in the specified directory and file structure, supporting data search, playback, download, and deletion.

Feature description

Local storage can record live streams to the SD card, allowing for event recording or continuous recording. When the local storage is full, new videos will overwrite the oldest ones. Playback by time allows searching for recordings by time.

Development guide

Runtime environment

• Development framework

  The general features provided by the IPC Development Framework.

• Components

  svc_local_storage

Directory and file structure

The local storage uses a general file system to store audio, video, and index in a proprietary format and images in JPG format. Files are organized with a multilevel directory and file naming convention for fast retrieval.

Directories are broken down into two independent categories: recordings and local albums, as shown below.

DCIM                                       // The storage directory, located in the top-level directory in the SD card file system.
    ├── CHAN0                              // The recording storage directory of the first channel for 1-channel or multichannel IPCs.
    │   └── 2022
    │       └── 10
    │           └── 14
    │               ├── 1665732067_0014    // The event folder, containing 14-second footage in UTC.
    │               │   ├── 0000.media     // The audio and video file in Tuya's proprietary format, starting at 0 seconds.
    │               │   ├── 0010.media     // Start at 10 seconds.
    │               │   ├── 1665732067.jpg // The thumbnail of an event video.
    │               │   └── .info          // Information about the video format and event type.
    │               └── day_idx.bin        // The index of the .info file.
    ├── CHAN1
    │           ...                        // The recording storage directory of the second channel for multichannel IPCs, with the same structure as that of the first channel.

Recordings

Recording

• There are three recording modes:

  • Not recording (at any time)

  • Continuous recording (24/7)

  • Event recording (Recording is triggered by events. Pre-recording is supported.)

    Pre-recording enables storing the footage N seconds before the event. The maximum value of N is limited by ringBuff. For example, if ringBuff is 10 seconds, the upper limit of N is 9 seconds.

• When the available space on the SD card is less than 500 MB, the program will automatically delete the oldest recordings to make room for new recordings. Only one event folder is deleted at a time.

Search

• Search by month: Check for the available footage in a month.
• Search by timeline: Check for the available footage on a specified day.

Playback

Read audio and video from the SD card and selectively send the data to the client at a specific rate.

• The user can control playback, adjust the speed, and jump to a specified position on the timeline.
• Playback control supports start, pause, resume, and end.
• Speed up or slow down the playback by 0.5x, 2x, 4x, or 8x.

Download

Read audio and video from the SD card and send the data to the client as fast as possible.

Delete

Delete the recording on a specific day after the user initiates the deletion on the mobile app.

Video format

Store in a proprietary format

When storage is enabled and continuous recording or event recording is selected, the audio and video streams are automatically recorded to the SD card in Tuya’s proprietary format by default. Therefore, the video files saved in the SD card cannot be opened and played by conventional players. Users can only view playback on the Tuya-enabled app, which meets security requirements.

Storage encryption

To meet higher security requirements, the stored data is encrypted based on the proprietary format. Invoke the specified API to turn the encryption feature on or off. After the encryption feature is turned on, the stream data will be encrypted and written to the SD card.
The encrypted video can only be played back on the device used when recording. If the SD card is inserted into other devices, the encrypted video cannot be played back properly. For example, the encrypted video recorded in device A cannot be played back properly in device B.

Store in an MP4 format

The MP4 file format is a digital multimedia container format widely used for storing video, audio, subtitles, and images. MP4, short for MPEG-4 Part 14, is based on the ISO/IEC 14496-12 standard. It is a highly compatible video format that supports multiple encoding standards.
Available MP4 video encodings of the latest SDK include H.264 and H.265, while audio encodings include PCM and G.711.

Data structure

Initial parameters

typedef struct {
    CHAR_T base_path[SS_BASE_PATH_LEN];   // The root directory of video storage.
    UINT_T max_event_per_day;           // The maximum number of events per day, which is based on the SoC capabilities. Query and get the playback information within the acceptable time period. If the upper limit is exceeded, a query message will be rejected.
    SS_SD_STATUS_CHANGED_CB  sd_status_changed_cb;  // The callback invoked when the storage card status changes.
    INT_T stor_format;  // 0: Default, storage in proprietary format. 1: storage in MP4 format (encryption not supported).
    INT_T encrypt_mode;  // 1: Enable encryption.
    INT_T security_level;   //  Encryption level (optional).
    UINT_T skills;                     // 0 means all the capabilities are supported. See TUYA_IPC_SKILL_BASIC | TUYA_IPC_SKILL_DOWNLOAD for details.
    TUYA_IPC_ALBUM_INFO_T album_info;    // Album initialization parameters.
    INT_T max_event_duration;  // Maximum event duration, 0 defaults to 10 minutes.
    UINT_T write_card_period_s;  // Video data write cycle, 0 defaults to writing data every 6 seconds.
    TUYA_IPC_STORAGE_WORKING_PATH_NAME_T path_name;  // Custom path naming for video storage.
    TUYA_IPC_AOV_STORAGE_INFO_T aov_info;  // AOV storage parameters.
} TUYA_IPC_STORAGE_VAR_T;

Callback parameters

SD card status callback.

typedef OPERATE_RET (*SS_SD_STATUS_CHANGED_CB)(SD_STATUS_E status);

Parameter description

typedef enum {
    SD_STATUS_UNKNOWN = 0,
    SD_STATUS_NORMAL,
    SD_STATUS_ABNORMAL,
    SD_STATUS_LACK_SPACE,
    SD_STATUS_FORMATING,
    SD_STATUS_NOT_EXIST,
    SD_STATUS_MAX
} SD_STATUS_E;

SD card management

The SDK integrates internal logic for SD card status monitoring and status change notifications.

SD card status

Due to differences across development platforms, the SDK relies on the following developer-implemented interfaces: SD_STATUS_E tuya_ipc_sd_get_status(VOID) to get the card’s status, and VOID tuya_ipc_sd_get_capacity_by_mount_path(CONST CHAR_T* mount_path, UINT_T *p_total, UINT_T *p_used, UINT_T *p_free) to get the card’s remaining capacity.

SD card formatting

The user initiates formatting on the mobile app to erase the SD card for normal usage.
You need to implement the formatting process and strictly refer to the processing logic in the demo.

SD card status monitoring

After retrieving the SD card’s status and remaining capacity, the SDK performs a comprehensive assessment to determine its overall status. If an exception is detected, the SDK will automatically stop recording and notify you of the status via a callback function. If the card’s status subsequently returns to normal, the SDK will automatically resume recording based on the current recording mode configuration.

API description

Initialize the channel

Initialize the storage channel, which will create and initialize a buffer. OPRT_OK is returned on success.

/**
 * @brief  Initialize local storage
 *
 * @param[in] p_storage_var: pointer
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_init(IN TUYA_IPC_STORAGE_VAR_T *p_storage_var);

Deallocate local storage

Perform deinitialization to free the buffer memory.

/**
 * @brief Uninit tuya stream storage, free used resource, and memory.
 *
 * @param VOID
 *
 * @return VOID
 */
VOID tuya_ipc_ss_uninit(VOID);

Check if local storage is started

/**
 * @brief Check if stream storage is inited
 *
 * @param VOID
 *
 * @return TRUE/FALSE
 */
BOOL_T tuya_ipc_ss_is_inited(VOID);

Set local storage mode

/**
 * @brief Set write mode of stream storage
 *
 * @param[in] write_mode
 *
 * @return OPERATE_RET
 */
OPERATE_RET tuya_ipc_ss_set_write_mode(IN CONST STREAM_STORAGE_WRITE_MODE_E write_mode);

Get local storage mode

/**
* @brief Get current stream storage write mode
*
* @param VOID
*
* @return STREAM_STORAGE_WRITE_MODE_E
*/
STREAM_STORAGE_WRITE_MODE_E tuya_ipc_ss_get_write_mode(VOID);

Check if write mode of local storage is enabled

/**
 * @brief Check if stream storage write mode is enabled
 *
 * @param VOID
 *
 * @return TRUE/FALSE
 */
BOOL_T tuya_ipc_ss_write_mode_is_enabled(VOID);

Start recording storage by channel

/**
 * @brief Start event stream storage by channel
 *
 * @param[in] channel: which channel, 0 for ipc
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_start_event(IN INT_T channel);

This API only generates video clips in event recording mode and does not record event details.

Stop recording storage by channel

/**
 * @brief Stop event stream storage by channel
 *
 * @param[in] channel: which channel, 0 for ipc
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_stop_event(IN INT_T channel);

Start event recording and log event information

/**
 * @brief Create and start event stream storage
 *
 * @param[in] channel: which channel, default: 0(camera0)
 * @param[in] event_info: event info
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_start_event_by_info(IN INT_T channel, IN SS_EVENT_DETAIL_INFO_T* event_info);

This API was added in v3.10.16 to enable event recording and log event details, such as event type and captured images.

Log new events during event recording

/**
 * @brief Create and start event stream storage
 *
 * @param[in] channel: which channel, default: 0(camera0)
 * @param[in] event_info: event info
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_start_event_by_info(IN INT_T channel, IN SS_EVENT_DETAIL_INFO_T* event_info);

This API was added in v3.10.16 to append the event information to the recording after event recording is enabled. It can only be used after tuya_ipc_ss_start_event_by_info is invoked.

Stop event recording

/**
 * @brief Stop event stream storage after tuya_ipc_ss_start_event_by_info
 *
 * @param[in] channel: which channel, default: 0(camera0)
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_stop_event_by_info(IN INT_T channel);

This API was added in v3.10.16 to stop recordings generated by tuya_ipc_ss_start_event_by_info.

Set pre-record time

/**
 * @brief Set pre-record time, invoke this API only if needed, or it is 2 seconds by default.
 * Should be invoked once after init and before start.
 *
 * @param[in] pre_record_second: time in seconds
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_set_pre_record_time(IN UINT_T pre_record_second);

Set the maximum event duration

/**
 * @brief Set max event duration, invoke this API only if needed, or it is 600 seconds by default.
 * Should be invoked once after init and before start.
 *
 * @param[in] max_event_duration: time in seconds
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_set_max_event_duration(IN UINT_T max_event_duration);

Start playback

This API is invoked based on the MEDIA_STREAM_PLAYBACK_START_TS P2P event. For more information, see the demo application.

/**
 * @brief Start a new playback
 *
 * @param[in] pb_idx: the playback and search index, used for simultaneous search from different clients
 * @param[in] event_cb: callback function for playback events
 * @param[in] video_cb: callback function for getting playback video data
 * @param[in] audio_cb: callback function for getting playback audio data
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_pb_start(IN UINT_T pb_idx, IN SS_PB_EVENT_CB event_cb, IN SS_PB_GET_MEDIA_CB video_cb, IN SS_PB_GET_MEDIA_CB audio_cb);

Callback parameters

typedef VOID (*SS_PB_EVENT_CB)(IN UINT_T pb_idx, IN SS_PB_EVENT_E pb_event, IN PVOID_T args);

Playback event callback

typedef VOID (*SS_PB_GET_MEDIA_CB)(IN UINT_T pb_idx, IN CONST MEDIA_FRAME_T *p_frame);

Callback parameters of audio and video receiving

Parameter	Description
pb_idx	The playback and search index, used for simultaneous search from different clients.
event_cb	Playback event callback.
video_cb	Video data callback.
audio_cb	Audio data callback.

Stop playback

Stop playback on the specified channel.

/**
 * @brief Stop an ongoing playback
 *
 * @param[in] pb_idx: playback/query index, for different clients, do query at the same time
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_pb_stop(IN UINT_T pb_idx);

Storage encryption

• When tuya_ipc_ss_init is invoked to initialize local storage, set the encryption enable parameter.
• Dynamically turn encryption on or off. After the mode is changed, the original recording process will be stopped and a new recording will be started.

/**
 * @brief Set the encryption mode
 *
 * @param[in] encrypt_enable: turn encryption on or off
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ss_set_encrypt_mode(IN CONST BOOL_T encrypt_enable)

Enable MP4 recording

Set the stor_format parameter to 1 in the tuya_ipc_ss_init initialization function to enable storage in MP4 format.

Considerations

• To ensure stable and reliable read/write performance, it is recommended to select SD cards from reputable brands with a speed rating of Class 10 or above.
• An audio or video file can be up to 10 seconds long.
• An event folder contains multiple audio and video files that are continuous and can last up to 600 seconds in total.
• In event recording mode, an event folder contains all the recordings that are specific to an event.
• In continuous mode, recordings in an event folder can last up to 600 seconds in total.

FAQs

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

The recording buffer memory is allocated when a normal SD card is detected and deallocated when local storage is deinitialized.
Memory size: N seconds × (the size of 1-second main video stream + the size of 1-second main audio stream). N is configurable, defaulting to 6.
For multichannel recording, each channel is allocated a buffer.

What video format is compatible with SD card storage?

Audio and video data is stored in Tuya’s proprietary format, with the suffix .media.

Does the local storage module support custom formats and logic?

If you prefer a custom storage logic instead of the standard implementation, you can choose not to enable local storage. Instead, use your own storage program for the customized directory structure, file size and format, and read/write solution. When integrating video playback, downloads, and other features, you must still follow the standard protocol.

How can I fix frame skipping?

• Check if the local time on the device remains consistent.
• Check if the frame rate for audio and video is stable.
• For low power products, the SD card mounting duration should fall within the pre-recording time.
• The larger the capacity of the SD card, the longer it takes to create a folder for event recording after the first frame is captured. This can affect the continuity between the second and first frames, causing skipped frames.

Why is the device reporting an event without local video recording?

This issue is common in low-power devices, where tuya_ipc_ss_stop_event is executed immediately after tuya_ipc_ss_start_event during the initialization phase.

Due to the characteristics of low-power devices, when calling tuya_ipc_ss_start_event, the initialization of the local storage module may not be completed. At this time, event markers will be cached internally. After the initialization is completed, recording will start based on the event markers. If tuya_ipc_ss_stop_event is called during this period, the markers will be cleared, and eventually, no event recording will be generated.

Solution:
When you need to start storing event recordings, use tuya_ipc_ss_is_inited to determine the current initialization status before calling interfaces such as start. At the same time, try to avoid excessively short intervals between interface calls.

Why does the local storage initialization fail?

After tuya_ipc_ss_start_event or tuya_ipc_ss_set_write_mode is called, a not init error appears in the log, indicating that the directory of the storage module has not been initialized.

This issue is mostly related to the implementation of the upper layer SD_STATUS_E tuya_ipc_sd_get_status(VOID). The SDK will call tuya_ipc_sd_get_status internally, and the storage directory initialization can only be completed after SD_STATUS_NORMAL is returned.

Why are there no download and delete buttons on the app’s playback interface?

You can enable the Download and Delete buttons on the playback interface only after uploading the specified capability flag through tuya_ipc_upload_skills. Each capability flag can be set one by one based on the input parameter skills of tuya_ipc_ss_init. You can find the value by searching for TUYA_IPC_SKILL_DOWNLOAD in tuya_ipc_stream_storage.h. Pay attention to the following points:

• You need to perform tuya_ipc_ss_init before calling tuya_ipc_upload_skills. Otherwise, the stored capability flags cannot be uploaded.
• You need to call tuya_ipc_upload_skills after connecting to the internet. Otherwise, the capability flags cannot be uploaded.

Why does a black screen appear during app playback?

This issue is related to the parameters used when sending playback audio and video data. In the MP4 solution, when using tuya_ipc_media_playback_send_video_frame_with_encrypt to send video frame data, you must manually set the following encoding parameters in the request parameters, so the app can decode the data correctly: media.video.video_codec, media.video.video_width, and media.video.video_height.

Why is circular overwrite not working?

This issue is often related to the implementation of the API VOID tuya_ipc_sd_get_capacity(UINT_T *p_total, UINT_T *p_used, UINT_T *p_free).
The SDK calls this API to get the real-time remaining storage capacity and trigger specific strategies. The circular overwrite logic in the SDK operates as follows:

• Circular overwrite starts when the remaining capacity is less than 512 MB.
• All recording stops when the remaining capacity is less than 20 MB.

Is recording supported during offline periods?

Yes, it is supported. The prerequisites are that the device must be activated, and both the device and SDK time must be within a normal range. An exceptional time setting might cause issues with the video storage location.

Typically, the SDK automatically synchronizes with cloud time periodically after connecting to the internet. Suppose you prefer to set the SDK time manually instead of using cloud synchronization. In that case, you can disable cloud time sync by calling httpc_update_localtime_set after SDK initialization, and use tuya_ipc_set_service_time to set the SDK time.

How to display event details for playback video clips?

This feature only supports video clips generated by tuya_ipc_ss_start_event_by_info. Please also note the following details:

• Confirm whether the app version supports this feature.
• Add the TUYA_IPC_SKILL_SUPPORT_PB_V21 capability flag during tuya_ipc_ss_init.
• The responses MEDIA_STREAM_PLAYBACK_QUERY_DAY_V3 and MEDIA_STREAM_DOWNLOAD_IMAGE_V2 must be implemented during the playback query. Refer to the demo code for specific implementation examples.

Why do the video clip duration and path differ from the expected?

• Check if the frame information written to the ring buffer matches the theoretical expectations. It is recommended to use tuya_ipc_ring_buffer_append_data_with_timestamp. The last parameter timestamp should be assigned using tal_time_get_posix_ms.
  Make sure the header file "tal_time_service.h" is included in your .c file.

• Add frame data logging during append operations to verify consistency between the frame data and stored information. Simultaneously, collect both the recording and its corresponding log files.

Why does the app behave unexpectedly after I tap ‘Delete Recording’?

This issue is related to the handling of the delete command. Refer to the processing logic for the MEDIA_STREAM_PLAYBACK_DELETE command in the latest version of the demo code.

How to resolve abnormal frame timestamps during the initialization phase of low power devices?

A key characteristic of low power devices is that they rapidly generate audio and video frames after power-on and write them to the ring buffer. When these frames are written, the device has most likely not yet synchronized its time information, resulting in abnormal timestamps. The solution is as follows:

• Keep the audio and video frame writing process unchanged, but do not start any recording at this stage.
• After ensuring that both audio and video frames with correct timestamps have been written to the ring buffer, call tuya_ipc_ring_buffer_correct_timestamp to correct the erroneous timestamps of the frames in the ring buffer.
• Only after the above API returns a result successfully, begin the storage process.