目录

Volume Management

This module provides capabilities for managing playback volume, covering system volume, application volume, and audio stream volume.

The system volume is managed globally by HarmonyOS and applies to all applications and devices. HarmonyOS categorizes audio into various stream types, each with its own independent system volume control.

The system volume can be adjusted using physical volume buttons or through the system settings screen. On the system settings screen, users can individually adjust the volume levels for each type of system volume.

The following lists the common stream types and their corresponding system volumes.

The application volume is a type of volume control provided by HarmonyOS for third-party applications to manage the volume of all audio streams within that application. Once set, all audio streams initiated by the application will use this volume level by default. In addition, applications with the system application permission can adjust the volume of specific applications by using their UIDs.

The audio stream volume is a volume setting controlled independently by an application and affects only the output volume of the specified audio stream within that application. For example, a media player can control its playback volume independently without affecting the system volume or other types of stream volumes within the application.

The following describes the relationship between the system volume, application volume, and audio stream volume.

HarmonyOS achieves precise volume control for applications through the coordinated use of the system volume, app volume, and audio stream volume.

The following examples are code snippets. You can get the complete sample via the link at the bottom right of the sample code.

System Volume

The API for managing the system volume is provided by AudioVolumeManager. Before using this API, you must call getVolumeManager to obtain an AudioVolumeManager instance.

Currently, AudioVolumeManager can be used to obtain volume information and listen for volume changes. It cannot be used to adjust the system volume. If you want to adjust the system volume, follow the instructions provided in Adjusting the System Volume Using the Volume Panel.

import { audio } from '@kit.AudioKit';
// ...

let audioManager = audio.getAudioManager();
let audioVolumeManager = audioManager.getVolumeManager();

[h2]Obtaining Volume Information

Call AudioVolumeManager to obtain the volume of a specified audio stream.

The example code is as follows:

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
// ...

  try {
    // Obtain the volume of the specified audio stream.
    let volume = audioVolumeManager.getVolumeByStream(audio.StreamUsage.STREAM_USAGE_MUSIC);
    console.info(`Succeeded in getting volume by stream. Volume: ${volume}`);
    // ...
  } catch (err) {
    let error = err as BusinessError;
    console.error(`Failed to get volume by stream. Code: ${error.code}, message: ${error.message}`);
    // ...
  }
  // ...

  try {
    // Obtain the minimum volume of the specified audio stream.
    let volume = audioVolumeManager.getMinVolumeByStream(audio.StreamUsage.STREAM_USAGE_MUSIC);
    console.info(`Succeeded in getting min volume by stream. Volume: ${volume}`);
    // ...
  } catch (err) {
    let error = err as BusinessError;
    console.error(`Failed to get min volume by stream. Code: ${error.code}, message: ${error.message}`);
    // ...
  }
  // ...

  try {
    // Obtain the maximum volume of the specified audio stream.
    let volume = audioVolumeManager.getMaxVolumeByStream(audio.StreamUsage.STREAM_USAGE_MUSIC);
    console.info(`Succeeded in getting max volume by stream. Volume: ${volume}`);
    // ...
  } catch (err) {
    let error = err as BusinessError;
    console.error(`Failed to get max volume by stream. Code: ${error.code}, message: ${error.message}`);
    // ...
  }

[h2]Listening for System Volume Changes

You can set an event to listen for system volume changes.

The system volumes of different output devices are independent of each other. When the output device of an audio stream changes, the system volume of that stream type on the current device may differ from that on the original device. You can listen for changes in the highest-priority output device, and after the device changes, re-query the volume value through the system volume query API getVolumeByStream to update the volume state maintained on the application side.

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
// ...

  try {
    audioVolumeManager.on('streamVolumeChange', audio.StreamUsage.STREAM_USAGE_MUSIC, (streamVolumeEvent: audio.StreamVolumeEvent) => {
      console.info(`Succeeded in using on function. StreamVolumeEvent: ${JSON.stringify(streamVolumeEvent)}`);
      // ...
    });
  } catch (err) {
    let error = err as BusinessError;
    console.error(`Failed to use on function. Code: ${error.code}, message: ${error.message}`);
    // ...
  }

[h2]Adjusting the System Volume Using the Volume Panel

An application cannot directly adjust the system volume. However, it can invoke the system volume panel for users to adjust the volume. When the user adjusts the volume, a volume prompt UI is displayed to explicitly notify the user that the system volume changes.

The system provides the ArkTS component AVVolumePanel (volume panel), which applications can create. For details and examples, see avVolumePanel.

Application Volume

The API for managing the application volume is provided by AudioVolumeManager. Before using this API, you must call getVolumeManager to obtain an AudioVolumeManager instance.

When volume mode is set to APP_INDIVIDUAL, you can set and query the application volume by calling the APIs in the following sample.

[h2]Adjusting the Application Volume

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
// ...

let audioManager = audio.getAudioManager();
let audioVolumeManager = audioManager.getVolumeManager();

let appVolumeChangeCallback = (volumeEvent: audio.VolumeEvent) => {
  console.info(`Succeeded in using on function. VolumeEvent: ${JSON.stringify(volumeEvent)}`);
  // ...
};
// ...

  try {
    // Listen for app volume changes.
    audioVolumeManager.on('appVolumeChange', appVolumeChangeCallback);
  } catch (err) {
    let error = err as BusinessError;
    console.error(`Failed to use on function. Code: ${error.code}, message: ${error.message}`);
    // ...
  }
  // ...

  // Set the volume (ranging from 0 to 100) for the application.
  audioVolumeManager.setAppVolumePercentage(20).then(() => {
    console.info('Succeeded in setting app volume percentage.');
    // ...
  }).catch((err: BusinessError) => {
    console.error(`Failed to set app volume percentage. Code: ${err.code}, message: ${err.message}`);
    // ...
  });
  // ...

  // Query the application volume.
  audioVolumeManager.getAppVolumePercentage().then((volume: number) => {
    console.info(`Succeeded in getting app volume percentage. Volume: ${volume}`);
    // ...
  }).catch((err: BusinessError) => {
    console.error(`Failed to get app volume percentage. Code: ${err.code}, message: ${err.message}`);
    // ...
  });

Audio Stream Volume

You can use setVolume of AVPlayer or setVolume of AudioRenderer to set the audio stream volume.

Call setVolume and getVolume of AudioRenderer to set and obtain the volume of the audio stream, respectively.

The example code is as follows:

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
// ...

    // Set the audio stream volume. The volume ranges from 0.0 to 1.0.
    audioRenderer.setVolume(0.1).then(() => {
      console.info('Succeeded in setting volume.');
      // ...
    }).catch((err: BusinessError) => {
      console.error(`Failed to set volume. Code: ${err.code}, message: ${err.message}`);
      // ...
    });
    // ...

    try {
      // Obtain the audio stream volume.
      let volume: number = audioRenderer.getVolume();
      console.info(`Succeeded in getting volume. Volume: ${volume}`);
      // ...
    } catch (err) {
      let error = err as BusinessError;
      console.error(`Failed to get volume. Code: ${error.code}, message: ${error.message}`);
      // ...
    }