diff --git a/en/application-dev/reference/apis/js-apis-audio.md b/en/application-dev/reference/apis/js-apis-audio.md index 0b31d38d305281fec2aa327959de91e1833e409f..715b9dbe20f1b39bd0f5ce1cf5c9dd68dd2831ae 100644 --- a/en/application-dev/reference/apis/js-apis-audio.md +++ b/en/application-dev/reference/apis/js-apis-audio.md @@ -1,10 +1,6 @@ # Audio Management -> **NOTE** -> -> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> -> API version 9 is a canary release for trial use. The APIs of this version may be unstable. +The **Audio** module provides basic audio management capabilities, including audio volume and audio device management, and audio data collection and rendering. This module provides the following common audio-related functions: @@ -12,6 +8,12 @@ This module provides the following common audio-related functions: - [AudioRenderer](#audiorenderer8): audio rendering, used to play Pulse Code Modulation (PCM) audio data. - [AudioCapturer](#audiocapturer8): audio capture, used to record PCM audio data. +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> API version 9 is a canary release for trial use. The APIs of this version may be unstable. + ## Modules to Import ``` @@ -545,7 +547,7 @@ Describes the callback invoked for audio interruption or focus gain events. | ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | | actionType | [InterruptActionType](#interruptactiontype) | Yes | Returned event type. The value **TYPE_ACTIVATED** means the focus gain event, and **TYPE_INTERRUPT** means the audio interruption event.| | type | [InterruptType](#interrupttype) | No | Type of the audio interruption event. | -| hint | [InterruptHint](#interrupthint) | No | Hint provided along with the audio interruption event. | +| hint | [InterruptHint](#interrupthint) | No | Hint provided along with the audio interruption event. | | activated | boolean | No | Whether the focus is gained or released. The value **true** means that the focus is gained or released, and **false** means that the focus fails to be gained or released.| ## VolumeEvent8+ @@ -570,8 +572,8 @@ Describes the device connection status and device information. | Name | Type | Mandatory| Description | | :---------------- | :------------------------------------------------ | :--- | :----------------- | -| type | [DeviceChangeType](#DeviceChangeType) | Yes | Device connection status.| -| deviceDescriptors | [AudioDeviceDescriptors](#AudioDeviceDescriptors) | Yes | Device information. | +| type | [DeviceChangeType](#devicechangetype) | Yes | Device connection status.| +| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information. | ## DeviceChangeType @@ -641,6 +643,8 @@ setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback&l Sets the volume for a stream. This API uses an asynchronous callback to return the result. +**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY + **System capability**: SystemCapability.Multimedia.Audio.Volume **Parameters** @@ -669,6 +673,8 @@ setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> Sets the volume for a stream. This API uses a promise to return the result. +**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY + **System capability**: SystemCapability.Multimedia.Audio.Volume **Parameters** @@ -1033,6 +1039,8 @@ setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void Sets the ringer mode. This API uses an asynchronous callback to return the result. +**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY + **System capability**: SystemCapability.Multimedia.Audio.Communication **Parameters** @@ -1060,6 +1068,8 @@ setRingerMode(mode: AudioRingMode): Promise<void> Sets the ringer mode. This API uses a promise to return the result. +**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY + **System capability**: SystemCapability.Multimedia.Audio.Communication **Parameters** @@ -1140,6 +1150,8 @@ Sets an audio parameter. This API uses an asynchronous callback to return the re This API is used to extend the audio configuration based on the hardware capability. The supported audio parameters vary according to the device and can be obtained from the device manual. The example below is for reference only. +**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS + **System capability**: SystemCapability.Multimedia.Audio.Core **Parameters** @@ -1170,6 +1182,8 @@ Sets an audio parameter. This API uses a promise to return the result. This API is used to extend the audio configuration based on the hardware capability. The supported audio parameters vary according to the device and can be obtained from the device manual. The example below is for reference only. +**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS + **System capability**: SystemCapability.Multimedia.Audio.Core **Parameters** @@ -1426,6 +1440,8 @@ setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. +**Required permissions**: ohos.permission.MICROPHONE + **System capability**: SystemCapability.Multimedia.Audio.Device **Parameters** @@ -1453,6 +1469,8 @@ setMicrophoneMute(mute: boolean): Promise<void> Mutes or unmutes the microphone. This API uses a promise to return the result. +**Required permissions:** ohos.permission.MICROPHONE + **System capability**: SystemCapability.Multimedia.Audio.Device **Parameters** @@ -1481,6 +1499,8 @@ isMicrophoneMute(callback: AsyncCallback<boolean>): void Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. +**Required permissions**: ohos.permission.MICROPHONE + **System capability**: SystemCapability.Multimedia.Audio.Device **Parameters** @@ -1507,6 +1527,8 @@ isMicrophoneMute(): Promise<boolean> Checks whether the microphone is muted. This API uses a promise to return the result. +**Required permissions**: ohos.permission.MICROPHONE + **System capability**: SystemCapability.Multimedia.Audio.Device **Return value** @@ -1538,7 +1560,7 @@ This is a system API and cannot be called by third-party applications. | Name | Type | Mandatory| Description | | -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of event to subscribe to. The value **volumeChange** means the system volume change event, which is triggered when a system volume change is detected.| +| type | string | Yes | Event type. The value **volumeChange** means the system volume change event, which is triggered when a system volume change is detected.| | callback | Callback<[VolumeEvent](#volumeevent8)> | Yes | Callback used to return the system volume change event. | **Example** @@ -1565,7 +1587,7 @@ This is a system API and cannot be called by third-party applications. | Name | Type | Mandatory| Description | | -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of event to subscribe to. The value **ringerModeChange** means the ringer mode change event, which is triggered when a ringer mode change is detected.| +| type | string | Yes | Event type. The value **ringerModeChange** means the ringer mode change event, which is triggered when a ringer mode change is detected.| | callback | Callback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the updated ringer mode. | **Example** @@ -1588,7 +1610,7 @@ Subscribes to device change events. When a device is connected or disconnected, | Name | Type | Mandatory| Description | | :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | -| type | string | Yes | Type of event to subscribe to. The value **deviceChange** means the device change event, which is triggered when a device connection status change is detected.| +| type | string | Yes | Event type. The value **deviceChange** means the device change event, which is triggered when a device connection status change is detected.| | callback | Callback<[DeviceChangeAction](#DeviceChangeAction)\> | Yes | Callback used to return the device update details. | **Example** @@ -1614,7 +1636,7 @@ Unsubscribes from device change events. | Name | Type | Mandatory| Description | | -------- | --------------------------------------------------- | ---- | ------------------------------------------ | -| type | string | Yes | Type of event to unsubscribe from. The value **deviceChange** means the device change event, which is triggered when a device connection status change is detected.| +| type | string | Yes | Event type. The value **deviceChange** means the device change event, which is triggered when a device connection status change is detected.| | callback | Callback<[DeviceChangeAction](#DeviceChangeAction)> | No | Callback used to return the device update details. | **Example** @@ -1637,7 +1659,7 @@ Subscribes to audio interruption events. When the application's audio is interru | Name | Type | Mandatory| Description | | --------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of event to subscribe to. The value **interrupt** means the audio interruption event, which is triggered when the audio playback of the current application is interrupted by another application.| +| type | string | Yes | Event type. The value **interrupt** means the audio interruption event, which is triggered when the audio playback of the current application is interrupted by another application.| | interrupt | AudioInterrupt | Yes | Audio interruption event type. | | callback | Callback<[InterruptAction](#interruptaction)> | Yes | Callback invoked for the audio interruption event. | @@ -1673,7 +1695,7 @@ Unsubscribes from audio interruption events. | Name | Type | Mandatory| Description | | --------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of event to unsubscribe from. The value **interrupt** means the audio interruption event, which is triggered when the audio playback of the current application is interrupted by another application.| +| type | string | Yes | Event type. The value **interrupt** means the audio interruption event, which is triggered when the audio playback of the current application is interrupted by another application.| | interrupt | AudioInterrupt | Yes | Audio interruption event type. | | callback | Callback<[InterruptAction](#interruptaction)> | No | Callback invoked for the audio interruption event. | @@ -2501,7 +2523,7 @@ Subscribes to audio interruption events. This API uses a callback to get interru | Name | Type | Mandatory| Description | | -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of event to subscribe to. The value **interrupt** means the audio interruption event, which is triggered when audio playback is interrupted.| +| type | string | Yes | Event type. The value **interrupt** means the audio interruption event, which is triggered when audio playback is interrupted.| | callback | Callback<[InterruptEvent](#interruptevent9)> | Yes | Callback used to return the audio interruption event. | **Example** @@ -2567,7 +2589,7 @@ Subscribes to mark reached events. When the number of frames rendered reaches th | Name | Type | Mandatory| Description | | :------- | :----------------------- | :--- | :---------------------------------------- | -| type | string | Yes | Type of event to subscribe to. The value **markReach** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter.| +| type | string | Yes | Event type. The value **markReach** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter.| | frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | | callback | (position: number) => {} | Yes | Callback invoked when the event is triggered. | @@ -2594,7 +2616,7 @@ Unsubscribes from mark reached events. | Name| Type | Mandatory| Description | | :----- | :----- | :--- | :------------------------------------------------ | -| type | string | Yes | Type of event to unsubscribe from. The value is fixed at **markReach**.| +| type | string | Yes | Event type. The value is fixed at **markReach**.| **Example** @@ -2614,7 +2636,7 @@ Subscribes to period reached events. When the period of frame rendering reaches | Name | Type | Mandatory| Description | | :------- | :----------------------- | :--- | :------------------------------------------ | -| type | string | Yes | Type of event to subscribe to. The value **periodReach** means the period reached event, which is triggered when the period of frame rendering reaches the value of the **frame** parameter.| +| type | string | Yes | Event type. The value **periodReach** means the period reached event, which is triggered when the period of frame rendering reaches the value of the **frame** parameter.| | frame | number | Yes | Period during which frame rendering is listened. The value must be greater than **0**. | | callback | (position: number) => {} | Yes | Callback invoked when the event is triggered. | @@ -2640,7 +2662,7 @@ Unsubscribes from period reached events. | Name| Type | Mandatory| Description | | :----- | :----- | :--- | :-------------------------------------------------- | -| type | string | Yes | Type of event to unsubscribe from. The value is fixed at **periodReach**.| +| type | string | Yes | Event type. The value is fixed at **periodReach**.| **Example** @@ -2660,7 +2682,7 @@ Subscribes to state change events. | Name | Type | Mandatory| Description | | :------- | :------------------------- | :--- | :------------------------------------------ | -| type | string | Yes | Type of event to subscribe to. The value **stateChange** means the state change event.| +| type | string | Yes | Event type. The value **stateChange** means the state change event.| | callback | [AudioState](#audiostate8) | Yes | Callback used to return the state change. | **Example** @@ -2686,7 +2708,7 @@ Provides APIs for audio capture. Before calling any API in **AudioCapturer**, yo | Name | Type | Readable| Writable| Description | | :---- | :------------------------- | :--- | :--- | :--------------- | -| state8+ | [AudioState](#audiostate8) | Yes | No | Audio capturer state.| +| state8+ | [AudioState](#audiostate8) | Yes| No | Audio capturer state.| **Example** @@ -3165,7 +3187,7 @@ Subscribes to mark reached events. When the number of frames captured reaches th | Name | Type | Mandatory| Description | | :------- | :---------------------- | :--- | :----------------------------------------- | -| type | string | Yes | Type of event to subscribe to. The value **markReach** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter. | +| type | string | Yes | Event type. The value **markReach** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter. | | frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | | callback | position: number) => {} | Yes | Callback invoked when the event is triggered.| @@ -3191,7 +3213,7 @@ Unsubscribes from mark reached events. | Name| Type | Mandatory| Description | | :----- | :----- | :--- | :-------------------------------------------- | -| type | string | Yes | Type of event to unsubscribe from. The value **markReach** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter.| +| type | string | Yes | Event type. The value **markReach** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter.| **Example** @@ -3211,7 +3233,7 @@ Subscribes to mark reached events. When the period of frame capturing reaches th | Name | Type | Mandatory| Description | | :------- | :----------------------- | :--- | :------------------------------------------ | -| type | string | Yes | Type of event to subscribe to. The value **periodReach** means the period reached event, which is triggered when the period of frame capturing reaches the value of the **frame** parameter.| +| type | string | Yes | Event type. The value **periodReach** means the period reached event, which is triggered when the period of frame capturing reaches the value of the **frame** parameter.| | frame | number | Yes | Period during which frame capturing is listened. The value must be greater than **0**. | | callback | (position: number) => {} | Yes | Callback invoked when the event is triggered. | @@ -3237,7 +3259,7 @@ Unsubscribes from period reached events. | Name| Type | Mandatory| Description | | :----- | :----- | :--- | :---------------------------------------------- | -| type | string | Yes | Type of event to unsubscribe from. The value **periodReach** means the period reached event, which is triggered when the period of frame capturing reaches the value of the **frame** parameter.| +| type | string | Yes | Event type. The value **periodReach** means the period reached event, which is triggered when the period of frame capturing reaches the value of the **frame** parameter.| **Example** @@ -3257,7 +3279,7 @@ Subscribes to state change events. | Name | Type | Mandatory| Description | | :------- | :------------------------- | :--- | :------------------------------------------ | -| type | string | Yes | Type of event to subscribe to. The value **stateChange** means the state change event.| +| type | string | Yes | Event type. The value **stateChange** means the state change event.| | callback | [AudioState](#audiostate8) | Yes | Callback used to return the state change. | **Example**