目录

Dynamically Adjusting the Preview Frame Rate (ArkTS)

Dynamic frame rate adjustment is an important capability for managing the preview effect in live streaming and video applications. This capability allows applications to explicitly control the output frame rate to meet various service requirements at different frame rates.

In certain scenarios, reducing the frame rate can also help in conserving power when the camera is in use.

Constraints

The supported frame rate range and the frame rate setting are subject to the hardware's capabilities. Different hardware platforms may offer different default frame rates.

Development Process

Before using the preview functionality, create a camera session. After the session configuration is complete, the application must commit the configuration and start the session before using the camera functionalities.

The procedure is shown below.

Pay attention to the differences (labeled with numbers in the figure above) between the dynamic adjustment of the preview frame rate and the standard preview process.

  1. When calling createSession to create a session, set the mode to NORMAL_PHOTO or NORMAL_VIDEO.

    The frame rate of the preview stream can be adjusted only when the session is in NORMAL_PHOTO or NORMAL_VIDEO mode. For details about the operation, see Creating a Session and Specifying a Mode.

  2. The operation of dynamically adjusting the frame rate can be performed before or after preview is enabled.

  3. Dynamic frame rate adjustment is optional during preview. It involves the following operations:

    • Query the supported frame rate range.
    • Set a frame rate.
    • Obtain the active frame rate.

For details about how to configure sessions and release resources, see Session Management and Preview, or the sample code provided in Complete Process.

Creating a Session and Specifying a Mode

Before using preview and other functionalities, call createSession of CameraManager to create a camera session.

When creating the session, SceneMode must be set to NORMAL_PHOTO or NORMAL_VIDEO. The created session is in photo capture or video recording mode.

The following creates a session in NORMAL_PHOTO mode.

function createPhotoSession(cameraManager: camera.CameraManager): camera.Session | undefined {
  let session: camera.Session | undefined = undefined;
  try {
    // Create a session and set the session mode to NORMAL_PHOTO.
    session = cameraManager.createSession(camera.SceneMode.NORMAL_PHOTO) as camera.PhotoSession;
  } catch (error) {
    let err = error as BusinessError;
    console.error(`Failed to create the session instance. error: ${JSON.stringify(err)}`);
  }
  return session;
}

Adjusting the Frame Rate

  1. Call getSupportedFrameRates of PreviewOutput to query the supported frame rate range.

    This operation must be performed after the session calls commitConfig to complete stream configuration.

    function getSupportedFrameRange(previewOutput: camera.PreviewOutput): Array<camera.FrameRateRange> {
// Obtain the supported frame rate range, which varies according to different hardware platforms.
  return previewOutput.getSupportedFrameRates();
}

  2. Call setFrameRate in the PreviewOutput class to dynamically adjust the frame rate.

    • This operation must be performed after the session calls commitConfig to complete stream configuration.

    • It can be called at any time before or after the session calls start to start preview.

    function setFrameRate(previewOutput: camera.PreviewOutput, minFps: number, maxFps: number): void {
  try {
    previewOutput.setFrameRate(minFps, maxFps);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`Failed to setFrameRate for previewOutput. error: ${JSON.stringify(err)}`);
  }
}

  3. (Optional) Call getActiveFrameRate in the PreviewOutput class to query the frame rate that has been set and taken effect.

    The active frame rate can be obtained only when it is explicitly set by calling setFrameRate.

    function getActiveFrameRange(previewOutput: camera.PreviewOutput): camera.FrameRateRange {
  return previewOutput.getActiveFrameRate();
}

Complete Process

Based on the preceding development process, the sample code for configuring the session and adjusting the frame rate of the preview output before and after session.start is as follows:

import { camera } from '@kit.CameraKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function sessionConfig(cameraManager: camera.CameraManager, cameraInput: camera.CameraInput,
  previewOutput: camera.PreviewOutput): Promise<void> {
  try {
    let session: camera.Session | undefined = undefined;
    // Create a CaptureSession instance.
    session = createPhotoSession(cameraManager);
    if (session === undefined) {
      return;
    }
    // Start configuration for the session.
    session.beginConfig();
    // Add the CameraInput object to the session.
    session.addInput(cameraInput);
    // Add the previewOutput object to the session.
    session.addOutput(previewOutput);
    // Commit the configuration.
    await session.commitConfig();
    // Obtain the supported frame rate range.
    let supportFrameRateArray: Array<camera.FrameRateRange> = getSupportedFrameRange(previewOutput);

    console.info(`frame rate supported by previewOutput: ${JSON.stringify(supportFrameRateArray)}`);
    // Set the frame rate before calling session.start.
    if (supportFrameRateArray.length !== 0) {
      // Set the frame rate to the maximum value in the first group of frame rates.
      setFrameRate(previewOutput, supportFrameRateArray[0].max, supportFrameRateArray[0].max);
    }
    // Obtain the active frame rate.
    let activeFrameRateArray: camera.FrameRateRange = getActiveFrameRange(previewOutput);
    console.info(`current effective frame rate for this previewOutput: ${JSON.stringify(activeFrameRateArray)}`);
    // Start the session and preview.
    await session.start();
    // Set the frame rate after calling session.start.
    if (supportFrameRateArray.length !== 0) {
      // Set the frame rate to half of the maximum value. (The setting result depends on whether the platform supports this value.)
      setFrameRate(previewOutput, supportFrameRateArray[0].max / 2, supportFrameRateArray[0].max / 2);
    }
    // Obtain the active frame rate.
    activeFrameRateArray = getActiveFrameRange(previewOutput);
    console.info(`current effective frame rate for this previewOutput: ${JSON.stringify(activeFrameRateArray)}`);
  } catch (error) {
    let err = error as BusinessError;
    console.info(`sessionConfig fail : ${JSON.stringify(err)}`);
  }
}