1# Managing Media Assets
2
3Applications can call **photoAccessHelper** APIs to manage media assets (images and videos).
4
5> **NOTE**
6>
7> - Before you get started, obtain a **PhotoAccessHelper** instance and apply for required permissions. For details, see [Before You Start](photoAccessHelper-preparation.md).
8> - Unless otherwise specified, the **PhotoAccessHelper** instance obtained in the **Before You Start** section is used to call **photoAccessHelper** APIs. If the code for obtaining the **PhotoAccessHelper** instance is missing, an error will be reported to indicate that **photoAccessHelper** is not defined.
9
10To ensure application running efficiency, most PhotoAccessHelper APIs are asynchronously implemented in callback or promise mode. The following examples use promise-based APIs. For details about the APIs, see [Album Management](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md).
11
12## Obtaining Media Assets
13
14You can obtain media assets based on the specified conditions, such as the media type, date, or album name.
15
16Use [PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-1) with the [FetchOptions](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchoptions) object to specify the search criteria. Unless otherwise specified, all the media assets to be obtained in this document exist in the database. If no media asset is obtained when the sample code is executed, check whether the media assets exist in the database.
17
18To obtain the object at the specified position (for example, the first one, the last one, or the one with the specified index) in the result set, use [FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult).
19
20**Prerequisites**
21
22- A **PhotoAccessHelper** instance is obtained.
23- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
24- The [dataSharePredicates](../../reference/apis-arkdata/js-apis-data-dataSharePredicates.md) module is imported.
25
26### Obtaining an Image or Video by Name
27
28Example: Obtain the image **test.jpg**.
29
30```ts
31import { dataSharePredicates } from '@kit.ArkData';
32import { photoAccessHelper } from '@kit.MediaLibraryKit';
33const context = getContext(this);
34let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
35
36async function example() {
37  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
38  predicates.equalTo(photoAccessHelper.PhotoKeys.DISPLAY_NAME, 'test.jpg');
39  let fetchOptions: photoAccessHelper.FetchOptions = {
40    fetchColumns: [],
41    predicates: predicates
42  };
43  try {
44    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
45    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
46    console.info('getAssets photoAsset.displayName : ' + photoAsset.displayName);
47    fetchResult.close();
48  } catch (err) {
49    console.error('getAssets failed with err: ' + err);
50  }
51}
52```
53
54## Obtaining an Image or Video Thumbnail
55
56The thumbnails offer a quick preview on images and videos. You can use [PhotoAsset.getThumbnail](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getthumbnail-2)  with the thumbnail size specified to obtain the image or video thumbnail.
57
58**Prerequisites**
59
60- A **PhotoAccessHelper** instance is obtained.
61- The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
62- The [dataSharePredicates](../../reference/apis-arkdata/js-apis-data-dataSharePredicates.md) module is imported.
63
64### Obtaining the Thumbnail of an Image
65
66Your application may need to obtain the thumbnail of an image or video for preview purposes.
67
68For example, obtain the file descriptor (FD) of an image, and decode the image into a pixel map for display or processing. For details, see [Image Decoding](../image/image-decoding.md).
69
70Example: Obtain the thumbnail at the size of 720 x 720 of an image.
71
72**How to Develop**
73
741. Set the fetch options.
752. Call [PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-1) to obtain image assets.
763. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first image from the result set.
774. Call **PhotoAsset.getThumbnail** to obtain the [PixelMap](../../reference/apis-image-kit/js-apis-image.md#pixelmap7) of the thumbnail of the image.
78
79```ts
80import { dataSharePredicates } from '@kit.ArkData';
81import { image } from '@kit.ImageKit';
82import { photoAccessHelper } from '@kit.MediaLibraryKit';
83const context = getContext(this);
84let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
85
86async function example() {
87  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
88  let fetchOptions: photoAccessHelper.FetchOptions = {
89    fetchColumns: [],
90    predicates: predicates
91  };
92
93  try {
94    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
95    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
96    console.info('getAssets photoAsset.displayName : ' + photoAsset.displayName);
97    let size: image.Size = { width: 720, height: 720 };
98    let pixelMap: image.PixelMap =  await photoAsset.getThumbnail(size);
99    let imageInfo: image.ImageInfo = await pixelMap.getImageInfo()
100    console.info('getThumbnail successful, pixelMap ImageInfo size: ' + JSON.stringify(imageInfo.size));
101    fetchResult.close();
102  } catch (err) {
103    console.error('getThumbnail failed with err: ' + err);
104  }
105}
106```
107
108<!--Del-->
109## Creating a Media Asset
110
111Use [MediaAssetChangeRequest](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#mediaassetchangerequest11) to create a media asset change request object for a media asset, and use [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to apply the changes.
112
113**Prerequisites**
114
115- A **PhotoAccessHelper** instance is obtained.
116- The application has the ohos.permission.WRITE_IMAGEVIDEO permission. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
117
118### Creating an Image or Video Asset (for System Applications Only)
119
120Example: Create an image asset.
121
122**How to Develop**
123
1241. Set the file name and create **createOption** for setting attributes for the image asset to create.
1252. Call **MediaAssetChangeRequest.createAssetRequest** to create a media asset change request object.
1263. Call **MediaAssetChangeRequest.getWriteCacheHandler** to obtain the handle of the file to write and write the content of the image asset.
1274. Call **PhotoAccessHelper.applyChanges** to apply the changes to the image.
128
129```ts
130import { photoAccessHelper } from '@kit.MediaLibraryKit';
131import { fileIo } from '@kit.CoreFileKit';
132let context = getContext(this);
133let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
134
135async function example() {
136  try {
137    let displayName: string = 'testPhoto' + Date.now() + '.jpg';
138    let createOption: photoAccessHelper.PhotoCreateOptions = {
139      subtype: photoAccessHelper.PhotoSubtype.DEFAULT
140    };
141    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, displayName, createOption);
142    let fd: number = await assetChangeRequest.getWriteCacheHandler();
143    // write date into fd
144    await fileIo.close(fd);
145    await phAccessHelper.applyChanges(assetChangeRequest);
146  } catch (err) {
147    console.error(`create asset failed with error: ${err.code}, ${err.message}`);
148  }
149}
150```
151
152You can also use **MediaAssetChangeRequest.addResource** to specify the data source information of the media asset, including the [application sandbox](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#addresource11), [ArrayBuffer](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#addresource11-1), and [PhotoProxy](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#addresource11).
153<!--DelEnd-->
154
155## Renaming a Media Asset
156
157To rename a media asset, change the **PhotoAsset.displayName** attribute, that is, the file name (including the file name extension) displayed.
158
159Use [FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult) to obtain the file to rename, use [MediaAssetChangeRequest.setTitle](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#settitle11) to set the new name, and then use [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to apply the changes to the database.
160
161**Prerequisites**
162
163- A **PhotoAccessHelper** instance is obtained.
164- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
165
166Example: Rename the first image in the obtained image assets.
167
168**How to Develop**
169
1701. Set the fetch options.
1712. Call [PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-1) to obtain image assets.
1723. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first image from the obtained file assets.
1734. Call [MediaAssetChangeRequest.setTitle](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#settitle11) to rename the image.
1745. Call [PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11) to save the modification to the database.
175
176```ts
177import { dataSharePredicates } from '@kit.ArkData';
178import { photoAccessHelper } from '@kit.MediaLibraryKit';
179let context = getContext(this);
180let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
181
182async function example() {
183  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
184  let fetchOptions: photoAccessHelper.FetchOptions = {
185    fetchColumns: ['title'],
186    predicates: predicates
187  };
188  let newTitle: string = 'newTestPhoto';
189
190  try {
191    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
192    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
193    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
194    assetChangeRequest.setTitle(newTitle);
195    await phAccessHelper.applyChanges(assetChangeRequest);
196    fetchResult.close();
197  } catch (err) {
198    console.error(`rename failed with error: ${err.code}, ${err.message}`);
199  }
200}
201```
202
203## Moving a Media Asset to the Trash
204
205You can use [MediaAssetChangeRequest.deleteAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#deleteassets11) to move files to the trash.
206
207The file moved to the trash will be retained for 30 days before being deleted permanently. Before a file is deleted permanently from the trash, the user can restore it using the system application **Files** or **Gallery**.
208
209**Prerequisites**
210
211- A **PhotoAccessHelper** instance is obtained.
212- The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see [Requesting Permissions](photoAccessHelper-preparation.md#requesting-permissions).
213
214Example: Move the first file in the result set to the trash.
215
216**How to Develop**
217
2181. Set the fetch options.
2192. Call [PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-1) to obtain image assets.
2203. Call [FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1) to obtain the first image.
2214. Call [MediaAssetChangeRequest.deleteAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#deleteassets11) to move the image to the trash.
222
223```ts
224import { dataSharePredicates } from '@kit.ArkData';
225import { photoAccessHelper } from '@kit.MediaLibraryKit';
226let context = getContext(this);
227let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
228
229async function example() {
230  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
231  let fetchOptions: photoAccessHelper.FetchOptions = {
232    fetchColumns: [],
233    predicates: predicates
234  };
235
236  try {
237    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
238    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
239    await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, [photoAsset]);
240    fetchResult.close();
241  } catch (err) {
242    console.error(`deleteAssets failed with error: ${err.code}, ${err.message}`);
243  }
244}
245```
246