1# Interface (VideoOutput) 2<!--Kit: Camera Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @qano--> 5<!--Designer: @leo_ysl--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12 13录像会话中使用的输出信息，继承[CameraOutput](arkts-apis-camera-CameraOutput.md)。 14 15## 导入模块 16 17```ts 18import { camera } from '@kit.CameraKit'; 19``` 20 21## start 22 23start(callback: AsyncCallback\<void\>): void 24 25启动录制，通过注册回调函数获取结果。使用callback异步回调。 26 27**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.Multimedia.Camera.Core 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| -------- | -------------------- | ---- | -------------------- | 35| callback | AsyncCallback\<void\> | 是 | 回调函数。当启动录制成功，err为undefined，否则为错误对象。错误码类型[CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode)。 | 36 37**错误码：** 38 39以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 40 41| 错误码ID | 错误信息 | 42| --------------- | --------------- | 43| 7400103 | Session not config. | 44| 7400201 | Camera service fatal error. | 45 46**示例：** 47 48```ts 49import { BusinessError } from '@kit.BasicServicesKit'; 50 51function startVideoOutput(videoOutput: camera.VideoOutput): void { 52 videoOutput.start((err: BusinessError) => { 53 if (err.code) { 54 console.error(`Failed to start the video output, error code: ${err.code}.`); 55 return; 56 } 57 console.info('Callback invoked to indicate the video output start success.'); 58 }); 59} 60``` 61 62## start 63 64start(): Promise\<void\> 65 66启动录制。使用Promise异步回调。 67 68**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 69 70**系统能力：** SystemCapability.Multimedia.Camera.Core 71 72**返回值：** 73 74| 类型 | 说明 | 75| -------------- | ----------------------- | 76| Promise\<void\> | Promise对象，无返回结果。 | 77 78**错误码：** 79 80以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 81 82| 错误码ID | 错误信息 | 83| --------------- | --------------- | 84| 7400103 | Session not config. | 85| 7400201 | Camera service fatal error. | 86 87**示例：** 88 89```ts 90import { BusinessError } from '@kit.BasicServicesKit'; 91 92function startVideoOutput(videoOutput: camera.VideoOutput): void { 93 videoOutput.start().then(() => { 94 console.info('Promise returned to indicate that start method execution success.'); 95 }).catch((error: BusinessError) => { 96 console.error(`Failed to video output start, error code: ${error.code}.`); 97 }); 98} 99``` 100 101## stop 102 103stop(callback: AsyncCallback\<void\>): void 104 105结束录制，通过注册回调函数获取结果。使用callback异步回调。 106 107**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 108 109**系统能力：** SystemCapability.Multimedia.Camera.Core 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| -------- | -------------------- | ---- | ------------------------ | 115| callback | AsyncCallback\<void\> | 是 | 回调函数。当结束录制成功，err为undefined，否则为错误对象。 | 116 117**示例：** 118 119```ts 120import { BusinessError } from '@kit.BasicServicesKit'; 121 122function stopVideoOutput(videoOutput: camera.VideoOutput): void { 123 videoOutput.stop(() => { 124 console.info('Callback invoked to indicate the video output stop success.'); 125 }); 126} 127``` 128 129## stop 130 131stop(): Promise\<void\> 132 133结束录制。使用Promise异步回调。 134 135**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 136 137**系统能力：** SystemCapability.Multimedia.Camera.Core 138 139**返回值：** 140 141| 类型 | 说明 | 142| -------------- | ----------------------- | 143| Promise\<void\> | Promise对象，无返回结果。 | 144 145**示例：** 146 147```ts 148import { BusinessError } from '@kit.BasicServicesKit'; 149 150function stopVideoOutput(videoOutput: camera.VideoOutput): void { 151 videoOutput.stop().then(() => { 152 console.info('Promise returned to indicate that stop method execution success.'); 153 }).catch((error: BusinessError) => { 154 console.error(`Failed to video output stop, error code: ${error.code}.`); 155 }); 156} 157``` 158 159## on('frameStart') 160 161on(type: 'frameStart', callback: AsyncCallback\<void\>): void 162 163监听录像开始，通过注册回调函数获取结果。使用callback异步回调。 164 165> **说明：** 166> 167> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 168 169**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 170 171**系统能力：** SystemCapability.Multimedia.Camera.Core 172 173**参数：** 174 175| 参数名 | 类型 | 必填 | 说明 | 176| -------- | -------------------- | ---- | ----------------------------------------- | 177| type | string | 是 | 监听事件，固定为'frameStart'，videoOutput创建成功后可监听。底层第一次曝光时触发该事件并返回。 | 178| callback | AsyncCallback\<void\> | 是 | 回调函数，用于获取结果。 只要有该事件返回就证明录像开始。 | 179 180**示例：** 181 182```ts 183import { BusinessError } from '@kit.BasicServicesKit'; 184 185function callback(err: BusinessError): void { 186 if (err.code) { 187 console.error(`Callback Error, errorCode: ${err.code}`); 188 return; 189 } 190 console.info('Video frame started'); 191} 192 193function registerVideoOutputFrameStart(videoOutput: camera.VideoOutput): void { 194 videoOutput.on('frameStart', callback); 195} 196``` 197 198## off('frameStart') 199 200off(type: 'frameStart', callback?: AsyncCallback\<void\>): void 201 202注销监听录像开始。 203 204> **说明：** 205> 206> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 207 208**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 209 210**系统能力：** SystemCapability.Multimedia.Camera.Core 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| -------- | -------------------- | ---- | ----------------------------------------- | 216| type | string | 是 | 监听事件，固定为'frameStart'，videoOutput创建成功后可监听。 | 217| callback | AsyncCallback\<void\> | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 218 219**示例：** 220 221```ts 222function unregisterVideoOutputFrameStart(videoOutput: camera.VideoOutput): void { 223 videoOutput.off('frameStart'); 224} 225 226``` 227 228## on('frameEnd') 229 230on(type: 'frameEnd', callback: AsyncCallback\<void\>): void 231 232监听录像结束，通过注册回调函数获取结果。使用callback异步回调。 233 234**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.Multimedia.Camera.Core 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| -------- | -------------------- | ---- | ------------------------------------------ | 242| type | string | 是 | 监听事件，固定为'frameEnd'，videoOutput创建成功后可监听。录像完全结束最后一帧时触发该事件并返回。 | 243| callback | AsyncCallback\<void\> | 是 | 回调函数，用于获取结果。 只要有该事件返回就证明录像结束。 | 244 245**示例：** 246 247```ts 248import { BusinessError } from '@kit.BasicServicesKit'; 249 250function callback(err: BusinessError): void { 251 if (err.code) { 252 console.error(`Callback Error, errorCode: ${err.code}`); 253 return; 254 } 255 console.info('Video frame ended'); 256} 257 258function registerVideoOutputFrameEnd(videoOutput: camera.VideoOutput): void { 259 videoOutput.on('frameEnd', callback); 260} 261``` 262 263## off('frameEnd') 264 265off(type: 'frameEnd', callback?: AsyncCallback\<void\>): void 266 267注销监听录像结束。 268 269**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 270 271**系统能力：** SystemCapability.Multimedia.Camera.Core 272 273**参数：** 274 275| 参数名 | 类型 | 必填 | 说明 | 276| -------- | -------------------- | ---- | ------------------------------------------ | 277| type | string | 是 | 监听事件，固定为'frameEnd'，videoOutput创建成功后可监听。 | 278| callback | AsyncCallback\<void\> | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 279 280**示例：** 281 282```ts 283function unregisterVideoOutputFrameEnd(videoOutput: camera.VideoOutput): void { 284 videoOutput.off('frameEnd'); 285} 286``` 287 288## on('error') 289 290on(type: 'error', callback: ErrorCallback): void 291 292监听录像输出发生错误，通过注册回调函数获取结果。使用callback异步回调。 293 294> **说明：** 295> 296> 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。 297 298**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 299 300**系统能力：** SystemCapability.Multimedia.Camera.Core 301 302**参数：** 303 304| 参数名 | 类型 | 必填 | 说明 | 305| -------- | ----------- | ---- | -------------------------------------- | 306| type | string | 是 | 监听事件，固定为'error'，videoOutput创建成功后可监听。录像接口调用出现错误时触发该事件并返回对应错误码，比如调用[start](#start-1)，[CameraOutput.release](arkts-apis-camera-CameraOutput.md#release-1)接口时出现错误返回对应错误信息。 | 307| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 回调函数，用于获取错误信息。返回错误码，错误码类型[CameraErrorCode](arkts-apis-camera-e.md#cameraerrorcode)。 | 308 309**示例：** 310 311```ts 312import { BusinessError } from '@kit.BasicServicesKit'; 313 314function callback(err: BusinessError): void { 315 console.error(`Video output error code: ${err.code}`); 316} 317 318function registerVideoOutputError(videoOutput: camera.VideoOutput): void { 319 videoOutput.on('error', callback); 320} 321``` 322 323## off('error') 324 325off(type: 'error', callback?: ErrorCallback): void 326 327注销监听录像输出发生错误。 328 329**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 330 331**系统能力：** SystemCapability.Multimedia.Camera.Core 332 333**参数：** 334 335| 参数名 | 类型 | 必填 | 说明 | 336| -------- | ------------- | ---- | ----------------------------------- | 337| type | string | 是 | 监听事件，固定为'error'，photoOutput创建成功后可监听。 | 338| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。 | 339 340**示例：** 341 342```ts 343function unregisterVideoOutputError(videoOutput: camera.VideoOutput): void { 344 videoOutput.off('error'); 345} 346``` 347 348## getSupportedFrameRates<sup>12+</sup> 349 350getSupportedFrameRates(): Array\<FrameRateRange\> 351 352查询支持的帧率范围。 353 354**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 355 356**系统能力：** SystemCapability.Multimedia.Camera.Core 357 358**返回值：** 359 360| 类型 | 说明 | 361| ------------- | ------------ | 362| Array<[FrameRateRange](arkts-apis-camera-i.md#frameraterange)> | 支持的帧率范围列表 | 363 364**示例：** 365 366```ts 367function getSupportedFrameRates(videoOutput: camera.VideoOutput): Array<camera.FrameRateRange> { 368 let supportedFrameRatesArray: Array<camera.FrameRateRange> = videoOutput.getSupportedFrameRates(); 369 return supportedFrameRatesArray; 370} 371``` 372 373## setFrameRate<sup>12+</sup> 374 375setFrameRate(minFps: number, maxFps: number): void 376 377设置录像流帧率范围，设置的范围必须在支持的帧率范围内。 378 379进行设置前，可通过[getSupportedFrameRates](#getsupportedframerates12)查询支持的帧率范围。 380 381> **说明：** 382> 383> 仅在[PhotoSession](arkts-apis-camera-PhotoSession.md)或[VideoSession](arkts-apis-camera-VideoSession.md)模式下支持。 384> 385> 接口调用前，先调用[getActiveFrameRate](arkts-apis-camera-VideoOutput.md#getactiveframerate12)接口查询当前VideoSession的帧率，若下发的帧率与当前帧率相等，则下发的帧率不会生效。 386 387**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 388 389**系统能力：** SystemCapability.Multimedia.Camera.Core 390 391**参数：** 392 393| 参数名 | 类型 | 必填 | 说明 | 394| -------- | --------------| ---- | ------------------------ | 395| minFps | number | 是 | 最小帧率，单位：fps。当传入的最大值小于最小值时，传参异常，接口不生效。 | 396| maxFps | number | 是 | 最大帧率，单位：fps。当传入的最小值大于最大值时，传参异常，接口不生效。 | 397 398**错误码：** 399 400以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 401 402| 错误码ID | 错误信息 | 403| --------------- | --------------- | 404| 7400101 | Parameter missing or parameter type incorrect. | 405| 7400110 | Unresolved conflicts with current configurations. | 406 407**示例：** 408 409```ts 410function setFrameRateRange(videoOutput: camera.VideoOutput, frameRateRange: Array<number>): void { 411 videoOutput.setFrameRate(frameRateRange[0], frameRateRange[1]); 412} 413``` 414 415## getActiveFrameRate<sup>12+</sup> 416 417getActiveFrameRate(): FrameRateRange 418 419获取已设置的帧率范围。 420 421使用[setFrameRate](#setframerate12)对录像流设置过帧率后可查询。 422 423**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 424 425**系统能力：** SystemCapability.Multimedia.Camera.Core 426 427**返回值：** 428 429| 类型 | 说明 | 430| ------------- | ------------ | 431| [FrameRateRange](arkts-apis-camera-i.md#frameraterange) | 帧率范围 | 432 433**示例：** 434 435```ts 436function getActiveFrameRate(videoOutput: camera.VideoOutput): camera.FrameRateRange { 437 let activeFrameRate: camera.FrameRateRange = videoOutput.getActiveFrameRate(); 438 return activeFrameRate; 439} 440``` 441 442## getActiveProfile<sup>12+</sup> 443 444getActiveProfile(): VideoProfile 445 446获取当前生效的配置信息。 447 448**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 449 450**系统能力：** SystemCapability.Multimedia.Camera.Core 451 452**返回值：** 453 454| 类型 | 说明 | 455| ------------- |-----------| 456| [VideoProfile](arkts-apis-camera-i.md#videoprofile) | 当前生效的配置信息 | 457 458**错误码：** 459 460以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 461 462| 错误码ID | 错误信息 | 463|---------|------------------------------| 464| 7400201 | Camera service fatal error. | 465 466**示例：** 467 468```ts 469import { BusinessError } from '@kit.BasicServicesKit'; 470 471function testGetActiveProfile(videoOutput: camera.VideoOutput): camera.Profile | undefined { 472 let activeProfile: camera.VideoProfile | undefined = undefined; 473 try { 474 activeProfile = videoOutput.getActiveProfile(); 475 } catch (error) { 476 // 失败返回错误码error.code并处理。 477 let err = error as BusinessError; 478 console.error(`The videoOutput.getActiveProfile call failed. error code: ${err.code}`); 479 } 480 return activeProfile; 481} 482``` 483 484## isMirrorSupported<sup>15+</sup> 485 486isMirrorSupported(): boolean 487 488查询是否支持镜像录像。 489 490**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 491 492**系统能力：** SystemCapability.Multimedia.Camera.Core 493 494**返回值：** 495 496| 类型 | 说明 | 497| -------------- |---------------------------------| 498| boolean | 返回是否支持镜像录像，true表示支持，false表示不支持。 | 499 500**示例：** 501 502```ts 503function testIsMirrorSupported(videoOutput: camera.VideoOutput): boolean { 504 let isSupported: boolean = videoOutput.isMirrorSupported(); 505 return isSupported; 506} 507``` 508 509## enableMirror<sup>15+</sup> 510 511enableMirror(enabled: boolean): void 512 513启用/关闭镜像录像。 514 515- 调用该接口前，需要通过[isMirrorSupported](#ismirrorsupported15)查询是否支录像镜像功能。 516 517- 启用/关闭录像镜像后，需要通过[getVideoRotation](#getvideorotation12)获取录像旋转角度以及[updateRotation](../apis-media-kit/arkts-apis-media-AVRecorder.md#updaterotation12)更新旋转角度。 518 519**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 520 521**系统能力：** SystemCapability.Multimedia.Camera.Core 522 523**参数：** 524 525| 参数名 | 类型 | 必填 | 说明 | 526|----------| ---------------------- | ---- |---------------------------| 527| enabled | boolean | 是 | 启用/关闭镜像录像。true为开启镜像录像，false为关闭镜像录像。 | 528 529**错误码：** 530 531以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 532 533| 错误码ID | 错误信息 | 534| -------- |------------------------------------------------| 535| 7400101 | Parameter missing or parameter type incorrect. | 536| 7400103 | Session not config. | 537 538 539**示例：** 540 541```ts 542import { camera } from '@kit.CameraKit'; 543import { media } from '@kit.MediaKit'; 544import { BusinessError } from '@kit.BasicServicesKit'; 545 546function enableMirror(videoOutput: camera.VideoOutput, mirrorMode: boolean, aVRecorder: media.AVRecorder, deviceDegree : number): void { 547 try { 548 videoOutput.enableMirror(mirrorMode); 549 aVRecorder.updateRotation(videoOutput.getVideoRotation(deviceDegree)); 550 } catch (error) { 551 let err = error as BusinessError; 552 } 553} 554``` 555 556## getVideoRotation<sup>12+</sup> 557 558getVideoRotation(deviceDegree: number): ImageRotation 559 560获取录像旋转角度。 561 562- 设备自然方向：设备默认使用方向，手机为竖屏（充电口向下）。 563- 相机镜头角度：值等于相机图像顺时针旋转到设备自然方向的角度，手机后置相机传感器是横屏安装的，所以需要顺时针旋转90度到设备自然方向。 564- 屏幕显示方向：需要屏幕显示的图片左上角为第一个像素点为坐标原点。锁屏时与自然方向一致。 565 566**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 567 568**系统能力：** SystemCapability.Multimedia.Camera.Core 569 570**参数：** 571 572| 参数名 | 类型 | 必填 | 说明 | 573| -------- | --------------| ---- | ------------------------ | 574| deviceDegree | number | 是 | 设备旋转角度，单位度，取值范围0-360。 | 575 576**返回值：** 577 578| 类型 | 说明 | 579| ------------- |-----------| 580| [ImageRotation](arkts-apis-camera-e.md#imagerotation) | 获取录像旋转角度。 | 581 582**错误码：** 583 584以下错误码的详细介绍请参见[Camera错误码](errorcode-camera.md)。 585 586| 错误码ID | 错误信息 | 587|---------|------------------------------| 588| 7400101 | Parameter missing or parameter type incorrect. | 589| 7400201 | Camera service fatal error. | 590 591**示例：** 592 593```ts 594import { camera } from '@kit.CameraKit'; 595import { Decimal } from '@kit.ArkTS'; 596import { sensor } from '@kit.SensorServiceKit'; 597import { BusinessError } from '@kit.BasicServicesKit'; 598 599async function getVideoRotation(videoOutput: camera.VideoOutput): Promise<camera.ImageRotation> { 600 let deviceDegree = await getDeviceDegree(); 601 let videoRotation: camera.ImageRotation = camera.ImageRotation.ROTATION_0; 602 try { 603 videoRotation = videoOutput.getVideoRotation(deviceDegree); 604 } catch (error) { 605 let err = error as BusinessError; 606 console.error('Failed to get video rotation: ' + JSON.stringify(err)); 607 } 608 return videoRotation; 609} 610 611// 获取设备旋转角度 612function getDeviceDegree(): Promise<number> { 613 return new Promise<number>((resolve) => { 614 try { 615 sensor.once(sensor.SensorId.GRAVITY, (data: sensor.GravityResponse) => { 616 console.info('Succeeded in invoking once. X-coordinate component: ' + data.x); 617 console.info('Succeeded in invoking once. Y-coordinate component: ' + data.y); 618 console.info('Succeeded in invoking once. Z-coordinate component: ' + data.z); 619 let x = data.x; 620 let y = data.y; 621 let z = data.z; 622 let deviceDegree: number; 623 if ((x * x + y * y) * 3 < z * z) { 624 deviceDegree = -1; 625 } else { 626 let sd: Decimal = Decimal.atan2(y, -x); 627 let sc: Decimal = Decimal.round(Number(sd) / 3.141592653589 * 180) 628 deviceDegree = 90 - Number(sc); 629 deviceDegree = deviceDegree >= 0 ? deviceDegree% 360 : deviceDegree% 360 + 360; 630 } 631 resolve(deviceDegree); 632 }); 633 } catch (error) { 634 let err = error as BusinessError; 635 console.error('Failed to register gravity sensor: ' + JSON.stringify(err)); 636 resolve(-1); // 异常时返回默认值 637 } 638 }); 639} 640``` 641