Local Storage

Local storage, a basic feature of an IP camera (IPC), manages the SD card. It stores audio, videos, and images to the SD card in the specified directory and file structure, supporting video 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 search for recordings by time.

Development guide

Runtime environment

• Development framework

  The general features provided by the IPC Development Framework.

• Components

  svc_local_storage

SD card management

Hot swap detection, formatting, and status updates are available. To ensure excellent read/write performance, it is recommended to select a Class 10 SD card from reputable brands.

• Hot swap detection:

  • Identify and mount the file system for data read/write when an SD card is inserted.
  • Stop recording and playback and unmount the file system when an SD card is removed.

• SD card status: not detected, normal, and anomaly.

  An anomaly can be caused by no file system, incompatible file system, and file system or SD card damage.

• SD card formatting: The user initiates formatting on the mobile app to erase the SD card for normal usage. How SD card formatting works:

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

• 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 in one 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.

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 SD card status changes. */
    UINT_T skills;                     /* 0 means all the capabilities are supported. See TUYA_IPC_SKILL_BASIC | TUYA_IPC_SKILL_DOWNLOAD */
    TUYA_IPC_ALBUM_INFO_T album_info;   /* Album information */
} 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;

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, memory e.g.
 *
 * @param VOID
 *
 * @return VOID
 */
VOID tuya_ipc_ss_uninit(VOID);

Determine if local storage is started

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

Determine if write mode of local storage is enabled

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

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);

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 second
 *
 * @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 second
 *
 * @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 called 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: playback/query index, for different client do query at the same time
 * @param[in] event_cb: callback function of playback event
 * @param[in] video_cb: callback function of getting playback video data
 * @param[in] audio_cb: callback function of 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 client 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);

Things to note

• Recordings reside in a multilevel directory that is organized in year, month, day, and event folders as well as audio and video files.
• 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. MP4 format will be supported in later releases.

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?

Do not call tuya_ipc_ss_stop_event immediately after tuya_ipc_ss_start_event is invoked when an event occurs.

When calling tuya_ipc_ss_start_event, if local initialization is not completed, the system will cache event flags and start recording based on these flags after initialization. However, if tuya_ipc_ss_stop_event is called during this period, the flag will be cleared, causing the event recording to fail.

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 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.