Photo Album

Functional description

Tuya IPC Development Framework, in addition to providing live video recording and playback, also offers another method for “playback” files: the album feature. This feature enables the storage of important files (such as images and MP4 videos) in a designated location. Users can then view, download, or delete these files through the entries on the app.

Development guide

Directory and file structure

To view files within the album, the app shall provide the specified album name for the device. To simplify development and debugging, the album name in the current version is fixed and identical on both the device SDK and the app.

The device-side working directory is as follows:

DCIM                     // The storage directory, located in the top level directory in the SD card file system.
    ├── ipc_emergency_record
    │    ├── aaa.jpg
    │    ├── bbb.mp4
    │    ├── ccc.mp4
    │    └── idx.bin   // The index file. Do not delete.

Currently, only the album name ipc_emergency_record is supported.

API description

Initialize the feature

/**
 * @brief initialize album storage
 *
 * @param[in] album_info: album info
 * @param[in] path_info: storage mount path
 * @param[in]album_media_info: main video & audio stream info
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_album_ss_init(IN TUYA_IPC_ALBUM_INFO_T* album_info, IN TUYA_IPC_ALBUM_WORKING_PATH_NAME_T* path_info, IPC_MEDIA_INFO_T *album_media_info);

Write files to the album directory

/**
 * @brief write info of newly added file
 *
 * @param[in] album_name: album name
 * @param[in] pInfo: newly added file info
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 *
 * @warning: not thread safe
 */
OPERATE_RET tuya_ipc_album_write_file_info(IN CHAR_T* album_name, IN ALBUM_FILE_INFO_T* pInfo);

Move or copy recording or image files to the album directory in advance. Then, call this interface to complete the information logging.

Query files within the album

/**
 * @brief get album index info by album name
 *
 * @param[in] album_name: album name
 * @param[in] chan: ipc chan num, start from 0
 * @param[out] len: len of p_index_file (SS_ALBUM_INDEX_HEAD_T + SS_ALBUM_INDEX_ITEM_T)
 * @param[out] p_index_file: SS_ALBUM_INDEX_HEAD_T index header, followed SS_ALBUM_INDEX_ITEM_T
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_album_query_by_name(IN CHAR_T* album_name, IN INT_T chan, OUT INT_T* len, OUT SS_ALBUM_INDEX_HEAD_T** p_index_file);

This interface is called only when the app sends a query command.

Set download status

/**
 * @brief set album download status, start or cancel
 *
 * @param[in] new_status: start or cancel download
 * @param[in] p_info: dowload file count and info
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_album_set_download_status(IN SS_ALBUM_DOWNLOAD_STATUS_E new_status, IN SS_ALBUM_DOWNLOAD_START_INFO_T* p_info);

This interface is called only when the app sends acommand to download a file. When the app starts downloading a file, the SDK internally starts a new thread to send the file data.

Delete files within the album

/**
 * @brief delete file info
 *
 * @param[in] sessionId: p2p sesssion id
 * @param[in] album_name: album name
 * @param[in] cnt: file num to delete
 * @param[in] file_info_arr: file infos to delete
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_album_delete_by_file_info(IN INT_T sessionId, IN CHAR_T* album_name, IN INT_T cnt, IN SS_FILE_PATH_T* file_info_arr);

This interface is called only when the app sends acommand to delete a file.

Things to note

• Refer to the demo code in the development kit, focusing on the calling sequence in main.c and ty_sdk_sd_album.c.
• For devices that support the album or a recorder, the product ID (PID) requires special configuration to display the specified album entry. For the PID configuration rules, contact your account manager.

FAQs

How to view and download non-SDK stream files (such as MP4) in the album?

The development kit provides one method for file saving and viewing, but this is not mandatory. You can still implement your own logic for saving and viewing album files.

You can design and implement the management and maintenance of photo folders, images, and video files yourself. The SDK imposes no restrictions.

To view and play files on the app, you need to follow the signaling interaction process:

• Query album files MEDIA_STREAM_ALBUM_QUERY:
  If you implement your own album file saving, you need to convert the album name upon receiving this command and query/return information for all files within the album. The returned data structure must use C2C_ALBUM_INDEX_HEAD. The memory for this data must be dynamically allocated using tal_malloc. The SDK will automatically free this space after use.

• Download files MEDIA_STREAM_ALBUM_DOWNLOAD_START:
  Upon receiving this command, you need to implement the file data sending functionality yourself. It is recommended to start a new thread for sending frame data. Call the following interface to send files:

  OPERATE_RET tuya_imm_p2p_app_download_data(IN CONST CHAR_T *dev_id, IN CONST UINT_T client, TUYA_DOWNLOAD_DATA_TYPE type, IN CONST void * pHead, IN CONST CHAR_T * pData);
  

  The following settings are applied:

  • dev_id: Input parameter, set to NULL.
  • client: The channel parameter carried when receiving the signaling.
  • type: Fixed value TUYA_DOWNLOAD_ALBUM.
  • pHead: Data type is C2C_DOWNLOAD_ALBUM_HEAD.
  • pData: The data buffer to be sent.
  It is recommended to send the file in segments. When sending the last segment, set the fileEnd field in pHead to 1. After all file downloads are completed, clear pHead and change fileIndex to -1 to indicate the end of the download.

• Terminate downloadMEDIA_STREAM_ALBUM_DOWNLOAD_CANCEL: Upon receiving this signaling, immediately terminate the download thread and release any allocated resources.

• Delete files MEDIA_STREAM_ALBUM_DELETE: Upon receiving this signaling, delete the specified file within the album. After deletion, report the status by calling the following interface:

  OPERATE_RET tuya_imm_p2p_delete_video_finish(IN CONST CHAR_T *dev_id,  IN CONST UINT_T client, TUYA_DOWNLOAD_DATA_TYPE type, INT_T success);
  

  The following settings are applied:

  • dev_id: Input parameter, set to NULL.
  • client: The channel parameter carried when receiving the signaling.
  • type: Fixed value TUYA_DOWNLOAD_ALBUM.
  • success: The value is 0 on failure, and 1 on success.

• Play album videos online MEDIA_STREAM_ALBUM_PLAY_CTRL: This control command is complex and includes:

  • Start playback: TY_CMD_IO_CTRL_ALBUM_PLAY_START.
  • Stop playback: TY_CMD_IO_CTRL_ALBUM_PLAY_STOP.
  • Pause playback: TY_CMD_IO_CTRL_ALBUM_PLAY_PAUSE.
  • Resume playback: TY_CMD_IO_CTRL_ALBUM_PLAY_RESUME.

  You need to implement the above functions one by one. After playback starts, you must implement file parsing and transmission yourself. When sending frame data, use tuya_imm_p2p_app_album_play_send_data. Upon playback completion, use tuya_imm_p2p_album_play_send_finish to synchronize progress. Refer to the demo for the calling procedure.