1# Interface (MetadataOutput) 2<!--Kit: Camera Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @qano--> 5<!--SE: @leo_ysl--> 6<!--TSE: @xchaosioda--> 7 8> **NOTE** 9> 10> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 11 12MetadataOutput implements metadata streams. It inherits from [CameraOutput](arkts-apis-camera-CameraOutput.md). 13 14## Modules to Import 15 16```ts 17import { camera } from '@kit.CameraKit'; 18``` 19 20## start 21 22start(callback: AsyncCallback\<void\>): void 23 24Starts to output metadata. This API uses an asynchronous callback to return the result. 25 26**Atomic service API**: This API can be used in atomic services since API version 19. 27 28**System capability**: SystemCapability.Multimedia.Camera.Core 29 30**Parameters** 31 32| Name | Type | Mandatory| Description | 33| -------- | -------------------------- | ---- | ------------------- | 34| callback | AsyncCallback\<void\> | Yes | Callback used to return the result. If the operation fails, an error code defined in [CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode) is returned.| 35 36**Error codes** 37 38For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 39 40| ID | Error Message | 41| --------------- | --------------- | 42| 7400103 | Session not config. | 43| 7400201 | Camera service fatal error. | 44 45**Example** 46 47```ts 48import { BusinessError } from '@kit.BasicServicesKit'; 49 50function startMetadataOutput(metadataOutput: camera.MetadataOutput): void { 51 metadataOutput.start((err: BusinessError) => { 52 if (err) { 53 console.error(`Failed to start metadata output, error code: ${err.code}.`); 54 return; 55 } 56 console.info('Callback returned with metadata output started.'); 57 }); 58} 59``` 60 61## start 62 63start(): Promise\<void\> 64 65Starts to output metadata. This API uses a promise to return the result. 66 67**Atomic service API**: This API can be used in atomic services since API version 19. 68 69**System capability**: SystemCapability.Multimedia.Camera.Core 70 71**Return value** 72 73| Type | Description | 74| ---------------------- | ------------------------ | 75| Promise\<void\> | Promise that returns no value.| 76 77**Error codes** 78 79For details about the error codes, see [Camera Error Codes](errorcode-camera.md). 80 81| ID | Error Message | 82| --------------- | --------------- | 83| 7400103 | Session not config. | 84| 7400201 | Camera service fatal error. | 85 86**Example** 87 88```ts 89import { BusinessError } from '@kit.BasicServicesKit'; 90 91function startMetadataOutput(metadataOutput: camera.MetadataOutput): void { 92 metadataOutput.start().then(() => { 93 console.info('Callback returned with metadata output started.'); 94 }).catch((error: BusinessError) => { 95 console.error(`Failed to metadata output stop, error code: ${error.code}`); 96 }); 97} 98``` 99 100## stop 101 102stop(callback: AsyncCallback\<void\>): void 103 104Stops outputting metadata. This API uses an asynchronous callback to return the result. 105 106**Atomic service API**: This API can be used in atomic services since API version 19. 107 108**System capability**: SystemCapability.Multimedia.Camera.Core 109 110**Parameters** 111 112| Name | Type | Mandatory| Description | 113| -------- | -------------------------- | ---- | ------------------- | 114| callback | AsyncCallback\<void\> | Yes | Callback used to return the result.| 115 116**Example** 117 118```ts 119import { BusinessError } from '@kit.BasicServicesKit'; 120 121function stopMetadataOutput(metadataOutput: camera.MetadataOutput): void { 122 metadataOutput.stop((err: BusinessError) => { 123 if (err) { 124 console.error(`Failed to stop the metadata output, error code: ${err.code}.`); 125 return; 126 } 127 console.info('Callback returned with metadata output stopped.'); 128 }) 129} 130``` 131 132## stop 133 134stop(): Promise\<void\> 135 136Stops outputting metadata. This API uses a promise to return the result. 137 138**Atomic service API**: This API can be used in atomic services since API version 19. 139 140**System capability**: SystemCapability.Multimedia.Camera.Core 141 142**Return value** 143 144| Type | Description | 145| ---------------------- | --------------------------- | 146| Promise\<void\> | Promise that returns no value.| 147 148**Example** 149 150```ts 151import { BusinessError } from '@kit.BasicServicesKit'; 152 153function stopMetadataOutput(metadataOutput: camera.MetadataOutput): void { 154 metadataOutput.stop().then(() => { 155 console.info('Callback returned with metadata output stopped.'); 156 }).catch((error: BusinessError) => { 157 console.error(`Failed to metadata output stop, error code: ${error.code}`); 158 }); 159} 160``` 161 162## on('metadataObjectsAvailable') 163 164on(type: 'metadataObjectsAvailable', callback: AsyncCallback\<Array\<MetadataObject\>\>): void 165 166Subscribes to events indicating available metadata objects. This API uses an asynchronous callback to return the result. 167 168> **NOTE** 169> 170> Currently, you cannot use **off()** to unregister the callback in the callback method of **on()**. 171 172**Atomic service API**: This API can be used in atomic services since API version 19. 173 174**System capability**: SystemCapability.Multimedia.Camera.Core 175 176**Parameters** 177 178| Name | Type | Mandatory| Description | 179| -------- | -------------- | ---- | ------------------------------------ | 180| type | string | Yes | Event type. The value is fixed at **'metadataObjectsAvailable'**. The event can be listened for when a metadataOutput instance is created. This event is triggered and the corresponding metadata is returned when valid metadata is detected.| 181| callback | AsyncCallback\<Array\<[MetadataObject](arkts-apis-camera-i.md#metadataobject)\>\> | Yes | Callback used to return the metadata.| 182 183**Example** 184 185```ts 186import { BusinessError } from '@kit.BasicServicesKit'; 187 188function callback(err: BusinessError, metadataObjectArr: Array<camera.MetadataObject>): void { 189 if (err !== undefined && err.code !== 0) { 190 console.error(`Callback Error, errorCode: ${err.code}`); 191 return; 192 } 193 console.info('metadata output metadataObjectsAvailable'); 194} 195 196function registerMetadataObjectsAvailable(metadataOutput: camera.MetadataOutput): void { 197 metadataOutput.on('metadataObjectsAvailable', callback); 198} 199``` 200 201## off('metadataObjectsAvailable') 202 203off(type: 'metadataObjectsAvailable', callback?: AsyncCallback\<Array\<MetadataObject\>\>): void 204 205Unsubscribes from events indicating available metadata objects. 206 207**Atomic service API**: This API can be used in atomic services since API version 19. 208 209**System capability**: SystemCapability.Multimedia.Camera.Core 210 211**Parameters** 212 213| Name | Type | Mandatory| Description | 214| -------- | -------------- | ---- | ------------------------------------ | 215| type | string | Yes | Event type. The value is fixed at **'metadataObjectsAvailable'**. The event can be listened for when a metadataOutput instance is created.| 216| callback | AsyncCallback\<Array\<[MetadataObject](arkts-apis-camera-i.md#metadataobject)\>\> | No | Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.| 217 218**Example** 219 220```ts 221function unregisterMetadataObjectsAvailable(metadataOutput: camera.MetadataOutput): void { 222 metadataOutput.off('metadataObjectsAvailable'); 223} 224``` 225 226## on('error') 227 228on(type: 'error', callback: ErrorCallback): void 229 230Subscribes to metadata error events. This API uses an asynchronous callback to return the result. 231 232> **NOTE** 233> 234> Currently, you cannot use **off()** to unregister the callback in the callback method of **on()**. 235 236**Atomic service API**: This API can be used in atomic services since API version 19. 237 238**System capability**: SystemCapability.Multimedia.Camera.Core 239 240**Parameters** 241 242| Name | Type | Mandatory| Description | 243| -------- | ------------- | ---- | --------------------------------------- | 244| type | string | Yes | Event type. The value is fixed at **'error'**. The event can be listened for when a metadataOutput instance is created. This event is triggered and the corresponding error message is returned when an error occurs during the use of a metadata-related API such as [start](#start-1) or [CameraOutput.release](arkts-apis-camera-CameraOutput.md#release-1).| 245| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | Yes | Callback used to return an error code defined in [CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode). | 246 247**Example** 248 249```ts 250import { BusinessError } from '@kit.BasicServicesKit'; 251 252function callback(metadataOutputError: BusinessError): void { 253 console.error(`Metadata output error code: ${metadataOutputError.code}`); 254} 255 256function registerMetadataOutputError(metadataOutput: camera.MetadataOutput): void { 257 metadataOutput.on('error', callback); 258} 259``` 260 261## off('error') 262 263off(type: 'error', callback?: ErrorCallback): void 264 265Unsubscribes from metadata error events. 266 267**Atomic service API**: This API can be used in atomic services since API version 19. 268 269**System capability**: SystemCapability.Multimedia.Camera.Core 270 271**Parameters** 272 273| Name | Type | Mandatory| Description | 274| -------- | ------------- | ---- | --------------------------------------- | 275| type | string | Yes | Event type. The value is fixed at **'error'**. The event can be listened for when a metadataOutput instance is created.| 276| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | No | Callback used to return the result. If this parameter is specified, the subscription to the specified event with the specified callback is canceled. (The callback object cannot be an anonymous function.) Otherwise, the subscriptions to the specified event with all the callbacks are canceled.| 277 278**Example** 279 280```ts 281function unregisterMetadataOutputError(metadataOutput: camera.MetadataOutput): void { 282 metadataOutput.off('error'); 283} 284``` 285