1# Camera Metadata (ArkTS)
2
3Before developing a camera application, request permissions by following the instructions provided in [Camera Development Preparations](camera-preparation.md).
4
5Metadata is the description and context of image information returned by the camera application. It provides detailed data for the image information, such as the coordinates of a viewfinder frame for identifying a portrait in a photo or video.
6
7Metadata uses a tag (key) to find the corresponding data during parameter transfers and configurations, reducing memory copy operations.
8
9## How to Develop
10
11Read [Camera](../../reference/apis-camera-kit/js-apis-camera.md) for the API reference.
12
131. Import the modules.
14   ```ts
15   import { camera } from '@kit.CameraKit';
16   import { BusinessError } from '@kit.BasicServicesKit';
17   ```
18
192. Obtain the metadata types supported by the current device from **supportedMetadataObjectTypes** in the [CameraOutputCapability](../../reference/apis-camera-kit/js-apis-camera.md#cameraoutputcapability) class, and then use [createMetadataOutput](../../reference/apis-camera-kit/js-apis-camera.md#createmetadataoutput) to create a metadata output stream.
20
21   ```ts
22   function getMetadataOutput(cameraManager: camera.CameraManager, cameraOutputCapability: camera.CameraOutputCapability): camera.MetadataOutput | undefined {
23     let metadataObjectTypes: Array<camera.MetadataObjectType> = cameraOutputCapability.supportedMetadataObjectTypes;
24     let metadataOutput: camera.MetadataOutput | undefined = undefined;
25     try {
26       metadataOutput = cameraManager.createMetadataOutput(metadataObjectTypes);
27     } catch (error) {
28       let err = error as BusinessError;
29       console.error(`Failed to createMetadataOutput, error code: ${err.code}`);
30     }
31     return metadataOutput;
32   }
33   ```
34
353. Call [Session.start](../../reference/apis-camera-kit/js-apis-camera.md#start11) to start outputting metadata, and obtain the data through subscription to the **'metadataObjectsAvailable'** event. If the call fails, an error code is returned. For details, see [CameraErrorCode](../../reference/apis-camera-kit/js-apis-camera.md#cameraerrorcode).
36
37   For details about how to obtain preview output, see [Camera Preview (ArkTS)](camera-preview.md).
38   ```ts
39   async function startMetadataOutput(previewOutput: camera.PreviewOutput, metadataOutput: camera.MetadataOutput, cameraManager: camera.CameraManager): Promise<void> {
40     let cameraArray: Array<camera.CameraDevice> = [];
41     cameraArray = cameraManager.getSupportedCameras();
42     if (cameraArray.length == 0) {
43       console.error('no camera.');
44       return;
45     }
46     // Obtain the supported modes.
47     let sceneModes: Array<camera.SceneMode> = cameraManager.getSupportedSceneModes(cameraArray[0]);
48     let isSupportPhotoMode: boolean = sceneModes.indexOf(camera.SceneMode.NORMAL_PHOTO) >= 0;
49     if (!isSupportPhotoMode) {
50       console.error('photo mode not support');
51       return;
52     }
53     let cameraInput: camera.CameraInput | undefined = undefined;
54     cameraInput = cameraManager.createCameraInput(cameraArray[0]);
55     if (cameraInput === undefined) {
56       console.error('cameraInput is undefined');
57       return;
58     }
59     // Open a camera.
60     await cameraInput.open();
61     let session: camera.PhotoSession = cameraManager.createSession(camera.SceneMode.NORMAL_PHOTO) as camera.PhotoSession;
62     session.beginConfig();
63     session.addInput(cameraInput);
64     session.addOutput(previewOutput);
65     session.addOutput(metadataOutput);
66     await session.commitConfig();
67     await session.start();
68   }
69   ```
70
714. Call [Session.stop](../../reference/apis-camera-kit/js-apis-camera.md#stop11) to stop outputting metadata. If the call fails, an error code is returned. For details, see [CameraErrorCode](../../reference/apis-camera-kit/js-apis-camera.md#cameraerrorcode).
72
73   ```ts
74   function stopMetadataOutput(session: camera.Session): void {
75     session.stop().then(() => {
76       console.info('Callback returned with session stopped.');
77     }).catch((err: BusinessError) => {
78       console.error(`Failed to session stop, error code: ${err.code}`);
79     });
80   }
81   ```
82
83## Status Listening
84
85During camera application development, you can listen for the status of metadata objects and output stream.
86
87- Register the **'metadataObjectsAvailable'** event to listen for metadata objects that are available. When a valid metadata object is detected, the callback function returns the metadata. This event can be registered when a **MetadataOutput** object is created.
88
89  ```ts
90  function onMetadataObjectsAvailable(metadataOutput: camera.MetadataOutput): void {
91    metadataOutput.on('metadataObjectsAvailable', (err: BusinessError, metadataObjectArr: Array<camera.MetadataObject>) => {
92      if (err !== undefined && err.code !== 0) {
93        return;
94      }
95      console.info('metadata output metadataObjectsAvailable');
96    });
97  }
98  ```
99
100  > **NOTE**
101  >
102  > Currently, only **FACE_DETECTION** is available for the metadata type. The metadata object is the rectangle of the recognized face, including the x-axis coordinate and y-axis coordinate of the upper left corner of the rectangle as well as the width and height of the rectangle.
103
104- Register the **'error'** event to listen for metadata stream errors. The callback function returns an error code when an API is incorrectly used. For details about the error code types, see [CameraErrorCode](../../reference/apis-camera-kit/js-apis-camera.md#cameraerrorcode).
105
106  ```ts
107  function onMetadataError(metadataOutput: camera.MetadataOutput): void {
108    metadataOutput.on('error', (metadataOutputError: BusinessError) => {
109      console.error(`Metadata output error code: ${metadataOutputError.code}`);
110    });
111  }
112  ```
113