README.md
1# MediaLibrary<a name="EN-US_TOPIC_0000001147574647"></a>
2
3- [Introduction<a name="section1158716411637"></a>](#introduction)
4- [Directory Structure<a name="section161941989596"></a>](#directory-structure)
5- [Usage Guidelines<a name="usage-guidelines"></a>](#usage-guidelines)
6 - [Query AudioAsset<a name="get-audioasset"></a>](#query-audioasset)
7 - [Create Album<a name="create-album"></a>](#create-album)
8 - [Copy ImageAsset<a name="copy-imageasset"></a>](#copy-imageasset)
9- [Repositories Involved<a name="section1533973044317"></a>](#repositories-involved)
10
11
12## Introduction<a name="section1158716411637"></a>
13
14The **medialibrary\_standard** repository provides a set of easy-to-use APIs for getting media file metadata information.
15MediaLibrary APIs can only be used internally, not exposed to public application currently.
16
17The various capabilities can be categorized as below:
18- Query for audio, video and image files metadata information
19- Query for image and video albums
20- File operations like create, rename, copy and delete media file
21- Album operations like create, rename and delete album
22
23
24## Directory Structure<a name="section161941989596"></a>
25
26The structure of the repository directory is as follows:
27```
28/foundation/multimedia/medialibrary_standard # Medialibrary code
29├── frameworks # Framework code
30│ ├── innerkitsimpl # Internal Native API implementation
31│ │ └── media_library # Native MediaLibrary implementation
32│ └── kitsimpl # External JS API implementation
33│ └── medialibrary # External MediaLibrary NAPI implementation
34├── interfaces # Interfaces
35│ ├── innerkits # Internal Native APIs
36│ └── kits # External JS APIs
37├── LICENSE # License file
38├── ohos.build # Build file
39├── sa_profile # Service configuration profile
40└── services # Service implementation
41```
42
43## Usage Guidelines<a name="usage-guidelines"></a>
44### Query AudioAsset<a name="get-audioasset"></a>
45We can use APIs like **GetMediaAssets**, **GetAudioAssets**, **GetVideoAssets** and **GetImageAssets** to query for different file metadata information. The following steps describe how to use the GetAudioAssets API to obtain audio related metadata.
461. Use **GetMediaLibraryClientInstance** API to obtain the **Medialibrary** instance
47 ```
48 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
49 ```
502. Set the scanning directory for audio files in **selection** string. The selection value will be a relative path to a media root directory i.e. "/storage/media/local/files". It will check for audio files recursively in the given directory.
51 ```
52 string selection = "audios/audio1";
53 ```
543. Use the **GetAudioAssets** API to query for audio files. The input argument *selectionArgs* does not have any use case currently. The API returns a list of *AudioAsset*.
55 ```
56 vector<string> selectionArgs;
57 vector<unique_ptr<AudioAsset>> audioAssets = mediaLibClientInstance->GetAudioAssets(selection, selectionArgs);
58 ```
594. We can obtain audio metadata for each file from the list.
60 ```
61 for (size_t i = 0; i < audioAssets.size(); i++) {
62 cout << audioAssets[i]->uri_ << endl;
63 cout << audioAssets[i]->size_ << endl;
64 cout << audioAssets[i]->dateAdded_ << endl;
65 cout << audioAssets[i]->dateModified_ << endl;
66 cout << audioAssets[i]->albumName_ << endl;
67 cout << audioAssets[i]->duration_ << endl;
68 cout << audioAssets[i]->artist_ << endl;
69 }
70 ```
71
72### Create Album<a name="create-album"></a>
73MediaLibrary offers APIs for application to perform album operations like create, modify and delete. Below are the steps on how to create a new album.
741. Use **GetMediaLibraryInstance** API to obtain the **Medialibrary** instance
75 ```
76 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
77 ```
782. Specify the album type. It can be either *ASSET_GENERIC_ALBUM*, *ASSET_IMAGEALBUM* or *ASSET_VIDEOALBUM*.
79 ```
80 AssetType assetType = ASSET_VIDEOALBUM;
81 ```
823. Create a new **AlbumAsset** object and provide a new album name. Below album "new_video" will get created in the path "/storage/media/local/files/videos".
83 ```
84 AlbumAsset albumAsset;
85 albumAsset.albumName_ = "videos/new_video";
86 ```
874. Use **CreateMediaAlbumAsset** API to create the new album in the device. The return value will be boolean, which states whether the album creation succeeded or failed.
88 ```
89 bool errCode = mediaLibClientInstance->CreateMediaAlbumAsset(assetType, albumAsset);
90 ```
91
92### Copy ImageAsset<a name="copy-imageasset"></a>
93File operations are supported via APIs like **CreateMediaAsset**, **ModifyMediaAsset**, **CopyMediaAsset**, **DeleteMediaAsset**. The example below explains the usage of CopyMediaAsset API.
941. Use **GetMediaLibraryInstance** API to obtain the **Medialibrary** instance
95 ```
96 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
97 ```
982. Specify the asset type. It can be either *ASSET_MEDIA*, *ASSET_IMAGE*, *ASSET_AUDIO* or *ASSET_VIDEO*.
99 ```
100 AssetType assetType = ASSET_IMAGE;
101 ```
1023. Define the source and target **ImageAsset**. The target asset must specify the new album name where the source asset will be copied.
103 ```
104 MediaAsset srcMediaAsset;
105 MediaAsset dstMediaAsset;
106
107 srcMediaAsset.name_ = "image1.jpg";
108 srcMediaAsset.uri_ = "/storage/media/local/files/images/001/image1.jpg";
109
110 dstMediaAsset.albumName_ = "images/new_image";
111 ```
1124. Use **CopyMediaAsset** API to copy the source asset to target asset's album name location. The boolean return value denotes the status of the file operation. The source file "image1.jpg" will get copied to "/storage/media/local/files/images/new_image".
113 ```
114 bool errCode = mediaLibClientInstance->CopyMediaAsset(assetType, srcMediaAsset, dstMediaAsset);
115 ```
116
117Please refer [**imedia_library_client.h**](https://gitee.com/openharmony/multimedia_medialibrary_standard/blob/master/interfaces/innerkits/native/include/imedia_library_client.h) for more APIs.
118
119
120## Repositories Involved<a name="section1533973044317"></a>
121[multimedia/medialibrary_standard](https://gitee.com/openharmony/multimedia_medialibrary_standard)
122
README_zh.md
1# MediaLibrary组件<a name="ZH-CN_TOPIC_0000001147574647"></a>
2
3- [简介](#section1158716411637)
4- [目录](#section161941989596)
5- [使用说明](#usage-guidelines)
6 - [查询音频资产](#get-audioasset)
7 - [创建相册](#create-album)
8 - [拷贝图片资产](#copy-imageasset)
9- [相关仓](#section1533973044317)
10
11
12## 简介<a name="section1158716411637"></a>
13
14**medialibrary\_standard** 仓库提供了一系列易用的接口用于获取媒体文件元数据信息。
15MediaLibrary接口暂不对外部应用开放, 仅内部使用。
16
17支持能力列举如下：
18- 查询音频、视频和图片文件元数据信息
19- 查询图片和视频相册
20- 媒体文件操作如创建、重命名、拷贝和删除
21- 相册操作如创建、重命名和删除
22
23
24## 目录<a name="section161941989596"></a>
25
26仓目录结构如下:
27```
28/foundation/multimedia/medialibrary_standard # 媒体库组件代码
29├── frameworks # 框架代码
30│ ├── innerkitsimpl # 内部接口实现
31│ │ └── media_library # Native MediaLibrary 实现
32│ └── kitsimpl # 外部接口实现
33│ └── medialibrary # 外部 MediaLibrary NAPI 实现
34├── interfaces # 接口代码
35│ ├── innerkits # 内部 Native 接口
36│ └── kits # 外部 JS 接口
37├── LICENSE # 证书文件
38├── ohos.build # 编译文件
39├── sa_profile # 服务配置文件
40└── services # 服务实现
41```
42
43## 使用说明<a name="usage-guidelines"></a>
44### 查询音频资产<a name="get-audioasset"></a>
45可以使用接口如 **GetMediaAssets**, **GetAudioAssets**, **GetVideoAssets** 和 **GetImageAssets** 来查询不同类型的媒体文件元数据信息。
46以下步骤描述了如何使用 GetAudioAssets 接口来获取相应的音频元数据。
471. 使用 **GetMediaLibraryClientInstance** 接口来获取 **Medialibrary** 实例。
48 ```
49 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
50 ```
512. 在 **selection** 内设置音频文件的扫描目录。selection 代表媒体公共根目录的相对路径, i.e. "/storage/media/local/files"。接口会在指定目录内递归查找所有音频文件。
52 ```
53 string selection = "audios/audio1";
54 ```
553. 使用 **GetAudioAssets** 接口来查询音频文件。输入参数 *selectionArgs* 暂无作用，接口会返回 *AudioAsset* 的列表。
56 ```
57 vector<string> selectionArgs;
58 vector<unique_ptr<AudioAsset>> audioAssets = mediaLibClientInstance->GetAudioAssets(selection, selectionArgs);
59 ```
604. 可以从列表内获取音频元数据信息。
61 ```
62 for (size_t i = 0; i < audioAssets.size(); i++) {
63 cout << audioAssets[i]->uri_ << endl;
64 cout << audioAssets[i]->size_ << endl;
65 cout << audioAssets[i]->dateAdded_ << endl;
66 cout << audioAssets[i]->dateModified_ << endl;
67 cout << audioAssets[i]->albumName_ << endl;
68 cout << audioAssets[i]->duration_ << endl;
69 cout << audioAssets[i]->artist_ << endl;
70 }
71 ```
72
73### 创建相册<a name="create-album"></a>
74MediaLibrary 给应用提供了操作相册的接口, 如创建，修改和删除。以下展示了创建一个新相册的步骤。
751. 使用 **GetMediaLibraryInstance** 接口来获取 **Medialibrary** 实例。
76 ```
77 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
78 ```
792. 选择一种相册类型, 可以是 *ASSET_GENERIC_ALBUM*, *ASSET_IMAGEALBUM* 或 *ASSET_VIDEOALBUM* 。
80 ```
81 AssetType assetType = ASSET_VIDEOALBUM;
82 ```
833. 创建一个 **AlbumAsset** 并提供相册名称。如下 "new_video" 相册将在 "/storage/media/local/files/videos" 内被创建。
84 ```
85 AlbumAsset albumAsset;
86 albumAsset.albumName_ = "videos/new_video";
87 ```
884. 使用 **CreateMediaAlbumAsset** 接口来创建新相册, 返回值表示相册创建的成功与否。
89 ```
90 bool errCode = mediaLibClientInstance->CreateMediaAlbumAsset(assetType, albumAsset);
91 ```
92
93### 拷贝图片资产<a name="copy-imageasset"></a>
94文件操作通过如**CreateMediaAsset**, **ModifyMediaAsset**, **CopyMediaAsset**, **DeleteMediaAsset** 的接口支持。以下例子说明 **CopyMediaAsset** 接口的使用方法。
951. 使用 **GetMediaLibraryInstance** 接口来获取 **Medialibrary** 实例。
96 ```
97 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
98 ```
992. 选择一种资产类型, 可以是 *ASSET_MEDIA*, *ASSET_IMAGE*, *ASSET_AUDIO* 或 *ASSET_VIDEO*.
100 ```
101 AssetType assetType = ASSET_IMAGE;
102 ```
1033. 确定 **ImageAsset** 的源和目标位置, 目标资产需要指定源拷贝的目标相册名。
104 ```
105 MediaAsset srcMediaAsset;
106 MediaAsset dstMediaAsset;
107
108 srcMediaAsset.name_ = "image1.jpg";
109 srcMediaAsset.uri_ = "/storage/media/local/files/images/001/image1.jpg";
110
111 dstMediaAsset.albumName_ = "images/new_image";
112 ```
1134. 使用 **CopyMediaAsset** 接口来从源资产拷贝到目标资产相册目录, 接口返回值表示文件操作状态。源文件 "image1.jpg" 将会被拷贝到 "/storage/media/local/files/images/new_image" 。
114 ```
115 bool errCode = mediaLibClientInstance->CopyMediaAsset(assetType, srcMediaAsset, dstMediaAsset);
116 ```
117
118更多接口请参考 [**imedia_library_client.h**](https://gitee.com/openharmony/multimedia_medialibrary_standard/blob/master/interfaces/innerkits/native/include/imedia_library_client.h) 。
119
120
121## 相关仓<a name="section1533973044317"></a>
122[multimedia/medialibrary_standard](https://gitee.com/openharmony/multimedia_medialibrary_standard)
123
