相册功能

功能描述

涂鸦 IPC 开发框架在提供实时视频的记录和回放功能外，另外提供了一种 “回放” 文件的方式：相册功能，即将重要的文件（如：图片、MP4 视频）存放至指定位置，之后可通过 App 对应的入口查看、下载、删除这些文件。

开发指导

目录和文件结构

App 查看相册内的文件时，需要向设备提供对应的相册名称。为降低开发和调试难度，当前版本的相册名称在设备 SDK 和 App 端是固定不变的。

设备端工作目录层级如下：

DCIM                                       // 涂鸦存储目录，位于 SD 卡的文件系统的顶层目录
    ├── ipc_emergency_record
    │    ├── aaa.jpg
    │    ├── bbb.mp4
    │    ├── ccc.mp4
    │    └── idx.bin   // 索引文件，请勿删除

当前相册命名只支持 ipc_emergency_record。

API 说明

功能初始化

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

文件写入相册目录

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

需要将录像或图片文件提前移动或拷贝至相册目录，然后再调用此接口完成信息记录。

查询相册内的文件

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

仅在 App 下发查询命令时调用。

下载状态设置

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

仅在 App 下发下载文件命令时调用。在 App 开始下载文件时，SDK 内部会开启新的线程发送文件数据。

删除相册内的文件

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

仅在 App 下发删除文件命令时调用。

注意事项

• 可参考开发包中对应的 Demo 代码，重点查看 main.c 与 ty_sdk_sd_album.c 中的调用顺序。
• 支持相册或者记录仪的设备，PID 需要特殊设置方可展示对应相册入口，PID 配置规则可联系对接人。

常见问题

非 SDK 码流存储文件（如 MP4），相册内如何查看和下载？

开发包提供了一种文件保存和查看方式，但这种方式并非必选项，您仍可以自行实现相册文件的保存和查看。

相册文件夹以及相册图片、视频文件的管理维护可自行设计实现，SDK 没有任何限制。

App 端查看、播放文件功能需要按照信令交互流程执行：

• 查询相册文件 MEDIA_STREAM_ALBUM_QUERY：
  如果自行实现相册文件保存功能，则需要在收到此命令后，转换相册名称，并查询返回相册内所有的文件信息。返回的数据结构必须使用 C2C_ALBUM_INDEX_HEAD ，此数据的内存空间需要由 tal_malloc 动态申请，SDK 内部在使用此空间后自动释放。

• 下载文件 MEDIA_STREAM_ALBUM_DOWNLOAD_START：
  在收到此命令后，您需要自行实现文件数据发送功能，建议新开线程发送帧数据。文件发送必须使用以下接口。

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

  其中：

  • 入参 dev_id 为 NULL。
  • client 为接收信令时携带的参数 channel。
  • type 固定使用 TUYA_DOWNLOAD_ALBUM。
  • pHead 数据类型为 C2C_DOWNLOAD_ALBUM_HEAD。
  • pData 为需要发送的数据 Buffer。
  建议分片发送文件，并在发送最后一个分片时，将 pHead 的 fileEnd 置为 1。在所有文件下载完成后，需要清空 pHead 并将 fileIndex 改为 -1 表示下载结束。

• 下载终止 MEDIA_STREAM_ALBUM_DOWNLOAD_CANCEL：接收到此信令后，需要立即终止下载线程，并释放申请的资源。

• 删除文件 MEDIA_STREAM_ALBUM_DELETE：收到此信令后，需要删除相册内的指定文件，删除后调用以下接口上报状态。

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

  其中：

  • 入参 dev_id 为 NULL。
  • client 为接收信令时携带的参数 channel。
  • type 固定使用 TUYA_DOWNLOAD_ALBUM。
  • success 在失败时值为 0，成功则为 1。

• 相册视频在线播放 MEDIA_STREAM_ALBUM_PLAY_CTRL：此控制信令较为复杂，包含：

  • 播放开始：TY_CMD_IO_CTRL_ALBUM_PLAY_START
  • 播放停止：TY_CMD_IO_CTRL_ALBUM_PLAY_STOP
  • 播放暂停：TY_CMD_IO_CTRL_ALBUM_PLAY_PAUSE
  • 播放重新启动：TY_CMD_IO_CTRL_ALBUM_PLAY_RESUME

  以上功能需要逐个实现。播放开始后，需要自行实现文件解析和发送。发送帧数据时需要使用 tuya_imm_p2p_app_album_play_send_data，播放完成后需要使用 tuya_imm_p2p_album_play_send_finish 同步进度。调用过程请参考 Demo 。