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
14**Figure 1** medialibrary architecture<a name="fig99659301300"></a>
15
16
17The **medialibrary\_standard** repository provides a set of easy-to-use APIs for getting media file metadata information.
18MediaLibrary APIs can only be used internally, not exposed to public application currently.
19
20The various capabilities can be categorized as below:
21- Query for audio, video and image files metadata information
22- Query for image and video albums
23- File operations like create, rename, copy and delete media file
24- Album operations like create, rename and delete album
25
26
27## Directory Structure<a name="section161941989596"></a>
28
29The structure of the repository directory is as follows:
30```
31/foundation/multimedia/medialibrary_standard # Medialibrary code
32├── frameworks # Framework code
33│ ├── innerkitsimpl # Internal Native API implementation
34│ │ └── media_library # Native MediaLibrary implementation
35│ └── kitsimpl # External JS API implementation
36│ └── medialibrary # External MediaLibrary NAPI implementation
37├── interfaces # Interfaces
38│ ├── innerkits # Internal Native APIs
39│ └── kits # External JS APIs
40├── LICENSE # License file
41├── ohos.build # Build file
42├── sa_profile # Service configuration profile
43└── services # Service implementation
44```
45
46## Usage Guidelines<a name="usage-guidelines"></a>
47### Query AudioAsset<a name="get-audioasset"></a>
48We 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.
491. Use **GetMediaLibraryClientInstance** API to obtain the **Medialibrary** instance
50 ```cpp
51 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
52 ```
532. 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.
54 ```cpp
55 string selection = "audios/audio1";
56 ```
573. 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*.
58 ```cpp
59 vector<string> selectionArgs;
60 vector<unique_ptr<AudioAsset>> audioAssets = mediaLibClientInstance->GetAudioAssets(selection, selectionArgs);
61 ```
624. We can obtain audio metadata for each file from the list.
63 ```cpp
64 for (size_t i = 0; i < audioAssets.size(); i++) {
65 cout << audioAssets[i]->uri_ << endl;
66 cout << audioAssets[i]->size_ << endl;
67 cout << audioAssets[i]->dateAdded_ << endl;
68 cout << audioAssets[i]->dateModified_ << endl;
69 cout << audioAssets[i]->albumName_ << endl;
70 cout << audioAssets[i]->duration_ << endl;
71 cout << audioAssets[i]->artist_ << endl;
72 }
73 ```
74
75### Create Album<a name="create-album"></a>
76MediaLibrary offers APIs for application to perform album operations like create, modify and delete. Below are the steps on how to create a new album.
771. Use **GetMediaLibraryInstance** API to obtain the **Medialibrary** instance
78 ```cpp
79 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
80 ```
812. Specify the album type. It can be either *ASSET_GENERIC_ALBUM*, *ASSET_IMAGEALBUM* or *ASSET_VIDEOALBUM*.
82 ```cpp
83 AssetType assetType = ASSET_VIDEOALBUM;
84 ```
853. 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".
86 ```cpp
87 AlbumAsset albumAsset;
88 albumAsset.albumName_ = "videos/new_video";
89 ```
904. 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.
91 ```cpp
92 bool errCode = mediaLibClientInstance->CreateMediaAlbumAsset(assetType, albumAsset);
93 ```
94
95### Copy ImageAsset<a name="copy-imageasset"></a>
96File operations are supported via APIs like **CreateMediaAsset**, **ModifyMediaAsset**, **CopyMediaAsset**, **DeleteMediaAsset**. The example below explains the usage of CopyMediaAsset API.
971. Use **GetMediaLibraryInstance** API to obtain the **Medialibrary** instance
98 ```cpp
99 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
100 ```
1012. Specify the asset type. It can be either *ASSET_MEDIA*, *ASSET_IMAGE*, *ASSET_AUDIO* or *ASSET_VIDEO*.
102 ```cpp
103 AssetType assetType = ASSET_IMAGE;
104 ```
1053. Define the source and target **ImageAsset**. The target asset must specify the new album name where the source asset will be copied.
106 ```cpp
107 MediaAsset srcMediaAsset;
108 MediaAsset dstMediaAsset;
109
110 srcMediaAsset.name_ = "image1.jpg";
111 srcMediaAsset.uri_ = "/storage/media/local/files/images/001/image1.jpg";
112
113 dstMediaAsset.albumName_ = "images/new_image";
114 ```
1154. 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".
116 ```cpp
117 bool errCode = mediaLibClientInstance->CopyMediaAsset(assetType, srcMediaAsset, dstMediaAsset);
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**图1** medialibrary组件架构图
14
15**medialibrary\_standard** 仓库提供了一系列易用的接口用于获取媒体文件元数据信息。
16MediaLibrary接口暂不对外部应用开放, 仅内部使用。
17
18支持能力列举如下：
19- 查询音频、视频和图片文件元数据信息
20- 查询图片和视频相册
21- 媒体文件操作如创建、重命名、拷贝和删除
22- 相册操作如创建、重命名和删除
23
24
25## 目录<a name="section161941989596"></a>
26
27仓目录结构如下:
28```
29/foundation/multimedia/medialibrary_standard # 媒体库组件代码
30├── frameworks # 框架代码
31│ ├── innerkitsimpl # 内部接口实现
32│ │ └── media_library # Native MediaLibrary 实现
33│ └── kitsimpl # 外部接口实现
34│ └── medialibrary # 外部 MediaLibrary NAPI 实现
35├── interfaces # 接口代码
36│ ├── innerkits # 内部 Native 接口
37│ └── kits # 外部 JS 接口
38├── LICENSE # 证书文件
39├── ohos.build # 编译文件
40├── sa_profile # 服务配置文件
41└── services # 服务实现
42```
43
44## 使用说明<a name="usage-guidelines"></a>
45### 查询音频资产<a name="get-audioasset"></a>
46可以使用接口如 **GetMediaAssets**、**GetAudioAssets**、**GetVideoAssets** 和 **GetImageAssets** 来查询不同类型的媒体文件元数据信息。
47以下步骤描述了如何使用 GetAudioAssets 接口来获取相应的音频元数据。
481. 使用 **GetMediaLibraryClientInstance** 接口来获取 **Medialibrary** 实例。
49 ```cpp
50 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
51 ```
522. 在 **selection** 内设置音频文件的扫描目录。selection 代表媒体公共根目录的相对路径, i.e. "/storage/media/local/files"。接口会在指定目录内递归查找所有音频文件。
53 ```cpp
54 string selection = "audios/audio1";
55 ```
563. 使用 **GetAudioAssets** 接口来查询音频文件。输入参数 *selectionArgs* 暂无作用，接口会返回 *AudioAsset* 的列表。
57 ```cpp
58 vector<string> selectionArgs;
59 vector<unique_ptr<AudioAsset>> audioAssets = mediaLibClientInstance->GetAudioAssets(selection, selectionArgs);
60 ```
614. 可以从列表内获取音频元数据信息。
62 ```cpp
63 for (size_t i = 0; i < audioAssets.size(); i++) {
64 cout << audioAssets[i]->uri_ << endl;
65 cout << audioAssets[i]->size_ << endl;
66 cout << audioAssets[i]->dateAdded_ << endl;
67 cout << audioAssets[i]->dateModified_ << endl;
68 cout << audioAssets[i]->albumName_ << endl;
69 cout << audioAssets[i]->duration_ << endl;
70 cout << audioAssets[i]->artist_ << endl;
71 }
72 ```
73
74### 创建相册<a name="create-album"></a>
75MediaLibrary 给应用提供了操作相册的接口, 如创建、修改和删除。以下展示了创建一个新相册的步骤。
761. 使用 **GetMediaLibraryInstance** 接口来获取 **Medialibrary** 实例。
77 ```cpp
78 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
79 ```
802. 选择一种相册类型, 可以是 *ASSET_GENERIC_ALBUM*、*ASSET_IMAGEALBUM* 或 *ASSET_VIDEOALBUM* 。
81 ```cpp
82 AssetType assetType = ASSET_VIDEOALBUM;
83 ```
843. 创建一个 **AlbumAsset** 并提供相册名称。如下 "new_video" 相册将在 "/storage/media/local/files/videos" 内被创建。
85 ```cpp
86 AlbumAsset albumAsset;
87 albumAsset.albumName_ = "videos/new_video";
88 ```
894. 使用 **CreateMediaAlbumAsset** 接口来创建新相册, 返回值表示相册创建的成功与否。
90 ```cpp
91 bool errCode = mediaLibClientInstance->CreateMediaAlbumAsset(assetType, albumAsset);
92 ```
93
94### 拷贝图片资产<a name="copy-imageasset"></a>
95文件操作通过如**CreateMediaAsset**、**ModifyMediaAsset**、**CopyMediaAsset**、**DeleteMediaAsset** 的接口支持。以下例子说明 **CopyMediaAsset** 接口的使用方法。
961. 使用 **GetMediaLibraryInstance** 接口来获取 **Medialibrary** 实例。
97 ```cpp
98 IMediaLibraryClient* mediaLibClientInstance = IMediaLibraryClient::GetMediaLibraryClientInstance();
99 ```
1002. 选择一种资产类型, 可以是 *ASSET_MEDIA*、*ASSET_IMAGE*、*ASSET_AUDIO* 或 *ASSET_VIDEO*.
101 ```cpp
102 AssetType assetType = ASSET_IMAGE;
103 ```
1043. 确定 **ImageAsset** 的源和目标位置, 目标资产需要指定源拷贝的目标相册名。
105 ```cpp
106 MediaAsset srcMediaAsset;
107 MediaAsset dstMediaAsset;
108
109 srcMediaAsset.name_ = "image1.jpg";
110 srcMediaAsset.uri_ = "/storage/media/local/files/images/001/image1.jpg";
111
112 dstMediaAsset.albumName_ = "images/new_image";
113 ```
1144. 使用 **CopyMediaAsset** 接口来从源资产拷贝到目标资产相册目录, 接口返回值表示文件操作状态。源文件 "image1.jpg" 将会被拷贝到 "/storage/media/local/files/images/new_image" 。
115 ```cpp
116 bool errCode = mediaLibClientInstance->CopyMediaAsset(assetType, srcMediaAsset, dstMediaAsset);
117 ```
118
119## 相关仓<a name="section1533973044317"></a>
120**[multimedia/medialibrary_standard](https://gitee.com/openharmony/multimedia_medialibrary_standard)**
121
