diff --git a/en/application-dev/reference/apis/js-apis-audio.md b/en/application-dev/reference/apis/js-apis-audio.md index e03b03206e91eac28dab5d3efa8cf5feb3b95918..2c58a89c09ebdefba443d01d3e3f60dc88077364 100644 --- a/en/application-dev/reference/apis/js-apis-audio.md +++ b/en/application-dev/reference/apis/js-apis-audio.md @@ -1,13 +1,13 @@ # 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. +> **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. This module provides the following common audio-related functions: -- [AudioManager](#audiomanager): Audio management. -- [AudioRenderer](#audiorenderer8): Audio rendering, used to play Pulse Code Modulation (PCM) audio data. -- [AudioCapturer](#audiocapturer8): Audio capture, used to record PCM audio data. +- [AudioManager](#audiomanager): audio management. +- [AudioRenderer](#audiorenderer8): audio rendering, used to play Pulse Code Modulation (PCM) audio data. +- [AudioCapturer](#audiocapturer8): audio capture, used to record PCM audio data. ## Modules to Import @@ -15,22 +15,21 @@ This module provides the following common audio-related functions: import audio from '@ohos.multimedia.audio'; ``` + ## audio.getAudioManager getAudioManager(): AudioManager Obtains an **AudioManager** instance. -**System capability:** SystemCapability.Multimedia.Audio.Core - -**Return value:** +**System capability**: SystemCapability.Multimedia.Audio.Core -| Type | Description | -| ----------------------------- | -------------------- | -| [AudioManager](#audiomanager) | AudioManager object. | - -**Example:** +**Return value** +| Type | Description | +| ----------------------------- | ------------ | +| [AudioManager](#audiomanager) | **AudioManager** instance.| +**Example** ``` var audioManager = audio.getAudioManager(); ``` @@ -39,17 +38,18 @@ var audioManager = audio.getAudioManager(); createAudioRenderer(options: AudioRendererOptions, callback: AsyncCallback\): void -Obtains an **AudioRenderer** instance. This API uses an asynchronous callback to return the renderer instance. +Obtains an **AudioRenderer** instance. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**Parameters** -**Parameters:** -| Name | Type | Mandatory | Description | -| :--------- | :---------------------------------------------- | :-------- | :--------------------------------------------------- | -| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations. | -| callback | AsyncCallback<[AudioRenderer](#audiorenderer8)> | Yes | Callback used to return the audio renderer instance. | +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------- | ---- | ---------------- | +| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations. | +| callback | AsyncCallback<[AudioRenderer](#audiorenderer8)> | Yes | Callback used to return the **AudioRenderer** instance.| -**Example:** +**Example** ``` import audio from '@ohos.multimedia.audio'; @@ -81,26 +81,28 @@ audio.createAudioRenderer(audioRendererOptions,(err, data) => { } }); ``` + ## audio.createAudioRenderer8+ -createAudioRenderer(options: AudioRendererOptions): Promise +createAudioRenderer(options: AudioRendererOptions): Promise + +Obtains an **AudioRenderer** instance. This API uses a promise to return the result. -Obtains an **AudioRenderer** instance. This API uses a promise to return the renderer instance. +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**Parameters** -**Parameters:** -| Name | Type | Mandatory | Description | -| :--------- | :--------------------------------------------- | :-------- | :---------------------------| -| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations. | +| Name | Type | Mandatory| Description | +| :------ | :--------------------------------------------- | :--- | :----------- | +| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations.| -**Return value:** +**Return value** -| Type | Description | -| ----------------------------------------- | --------------------------------------------------- | -| Promise<[AudioRenderer](#audiorenderer8)> | Promise used to return the audio renderer instance. | +| Type | Description | +| ----------------------------------------- | ---------------- | +| Promise<[AudioRenderer](#audiorenderer8)> | Promise used to return the **AudioRenderer** instance.| -**Example:** +**Example** ``` import audio from '@ohos.multimedia.audio'; @@ -136,17 +138,18 @@ audio.createAudioRenderer(audioRendererOptions).then((data) => { createAudioCapturer(options: AudioCapturerOptions, callback: AsyncCallback): void -Obtains an **AudioCapturer** instance. This API uses an asynchronous callback to return the capturer instance. +Obtains an **AudioCapturer** instance. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** -| Name | Type | Mandatory | Description | -| :--------- | :---------------------------------------------- | :-------- | :--------------------------------------------------- | -| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations. | -| callback | AsyncCallback<[AudioCapturer](#audiocapturer8)> | Yes | Callback used to return the audio capturer instance. | +**Parameters** -**Example:** +| Name | Type | Mandatory| Description | +| :------- | :---------------------------------------------- | :--- | :--------------- | +| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| +| callback | AsyncCallback<[AudioCapturer](#audiocapturer8)> | Yes | Callback used to return the **AudioCapturer** instance.| + +**Example** ``` import audio from '@ohos.multimedia.audio'; @@ -182,22 +185,23 @@ audio.createAudioCapturer(audioCapturerOptions,(err, data) => { createAudioCapturer(options: AudioCapturerOptions): Promise -Obtains an **AudioCapturer** instance. This API uses a promise to return the capturer instance. +Obtains an **AudioCapturer** instance. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**Parameters** -**Parameters:** -| Name | Type | Mandatory | Description | -| :--------- | :-------------------------------------------- | :-------- | :-------------------------- | -| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations. | +| Name | Type | Mandatory| Description | +| :------ | :--------------------------------------------- | :--- | :--------------- | +| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| -**Return value:** +**Return value** -| Type | Description | -| ----------------------------------------- | --------------------------------------------------- | -| Promise<[AudioCapturer](#audiocapturer8)> | Promise used to return the audio capturer instance. | +| Type | Description | +| ----------------------------------------- | -------------- | +| Promise<[AudioCapturer](#audiocapturer8)> | Promise used to return the **AudioCapturer** instance.| -**Example:** +**Example** ``` import audio from '@ohos.multimedia.audio'; @@ -230,432 +234,421 @@ audio.createAudioRenderer(audioCapturerOptions).then((data) => { ## AudioVolumeType -Enumerates audio stream types. +Enumerates the audio stream types. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume + +| Name | Default Value| Description | +| ---------------------------- | ------ | ---------- | +| VOICE_CALL8+ | 0 | Audio stream for voice calls.| +| RINGTONE | 2 | Audio stream for ringtones. | +| MEDIA | 3 | Audio stream for media purpose. | +| VOICE_ASSISTANT8+ | 9 | Audio stream for voice assistant.| -| Name | Default Value | Description | -| ---------------------------- | -------------- | --------------------------------- | -| VOICE_CALL8+ | 0 | Audio stream for voice calls. | -| RINGTONE | 2 | Audio stream for ringtones. | -| MEDIA | 3 | Audio stream for media purpose. | -| VOICE_ASSISTANT8+ | 9 | Audio stream for voice assistant. | ## DeviceFlag -Enumerates audio device flags. +Enumerates the audio device flags. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -| Name | Default Value | Description | -| ------------------- | ------------- | -------------- | -| OUTPUT_DEVICES_FLAG | 1 | Output device. | -| INPUT_DEVICES_FLAG | 2 | Input device. | -| ALL_DEVICES_FLAG | 3 | All devices. | +| Name | Default Value| Description | +| ------------------- | ------ | ---------- | +| OUTPUT_DEVICES_FLAG | 1 | Output device.| +| INPUT_DEVICES_FLAG | 2 | Input device.| +| ALL_DEVICES_FLAG | 3 | All devices.| ## DeviceRole -Enumerates audio device roles. +Enumerates the audio device roles. + +**System capability**: SystemCapability.Multimedia.Audio.Device -**System capability:** SystemCapability.Multimedia.Audio.Device +| Name | Default Value| Description | +| ------------- | ------ | -------------- | +| INPUT_DEVICE | 1 | Input role.| +| OUTPUT_DEVICE | 2 | Output role.| -| Name | Default Value | Description | -| ------------- | ------------- | ------------ | -| INPUT_DEVICE | 1 | Input role. | -| OUTPUT_DEVICE | 2 | Output role. | ## DeviceType -Enumerates audio device types. +Enumerates the audio device types. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -| Name | Default Value | Description | -| ---------------- | ------------- | ------------------------------------------------------------------------ | -| INVALID | 0 | Invalid device. | -| EARPIECE | 1 | Earpiece. | -| SPEAKER | 2 | Speaker. | -| WIRED_HEADSET | 3 | Wired headset. | -| WIRED_HEADPHONES | 4 | Wired headset without microphone. | -| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links. | -| BLUETOOTH_A2DP | 8 | Bluetooth device using Advanced Audio Distribution Profile (A2DP) links. | -| MIC | 15 | Microphone. | -| USB_HEADSET | 22 | USB Type-C headset. | +| Name | Default Value| Description | +| ---------------- | ------ | --------------------------------------------------------- | +| INVALID | 0 | Invalid device. | +| EARPIECE | 1 | Earpiece. | +| SPEAKER | 2 | Speaker. | +| WIRED_HEADSET | 3 | Wired headset with a microphone. | +| WIRED_HEADPHONES | 4 | Wired headset without microphone. | +| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links. | +| BLUETOOTH_A2DP | 8 | Bluetooth device using Advanced Audio Distribution Profile (A2DP) links.| +| MIC | 15 | Microphone. | +| USB_HEADSET | 22 | USB Type-C headset. | ## ActiveDeviceType Enumerates the active device types. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -| Name | Default Value | Description | -| ------------- | ------------- | ---------------------------------------------------------------------- | -| SPEAKER | 2 | Speaker. | -| BLUETOOTH_SCO | 7 | Bluetooth device using the SCO links. | +| Name | Default Value| Description | +| ------------- | ------ | ---------------------------------------------------- | +| SPEAKER | 2 | Speaker. | +| BLUETOOTH_SCO | 7 | Bluetooth device using the SCO links.| ## AudioRingMode -Enumerates ringer modes. +Enumerates the ringer modes. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -| Name | Default Value | Description | -| ------------------- | ------------- | ---------------- | -| RINGER_MODE_SILENT | 0 | Silent mode. | -| RINGER_MODE_VIBRATE | 1 | Vibration mode. | -| RINGER_MODE_NORMAL | 2 | Normal mode. | +| Name | Default Value| Description | +| ------------------- | ------ | ---------- | +| RINGER_MODE_SILENT | 0 | Silent mode.| +| RINGER_MODE_VIBRATE | 1 | Vibration mode.| +| RINGER_MODE_NORMAL | 2 | Normal mode.| ## AudioSampleFormat8+ -Enumerates the audio sample formats. +Enumerate the audio sample formats. -**System capability:** SystemCapability.Multimedia.Audio.Core +**System capability**: SystemCapability.Multimedia.Audio.Core -| Name | Default Value | Description | -| :-------------------- | :------------ | :------------------------------------ | -| SAMPLE_FORMAT_INVALID | -1 | Invalid format. | -| SAMPLE_FORMAT_U8 | 0 | Unsigned 8 bit integer. | -| SAMPLE_FORMAT_S16LE | 1 | Signed 16 bit integer, little endian. | -| SAMPLE_FORMAT_S24LE | 2 | Signed 24 bit integer, little endian. | -| SAMPLE_FORMAT_S32LE | 3 | Signed 32 bit integer, little endian. | +| Name | Default Value| Description | +| --------------------- | ------ | -------------------------- | +| SAMPLE_FORMAT_INVALID | -1 | Invalid format. | +| SAMPLE_FORMAT_U8 | 0 | Unsigned 8-bit integer. | +| SAMPLE_FORMAT_S16LE | 1 | Signed 16-bit integer, little endian.| +| SAMPLE_FORMAT_S24LE | 2 | Signed 24-bit integer, little endian.| +| SAMPLE_FORMAT_S32LE | 3 | Signed 32-bit integer, little endian.| ## AudioChannel8+ Enumerates the audio channels. -**System capability:** SystemCapability.Multimedia.Audio.Core +**System capability**: SystemCapability.Multimedia.Audio.Core -| Name | Default Value | Description | -| :-------- | :------------ | :--------------- | -| CHANNEL_1 | 0x1 << 0 | Channel count 1. | -| CHANNEL_2 | 0x1 << 1 | Channel count 2. | +| Name | Default Value | Description | +| --------- | -------- | -------- | +| CHANNEL_1 | 0x1 << 0 | Mono.| +| CHANNEL_2 | 0x1 << 1 | Dual-channel.| ## AudioSamplingRate8+ Enumerates the audio sampling rates. -**System capability:** SystemCapability.Multimedia.Audio.Core - -| Name | Default Value | Description | -| :---------------- | :------------ | :------------------- | -| SAMPLE_RATE_8000 | 8000 | Sampling rate 8000. | -| SAMPLE_RATE_11025 | 11025 | Sampling rate 11025. | -| SAMPLE_RATE_12000 | 12000 | Sampling rate 12000. | -| SAMPLE_RATE_16000 | 16000 | Sampling rate 16000. | -| SAMPLE_RATE_22050 | 22050 | Sampling rate 22050. | -| SAMPLE_RATE_24000 | 24000 | Sampling rate 24000. | -| SAMPLE_RATE_32000 | 32000 | Sampling rate 32000. | -| SAMPLE_RATE_44100 | 44100 | Sampling rate 44100. | -| SAMPLE_RATE_48000 | 48000 | Sampling rate 48000. | -| SAMPLE_RATE_64000 | 64000 | Sampling rate 64000. | -| SAMPLE_RATE_96000 | 96000 | Sampling rate 96000. | - +**System capability**: SystemCapability.Multimedia.Audio.Core + +| Name | Default Value| Description | +| ----------------- | ------ | --------------- | +| SAMPLE_RATE_8000 | 8000 | The sampling rate is 8000. | +| SAMPLE_RATE_11025 | 11025 | The sampling rate is 11025.| +| SAMPLE_RATE_12000 | 12000 | The sampling rate is 12000.| +| SAMPLE_RATE_16000 | 16000 | The sampling rate is 16000.| +| SAMPLE_RATE_22050 | 22050 | The sampling rate is 22050.| +| SAMPLE_RATE_24000 | 24000 | The sampling rate is 24000.| +| SAMPLE_RATE_32000 | 32000 | The sampling rate is 32000.| +| SAMPLE_RATE_44100 | 44100 | The sampling rate is 44100.| +| SAMPLE_RATE_48000 | 48000 | The sampling rate is 48000.| +| SAMPLE_RATE_64000 | 64000 | The sampling rate is 64000.| +| SAMPLE_RATE_96000 | 96000 | The sampling rate is 96000.| ## AudioEncodingType8+ Enumerates the audio encoding types. -**System capability:** SystemCapability.Multimedia.Audio.Core - -| Name | Default Value | Description | -| :-------------------- | :------------- | :---------------- | -| ENCODING_TYPE_INVALID | -1 | Invalid. | -| ENCODING_TYPE_RAW | 0 | PCM encoding. | +**System capability**: SystemCapability.Multimedia.Audio.Core +| Name | Default Value| Description | +| --------------------- | ------ | --------- | +| ENCODING_TYPE_INVALID | -1 | Invalid. | +| ENCODING_TYPE_RAW | 0 | PCM encoding.| ## ContentType -Enumerates the content types. - -**System capability:** SystemCapability.Multimedia.Audio.Core +Enumerates the audio content types. -| Name | Default Value | Description | -| :----------------------------------| :------------ | :---------------------- | -| CONTENT_TYPE_UNKNOWN | 0 | Unknown content. | -| CONTENT_TYPE_SPEECH | 1 | Speech content. | -| CONTENT_TYPE_MUSIC | 2 | Music content. | -| CONTENT_TYPE_MOVIE | 3 | Movie content. | -| CONTENT_TYPE_SONIFICATION | 4 | Sonification content. | -| CONTENT_TYPE_RINGTONE8+ | 5 | Ringtone content. | +**System capability**: SystemCapability.Multimedia.Audio.Core +| Name | Default Value| Description | +| ---------------------------------- | ------ | ---------- | +| CONTENT_TYPE_UNKNOWN | 0 | Unknown content.| +| CONTENT_TYPE_SPEECH | 1 | Speech. | +| CONTENT_TYPE_MUSIC | 2 | Music. | +| CONTENT_TYPE_MOVIE | 3 | Movie. | +| CONTENT_TYPE_SONIFICATION | 4 | Sonification content.| +| CONTENT_TYPE_RINGTONE8+ | 5 | Ringtone. | ## StreamUsage -Enumerates the stream usage. - -**System capability:** SystemCapability.Multimedia.Audio.Core +Enumerates the audio stream usage. -| Name | Default Value | Description | -| :--------------------------------- | :------------ | :-------------------------------- | -| STREAM_USAGE_UNKNOWN | 0 | Unknown usage. | -| STREAM_USAGE_MEDIA | 1 | Media usage. | -| STREAM_USAGE_VOICE_COMMUNICATION | 2 | Voice communication usage. | -| STREAM_USAGE_NOTIFICATION_RINGTONE | 6 | Notification or ringtone usage. | +**System capability**: SystemCapability.Multimedia.Audio.Core +| Name | Default Value| Description | +| ---------------------------------- | ------ | ---------- | +| STREAM_USAGE_UNKNOWN | 0 | Unknown usage.| +| STREAM_USAGE_MEDIA | 1 | Used for media. | +| STREAM_USAGE_VOICE_COMMUNICATION | 2 | Used for voice communication.| +| STREAM_USAGE_NOTIFICATION_RINGTONE | 6 | Used for notification.| ## AudioState8+ Enumerates the audio states. -**System capability:** SystemCapability.Multimedia.Audio.Core - -| Name | Default Value | Description | -| :------------- | :------------ | :--------------------------- | -| STATE_INVALID | -1 | Invalid state. | -| STATE_NEW | 0 | Creating new instance state. | -| STATE_PREPARED | 1 | Prepared state. | -| STATE_RUNNING | 2 | Running state. | -| STATE_STOPPED | 3 | Stopped state. | -| STATE_RELEASED | 4 | Released state. | -| STATE_PAUSED | 5 | Paused state. | +**System capability**: SystemCapability.Multimedia.Audio.Core +| Name | Default Value| Description | +| -------------- | ------ | ---------------- | +| STATE_INVALID | -1 | Invalid state. | +| STATE_NEW | 0 | Creating instance state.| +| STATE_PREPARED | 1 | Prepared. | +| STATE_RUNNING | 2 | Running. | +| STATE_STOPPED | 3 | Stopped. | +| STATE_RELEASED | 4 | Released. | +| STATE_PAUSED | 5 | Paused. | ## AudioRendererRate8+ Enumerates the audio renderer rates. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -| Name | Default Value | Description | -| :----------------- | :------------ | :------------ | -| RENDER_RATE_NORMAL | 0 | Normal rate. | -| RENDER_RATE_DOUBLE | 1 | Double rate. | -| RENDER_RATE_HALF | 2 | Half rate. | +| Name | Default Value| Description | +| ------------------ | ------ | ---------- | +| RENDER_RATE_NORMAL | 0 | Normal rate.| +| RENDER_RATE_DOUBLE | 1 | Double rate. | +| RENDER_RATE_HALF | 2 | Half rate. | ## InterruptType -Enumerates the interrupt types. - -**System capability:** SystemCapability.Multimedia.Audio.Renderer +Enumerates the audio interruption types. -| Name | Default Value | Description | -| :------------------- | :------------ | :----------------------------------- | -| INTERRUPT_TYPE_BEGIN | 1 | Audio playback interruption started. | -| INTERRUPT_TYPE_END | 2 | Audio playback interruption ended. | +**System capability**: SystemCapability.Multimedia.Audio.Renderer +| Name | Default Value| Description | +| -------------------- | ------ | ---------------------- | +| INTERRUPT_TYPE_BEGIN | 1 | Audio interruption started.| +| INTERRUPT_TYPE_END | 2 | Audio interruption ended.| ## InterruptForceType9+ -Enumerates the interrupt force types. +Enumerates the types of force that causes audio interruption. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -| Name | Default Value | Description | -| :-------------- | :------------ | :----------------------------------------- | -| INTERRUPT_FORCE | 0 | Forced action taken by system. | -| INTERRUPT_SHARE | 1 | App can choose to take action or ignore. | +| Name | Default Value| Description | +| --------------- | ------ | ------------------------------------ | +| INTERRUPT_FORCE | 0 | Forced action taken by the system. | +| INTERRUPT_SHARE | 1 | The application can choose to take action or ignore.| ## InterruptHint -Enumerates the interrupt hints. +Enumerates the hints provided along with audio interruption. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -| Name | Default Value | Description | -| :--------------------------------- | :------------ | :--------------------------- | -| INTERRUPT_HINT_NONE8+ | 0 | None. | -| INTERRUPT_HINT_RESUME | 1 | Resume the playback. | -| INTERRUPT_HINT_PAUSE | 2 | Paused/Pause the playback. | -| INTERRUPT_HINT_STOP | 3 | Stopped/Stop the playback. | -| INTERRUPT_HINT_DUCK | 4 | Ducked the playback. | -| INTERRUPT_HINT_UNDUCK8+ | 5 | Unducked the playback. | +| Name | Default Value| Description | +| ---------------------------------- | ------ | -------------------------------------------- | +| INTERRUPT_HINT_NONE8+ | 0 | None. | +| INTERRUPT_HINT_RESUME | 1 | Resume the playback. | +| INTERRUPT_HINT_PAUSE | 2 | Paused/Pause the playback. | +| INTERRUPT_HINT_STOP | 3 | Stopped/Stop the playback. | +| INTERRUPT_HINT_DUCK | 4 | Ducked the playback. (In ducking, the audio volume is reduced, but not silenced.)| +| INTERRUPT_HINT_UNDUCK8+ | 5 | Unducked the playback. | ## InterruptActionType -Enumerates the interrupt event return types. +Enumerates the returned event types for audio interruption events. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**System capability:** SystemCapability.Multimedia.Audio.Renderer - -| Name | Default Value | Description | -| :------------- | :------------ | :---------------------------------------- | -| TYPE_ACTIVATED | 0 | Audio interrupt activated. | -| TYPE_INTERRUPT | 1 | Audio interrupted. | +| Name | Default Value| Description | +| -------------- | ------ | ------------------ | +| TYPE_ACTIVATED | 0 | Focus gain event.| +| TYPE_INTERRUPT | 1 | Audio interruption event.| ## AudioStreamInfo8+ Describes audio stream information. -**System capability:** SystemCapability.Multimedia.Audio.Core +**System capability**: SystemCapability.Multimedia.Audio.Core -| Name | Type | Mandatory | Description | -| :------------ | :---------------------------------------- | :-------- | :-------------------- | -| samplingRate | [AudioSamplingRate](#audiosamplingrate8) | Yes | Sampling rate. | -| channels | [AudioChannel](#audiochannel8) | Yes | Audio channels. | -| sampleFormat | [AudioSampleFormat](#audiosampleformat8) | Yes | Audio sample format. | -| encodingType | [AudioEncodingType](#audioencodingtype8) | Yes | Audio encoding type. | +| Name | Type | Mandatory| Description | +| ------------ | ---------------------------------------- | ---- | ------------------ | +| samplingRate | [AudioSamplingRate](#audiosamplingrate8) | Yes | Audio sampling rate.| +| channels | [AudioChannel](#audiochannel8) | Yes | Number of audio channels.| +| sampleFormat | [AudioSampleFormat](#audiosampleformat8) | Yes | Audio sample format. | +| encodingType | [AudioEncodingType](#audioencodingtype8) | Yes | Audio encoding type. | ## AudioRendererInfo8+ Describes audio renderer information. -**System capability:** SystemCapability.Multimedia.Audio.Core +**System capability**: SystemCapability.Multimedia.Audio.Core -| Name | Type | Mandatory | Description | -| :------------ | :-------------------------- | :-------- | :-------------------- | -| contentType | [ContentType](#contenttype) | Yes | Content type. | -| usage | [StreamUsage](#streamusage) | Yes | Stream usage. | -| rendererFlags | number | Yes | Audio renderer flags. | +| Name | Type | Mandatory| Description | +| ------------- | --------------------------- | ---- | ---------------- | +| content | [ContentType](#contenttype) | Yes | Audio content type. | +| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage.| +| rendererFlags | number | Yes | Audio renderer flags.| ## AudioRendererOptions8+ -Describes audio renderer configuration options. - -**System capability:** SystemCapability.Multimedia.Audio.Renderer +Describes audio renderer configurations. -| Name | Type | Mandatory | Description | -| :------------ | :-----------------------------------------| :-------- | :-------------------- | -| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Stream information. | -| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Renderer information. | +**System capability**: SystemCapability.Multimedia.Audio.Renderer -## AudioCapturerInfo8+ - -Describes audio capturer information. +| Name | Type | Mandatory| Description | +| ------------ | ---------------------------------------- | ---- | ---------------- | +| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.| +| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information.| -**System capability:** SystemCapability.Multimedia.Audio.Core +## InterruptEvent9+ -| Name | Type | Mandatory | Description | -| :---------------| :------------------------- | :-------- | :-------------------- | -| source | [SourceType](#sourcetype) | Yes | Audio source type. | -| capturerFlags | number | Yes | Audio capturer flags. | +Describes the interruption event received by the application when playback is interrupted. -## AudioCapturerOptions8+ +**System capability**: SystemCapability.Multimedia.Audio.Renderer -Describes audio capturer configuration options. +| Name | Type | Mandatory| Description | +| --------- | ------------------------------------------ | ---- | ------------------------------------ | +| eventType | [InterruptType](#interrupttype) | Yes | Whether the interruption has started or ended. | +| forceType | [InterruptForceType](#interruptforcetype9) | Yes | Whether the interruption is taken by the system or to be taken by the application.| +| hintType | [InterruptHint](#interrupthint) | Yes | Hint provided along the interruption. | -**System capability:** SystemCapability.Multimedia.Audio.Capturer +## AudioInterrupt -| Name | Type | Mandatory | Description | -| :------------ | :-----------------------------------------| :-------- | :-------------------- | -| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Stream information. | -| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Capturer information. | +Describes input parameters of audio interruption events. -## InterruptEvent9+ +**System capability**: SystemCapability.Multimedia.Audio.Renderer -Describes the interrupt event received by the app when playback is interrupted. +| Name | Type | Mandatory| Description | +| --------------- | --------------------------- | ---- | ------------------------------------------------------------ | +| streamUsage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | +| contentType | [ContentType](#contenttype) | Yes | Audio content type. | +| pauseWhenDucked | boolean | Yes | Whether audio playback can be paused during audio interruption. The value **true** means that audio playback can be paused during audio interruption, and **false** means the opposite.| -**System capability:** SystemCapability.Multimedia.Audio.Renderer +## InterruptAction -| Name | Type | Mandatory | Description | -| :-------- | :-------------------------------------------- | :-------- | :---------------------------------------------------------------- | -| eventType | [InterruptType](#interrupttype) | Yes | Whether the interruption has started or finished. | -| forceType | [InterruptForceType](#interruptforcetype9) | Yes | Whether the action is taken by system or to be taken by the app. | -| hintType | [InterruptHint](#interrupthint) | Yes | Type of action. | +Describes the callback invoked for audio interruption or focus gain events. -## AudioInterrupt +**System capability**: SystemCapability.Multimedia.Audio.Renderer -The parameters passed in by the audio listener event. +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| 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. | +| 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.| -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +## VolumeEvent8+ -**System capability:** SystemCapability.Multimedia.Audio.Renderer +Describes the event received by the application when the volume is changed. -| Name | Type | Mandatory | Description | -| --------------- | --------------------------- | ---- | ------------------------------------------------------------ | -| streamUsage | [StreamUsage](#streamusage) | Yes | Audio stream usage type. | -| contentType | [ContentType](#contenttype) | Yes | Audio interrupt media type. | -| pauseWhenDucked | boolean | Yes | Whether audio playback can be paused when audio is interrupted (true means audio playback can be paused during audio interruptions and false means the opposite). | +This is a system API and cannot be called by third-party applications. -## InterruptAction +**System capability**: SystemCapability.Multimedia.Audio.Volume -Callback method for the audio interrupt or audio interrupt activated event. +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| volume | number | Yes | Volume level. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**.| +| updateUi | boolean | Yes | Whether to show the volume change in UI. | -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +## DeviceChangeAction -**System capability:** SystemCapability.Multimedia.Audio.Renderer +Describes the device connection status and device information. -| Name | Type | Mandatory | Description | -| ---------- | ------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| actionType | [InterruptActionType](#interruptactiontype) | Yes | Event return type. TYPE_ACTIVATED is the audio interrupt activated event, and TYPE_INTERRUPT is the audio interrupt event. | -| type | [InterruptType](#interrupttype) | No | Interrupt event type. | -| hint | [InterruptHint](#interrupthint) | No | Interrupt event prompts. | -| activated | boolean | No | Acquire/release focus. true indicates that the focus acquisition/release is successful, and false indicates that the focus acquisition/release fails. | +**System capability**: SystemCapability.Multimedia.Audio.Device -## VolumeEvent8+ -Describes the volume event received by the app when the volume is changed. +| Name | Type | Mandatory| Description | +| :---------------- | :------------------------------------------------ | :--- | :----------------- | +| type | [DeviceChangeType](#DeviceChangeType) | Yes | Device connection status.| +| deviceDescriptors | [AudioDeviceDescriptors](#AudioDeviceDescriptors) | Yes | Device information. | -This is a system API and cannot be called by third-party applications. +## DeviceChangeType -**System capability:** SystemCapability.Multimedia.Audio.Volume +Enumerates the device connection statuses. -| Name | Type | Mandatory | Description | -| :--------- | :---------------------------------- | :-------- | :--------------------------------------- | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Volume type of the current stream. | -| volume | number | Yes | Volume level. | -| updateUi | boolean | Yes | Whether to show the volume change in UI. | +**System capability**: SystemCapability.Multimedia.Audio.Device -## DeviceChangeAction +| Name | Default Value| Description | +| :--------- | :----- | :------------- | +| CONNECT | 0 | Connected. | +| DISCONNECT | 1 | Disconnected.| -Describes the device change type and device information. +## AudioCapturerOptions8+ -**System capability:** SystemCapability.Multimedia.Audio.Device +Describes audio capturer configurations. -| Name | Type | Mandatory | Description | -| :------------------ | :------------------------------------------------ | :-------- | :------------------ | -| type | [DeviceChangeType](#devicechangetype) | Yes | Device change type. | -| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information. | +**System capability**: SystemCapability.Multimedia.Audio.Capturer +| Name | Type | Mandatory| Description | +| ------------ | --------------------------------------- | ---- | ---------------- | +| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.| +| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo) | Yes | Audio capturer information.| -## DeviceChangeType +## AudioCapturerInfo8+ -Enumerates device change types. +Describes audio capturer information. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Core -| Name | Default Value | Description | -| :--------------------- | :------------ | :-------------------- | -| CONNECT | 0 | Device connection. | -| DISCONNECT | 1 | Device disconnection. | +| Name | Type | Mandatory| Description | +| :------------ | :------------------------ | :--- | :--------------- | +| source | [SourceType](#sourcetype) | Yes | Audio source type. | +| capturerFlags | number | Yes | Audio capturer flags.| ## SourceType8+ -Enumerates source types. - -**System capability:** SystemCapability.Multimedia.Audio.Core +Enumerates the audio source types. -| Name | Default Value | Description | -| :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ | :------------------------------- | -| SOURCE_TYPE_INVALID | -1 | Invalid source type. | -| SOURCE_TYPE_MIC | 0 | Mic source type. | -| SOURCE_TYPE_VOICE_COMMUNICATION(This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR) | 7 | Voice communication source type. | +**System capability**: SystemCapability.Multimedia.Audio.Core +| Name | Default Value| Description | +| :------------------------------ | :----- | :--------------------- | +| SOURCE_TYPE_INVALID | -1 | Invalid audio source. | +| SOURCE_TYPE_MIC | 0 | Mic source. | +| SOURCE_TYPE_VOICE_COMMUNICATION | 7 | Voice communication source.| ## AudioScene8+ -Enumerates audio scenes. +Enumerates the audio scenes. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -| Name | Default Value | Description | -| :------------------------------------------------------------------------------------ | :------------ | :---------------------- | -| AUDIO_SCENE_DEFAULT | 0 | Default audio scene. | -| AUDIO_SCENE_RINGING(system API, not supported by third-party applications) | 1 | Ringing audio scene. | -| AUDIO_SCENE_PHONE_CALL(system API, not supported by third-party applications) | 2 | Phone call audio scene. | -| AUDIO_SCENE_VOICE_CHAT | 3 | Voice chat audio scene. | +| Name | Default Value| Description | +| :--------------------- | :----- | :-------------------------------------------- | +| AUDIO_SCENE_DEFAULT | 0 | Default audio scene. | +| AUDIO_SCENE_RINGING | 1 | Ringing audio scene.
This is a system API and cannot be called by third-party applications.| +| AUDIO_SCENE_PHONE_CALL | 2 | Phone call audio scene.
This is a system API and cannot be called by third-party applications.| +| AUDIO_SCENE_VOICE_CHAT | 3 | Voice chat audio scene. | ## AudioManager -Implements audio volume and audio device management. Before calling the interface of AudioManager, you need to create an instance through [getAudioManager](#audiogetaudiomanager). +Implements audio volume and audio device management. Before calling any API in **AudioManager**, you must use [getAudioManager](#audiogetaudiomanager) to create an **AudioManager** instance. ### setVolume -setVolume\(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback\): void +setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void Sets the volume for a stream. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------- | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Volume stream type. | -| volume | number | Yes | Volume to set. The value range can be obtained by calling getMinVolume and getMaxVolume. | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| volume | number | Yes | Volume to set. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | -**Example:** +**Example** ``` audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err) => { @@ -666,28 +659,29 @@ audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err) => { console.log('Callback invoked to indicate a successful volume setting.'); }); ``` + ### setVolume -setVolume\(volumeType: AudioVolumeType, volume: number\): Promise +setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> Sets the volume for a stream. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------- | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Volume stream type. | -| volume | number | Yes | Volume to set. The value range can be obtained by calling getMinVolume and getMaxVolume. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| volume | number | Yes | Volume to set. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| ------------------- | ----------------------------- | +| Promise<void> | Promise used to return the result.| -**Example:** +**Example** ``` audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { @@ -697,20 +691,20 @@ audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { ### getVolume -getVolume\(volumeType: AudioVolumeType, callback: AsyncCallback\): void +getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void -Obtains the volume of a stream. This API uses an asynchronous callback to return the query result. +Obtains the volume of a stream. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | -| callback | AsyncCallback | Yes | Callback used to return the volume. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------------ | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| callback | AsyncCallback<number> | Yes | Callback used to return the volume.| -**Example:** +**Example** ``` audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err, value) => { @@ -722,28 +716,27 @@ audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err, value) => { }); ``` - ### getVolume -getVolume\(volumeType: AudioVolumeType\): Promise +getVolume(volumeType: AudioVolumeType): Promise<number> -Obtains the volume of a stream. This API uses a promise to return the query result. +Obtains the volume of a stream. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------ | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| --------------------- | ------------------------- | +| Promise<number> | Promise used to return the volume.| -**Example:** +**Example** ``` audioManager.getVolume(audio.AudioVolumeType.MEDIA).then((value) => { @@ -753,20 +746,20 @@ audioManager.getVolume(audio.AudioVolumeType.MEDIA).then((value) => { ### getMinVolume -getMinVolume\(volumeType: AudioVolumeType, callback: AsyncCallback\): void +getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void -Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the query result. +Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | -| callback | AsyncCallback | Yes | Callback used to return the volume. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------------ | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| callback | AsyncCallback<number> | Yes | Callback used to return the minimum volume.| -**Example:** +**Example** ``` audioManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err, value) => { @@ -778,28 +771,27 @@ audioManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err, value) => { }); ``` - ### getMinVolume -getMinVolume\(volumeType: AudioVolumeType\): Promise +getMinVolume(volumeType: AudioVolumeType): Promise<number> -Obtains the minimum volume allowed for a stream. This API uses a promise to return the query result. +Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------ | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| --------------------- | ------------------------- | +| Promise<number> | Promise used to return the minimum volume.| -**Example:** +**Example** ``` audioManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value) => { @@ -809,20 +801,20 @@ audioManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value) => { ### getMaxVolume -getMaxVolume\(volumeType: AudioVolumeType, callback: AsyncCallback\): void +getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void -Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the query result. +Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | -| callback | AsyncCallback | Yes | Callback used to return the volume. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ---------------------- | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| callback | AsyncCallback<number> | Yes | Callback used to return the maximum volume.| -**Example:** +**Example** ``` audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err, value) => { @@ -834,28 +826,27 @@ audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err, value) => { }); ``` - ### getMaxVolume -getMaxVolume\(volumeType: AudioVolumeType\): Promise +getMaxVolume(volumeType: AudioVolumeType): Promise<number> -Obtains the maximum volume allowed for a stream. This API uses a promise to return the query result. +Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------ | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| --------------------- | ----------------------------- | +| Promise<number> | Promise used to return the maximum volume.| -**Example:** +**Example** ``` audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data) => { @@ -865,21 +856,21 @@ audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data) => { ### mute -mute\(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback\): void +mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void -Mutes a stream. This API uses an asynchronous callback to return the result. +Mutes or unmutes a stream. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | -| mute | boolean | Yes | Mute status to set. The value true means to mute the stream, and false means the opposite. | -| callback | AsyncCallback | Yes | Callback used to return the volume. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------------------------------- | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | -**Example:** +**Example** ``` audioManager.mute(audio.AudioVolumeType.MEDIA, true, (err) => { @@ -891,29 +882,29 @@ audioManager.mute(audio.AudioVolumeType.MEDIA, true, (err) => { }); ``` - ### mute -mute\(volumeType: AudioVolumeType, mute: boolean\): Promise +mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> + +Mutes or unmutes a stream. This API uses a promise to return the result. -Mutes a stream. This API uses a promise to return the result. +**System capability**: SystemCapability.Multimedia.Audio.Volume -**System capability:** SystemCapability.Multimedia.Audio.Volume +**Parameters** -**Parameters:** +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------------------------------- | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | -| mute | boolean | Yes | Mute status to set. The value true means to mute the stream, and false means the opposite. | +**Return value** -**Return value:** +| Type | Description | +| ------------------- | ----------------------------- | +| Promise<void> | Promise used to return the result.| -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +**Example** -**Example:** ``` audioManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { @@ -924,20 +915,20 @@ audioManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { ### isMute -isMute\(volumeType: AudioVolumeType, callback: AsyncCallback\): void +isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void -Checks whether a stream is muted. This API uses an asynchronous callback to return the query result. +Checks whether a stream is muted. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | -| callback | AsyncCallback | Yes | Callback used to return the mute status of the stream. The value true means that the stream is muted, and false means the opposite.| +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the mute status of the stream. The value **true** means that the stream is muted, and **false** means the opposite.| -**Example:** +**Example** ``` audioManager.isMute(audio.AudioVolumeType.MEDIA, (err, value) => { @@ -952,25 +943,25 @@ audioManager.isMute(audio.AudioVolumeType.MEDIA, (err, value) => { ### isMute -isMute\(volumeType: AudioVolumeType\): Promise +isMute(volumeType: AudioVolumeType): Promise<boolean> -Checks whether a stream is muted. This API uses a promise to return the result. +Checks whether a stream is muted. This method uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------- | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------ | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| Promise | Promise used to return the mute status of the stream. The value true means that the stream is muted, and false means the opposite. | +| Type | Description | +| ---------------------- | ------------------------------------------------------ | +| Promise<boolean> | Promise used to return the mute status of the stream. The value **true** means that the stream is muted, and **false** means the opposite.| -**Example:** +**Example** ``` audioManager.isMute(audio.AudioVolumeType.MEDIA).then((value) => { @@ -980,20 +971,20 @@ audioManager.isMute(audio.AudioVolumeType.MEDIA).then((value) => { ### isActive -isActive\(volumeType: AudioVolumeType, callback: AsyncCallback\) +isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void -Checks whether a stream is active. This API uses an asynchronous callback to return the query result. +Checks whether a stream is active. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | -| callback | AsyncCallback | Yes | Callback used to return the active status of the stream. The value true means that the stream is active, and false means the opposite.| +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the active status of the stream. The value **true** means that the stream is active, and **false** means the opposite.| -**Example:** +**Example** ``` audioManager.isActive(audio.AudioVolumeType.MEDIA, (err, value) => { @@ -1005,28 +996,27 @@ audioManager.isActive(audio.AudioVolumeType.MEDIA, (err, value) => { }); ``` - ### isActive -isActive\(volumeType: AudioVolumeType\): Promise +isActive(volumeType: AudioVolumeType): Promise<boolean> -Checks whether a stream is active. This API uses a promise to return the query result. +Checks whether a stream is active. This method uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ------------------ | -| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------- | ---- | ------------ | +| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| Promise | Promise used to return the active status of the stream. The value true means that the stream is active, and false means the opposite. | +| Type | Description | +| ---------------------- | -------------------------------------------------------- | +| Promise<boolean> | Promise used to return the active status of the stream. The value **true** means that the stream is active, and **false** means the opposite.| -**Example:** +**Example** ``` audioManager.isActive(audio.AudioVolumeType.MEDIA).then((value) => { @@ -1034,23 +1024,22 @@ audioManager.isActive(audio.AudioVolumeType.MEDIA).then((value) => { }); ``` - ### setRingerMode -setRingerMode\(mode: AudioRingMode, callback: AsyncCallback\): void +setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void Sets the ringer mode. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ----------------------------------- | -| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode. | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| -------- | ------------------------------- | ---- | ------------------------ | +| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err) => { @@ -1062,28 +1051,27 @@ audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err) => { }); ``` - ### setRingerMode -setRingerMode\(mode: AudioRingMode\): Promise +setRingerMode(mode: AudioRingMode): Promise<void> Sets the ringer mode. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------- | --------- | ----------------------------------- | -| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode. | +| Name| Type | Mandatory| Description | +| ------ | ------------------------------- | ---- | -------------- | +| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| ------------------- | ------------------------------- | +| Promise<void> | Promise used to return the result.| -**Example:** +**Example** ``` audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { @@ -1094,19 +1082,19 @@ audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { ### getRingerMode -getRingerMode\(callback: AsyncCallback\): void +getRingerMode(callback: AsyncCallback<AudioRingMode>): void -Obtains the ringer mode. This API uses an asynchronous callback to return the query result. +Obtains the ringer mode. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ----------------------------------------------- | --------- | ---------------------------------------- | -| callback | AsyncCallback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the ringer mode. | +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------------- | ---- | ------------------------ | +| callback | AsyncCallback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the ringer mode.| -**Example:** +**Example** ``` audioManager.getRingerMode((err, value) => { @@ -1121,19 +1109,19 @@ audioManager.getRingerMode((err, value) => { ### getRingerMode -getRingerMode\(\): Promise +getRingerMode(): Promise<AudioRingMode> -Obtains the ringer mode. This API uses a promise to return the query result. +Obtains the ringer mode. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -**Return value:** +**Return value** -| Type | Description | -| ---------------------------------------------- | --------------------------------------- | -| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode. | +| Type | Description | +| ---------------------------------------------- | ------------------------------- | +| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| -**Example:** +**Example** ``` audioManager.getRingerMode().then((value) => { @@ -1141,24 +1129,23 @@ audioManager.getRingerMode().then((value) => { }); ``` - ### setAudioParameter -setAudioParameter\(key: string, value: string, callback: AsyncCallback\): void +setAudioParameter(key: string, value: string, callback: AsyncCallback<void>): void Sets an audio parameter. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Core +**System capability**: SystemCapability.Multimedia.Audio.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ----------------------| --------- | ------------------------------------- | -| key | string | Yes | Key of the audio parameter to set. | -| value | string | Yes | Value of the audio parameter to set. | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ------------------------ | +| key | string | Yes | Key of the audio parameter to set. | +| value | string | Yes | Value of the audio parameter to set. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioManager.setAudioParameter('PBits per sample', '8 bit', (err) => { @@ -1170,29 +1157,28 @@ audioManager.setAudioParameter('PBits per sample', '8 bit', (err) => { }); ``` - ### setAudioParameter -setAudioParameter\(key: string, value: string\): Promise +setAudioParameter(key: string, value: string): Promise<void> Sets an audio parameter. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Core +**System capability**: SystemCapability.Multimedia.Audio.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ----------------------| --------- | ------------------------------------- | -| key | string | Yes | Key of the audio parameter to set. | -| value | string | Yes | Value of the audio parameter to set. | +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------- | +| key | string | Yes | Key of the audio parameter to set.| +| value | string | Yes | Value of the audio parameter to set.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| ------------------- | ------------------------------- | +| Promise<void> | Promise used to return the result.| -**Example:** +**Example** ``` audioManager.setAudioParameter('PBits per sample', '8 bit').then(() => { @@ -1200,23 +1186,22 @@ audioManager.setAudioParameter('PBits per sample', '8 bit').then(() => { }); ``` - ### getAudioParameter -getAudioParameter\(key: string, callback: AsyncCallback\) +getAudioParameter(key: string, callback: AsyncCallback<string>): void -Obtains the value of an audio parameter. This API uses an asynchronous callback to return the query result. +Obtains the value of an audio parameter. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Core +**System capability**: SystemCapability.Multimedia.Audio.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ----------------------| --------- | ---------------------------------------------------------- | -| key | string | Yes | Key of the audio parameter whose value is to be obtained. | -| callback | AsyncCallback | Yes | Callback used to return the value of the audio parameter. | +| Name | Type | Mandatory| Description | +| -------- | --------------------------- | ---- | ---------------------------- | +| key | string | Yes | Key of the audio parameter whose value is to be obtained. | +| callback | AsyncCallback<string> | Yes | Callback used to return the value of the audio parameter.| -**Example:** +**Example** ``` audioManager.getAudioParameter('PBits per sample', (err, value) => { @@ -1228,28 +1213,27 @@ audioManager.getAudioParameter('PBits per sample', (err, value) => { }); ``` - ### getAudioParameter -getAudioParameter\(key: string\): Promise +getAudioParameter(key: string): Promise<string> -Obtains the value of an audio parameter. This API uses a promise to return the query result. +Obtains the value of an audio parameter. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Core +**System capability**: SystemCapability.Multimedia.Audio.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ----------------------| --------- | ----------------------------------------------------------- | -| key | string | Yes | Key of the audio parameter whose value is to be obtained. | +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------- | +| key | string | Yes | Key of the audio parameter whose value is to be obtained.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the value of the audio parameter. | +| Type | Description | +| --------------------- | ----------------------------------- | +| Promise<string> | Promise used to return the value of the audio parameter.| -**Example:** +**Example** ``` audioManager.getAudioParameter('PBits per sample').then((value) => { @@ -1257,24 +1241,22 @@ audioManager.getAudioParameter('PBits per sample').then((value) => { }); ``` - ### getDevices -getDevices\(deviceFlag: DeviceFlag, callback: AsyncCallback\): void +getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void -Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the query result. +Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------------------------------- | --------- | ----------------------------------------- | -| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | -| callback | AsyncCallback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the device list. | - -**Example:** +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | -------------------- | +| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | +| callback | AsyncCallback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the device list.| +**Example** ``` audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err, value) => { if (err) { @@ -1285,29 +1267,27 @@ audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err, value) => { }); ``` - - ### getDevices -getDevices\(deviceFlag: DeviceFlag\): Promise +getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> -Obtains the audio devices with a specific flag. This API uses a promise to return the query result. +Obtains the audio devices with a specific flag. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | --------------------------- | --------- | ------------------- | -| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | +| Name | Type | Mandatory| Description | +| ---------- | ------------------------- | ---- | ---------------- | +| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| -**Return value:** +**Return value** -| Type | Description | -| ----------------------------------------------------------- | ---------------------------------------- | -| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list. | +| Type | Description | +| ------------------------------------------------------------ | ------------------------- | +| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| -**Example:** +**Example** ``` audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => { @@ -1317,21 +1297,21 @@ audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => { ### setDeviceActive -setDeviceActive\(deviceType: DeviceType, active: boolean, callback: AsyncCallback\): void +setDeviceActive(deviceType: ActiveDeviceType, active: boolean, callback: AsyncCallback<void>): void Sets a device to the active state. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------| --------- | ---------------------------------------------------------------------------------------------------------------- | -| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type. | -| active | boolean | Yes | Active status to set. The value true means to set the device to the active status, and false means the opposite. | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------- | ---- | ------------------------ | +| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type. | +| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioManager.setDeviceActive(audio.DeviceType.SPEAKER, true, (err) => { @@ -1343,31 +1323,29 @@ audioManager.setDeviceActive(audio.DeviceType.SPEAKER, true, (err) => { }); ``` - - ### setDeviceActive -setDeviceActive\(deviceType: DeviceType, active: boolean\): Promise +setDeviceActive(deviceType: ActiveDeviceType, active: boolean): Promise<void> Sets a device to the active state. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------| --------- | ---------------------------------------------------------------------------------------------------------------- | -| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type. | -| active | boolean | Yes | Active status to set. The value true means to set the device to the active status, and false means the opposite. | +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------- | ---- | ------------------ | +| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type.| +| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| ------------------- | ------------------------------- | +| Promise<void> | Promise used to return the result.| +**Example** -**Example:** ``` audioManager.setDeviceActive(audio.DeviceType.SPEAKER, true).then(() => { @@ -1375,23 +1353,22 @@ audioManager.setDeviceActive(audio.DeviceType.SPEAKER, true).then(() => { }); ``` - ### isDeviceActive -isDeviceActive\(deviceType: DeviceType, callback: AsyncCallback\): void +isDeviceActive(deviceType: ActiveDeviceType, callback: AsyncCallback<boolean>): void -Checks whether a device is active. This API uses an asynchronous callback to return the query result. +Checks whether a device is active. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------| --------- | -------------------------------------------------------- | -| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type. | -| callback | AsyncCallback | Yes | Callback used to return the active status of the device. | +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------- | ---- | ------------------------ | +| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type. | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the active state of the device.| -**Example:** +**Example** ``` audioManager.isDeviceActive(audio.DeviceType.SPEAKER, (err, value) => { @@ -1406,25 +1383,25 @@ audioManager.isDeviceActive(audio.DeviceType.SPEAKER, (err, value) => { ### isDeviceActive -isDeviceActive\(deviceType: DeviceType\): Promise +isDeviceActive(deviceType: ActiveDeviceType): Promise<boolean> -Checks whether a device is active. This API uses a promise to return the query result. +Checks whether a device is active. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------| --------- | ----------------------------------------- | -| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type. | +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------- | ---- | ------------------ | +| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type.| -**Return value:** +**Return value** -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the active status of the device. | +| Type | Description | +| ---------------------- | ------------------------------- | +| Promise<boolean> | Promise used to return the active state of the device.| -**Example:** +**Example** ``` audioManager.isDeviceActive(audio.DeviceType.SPEAKER).then((value) => { @@ -1432,23 +1409,22 @@ audioManager.isDeviceActive(audio.DeviceType.SPEAKER).then((value) => { }); ``` - ### setMicrophoneMute -setMicrophoneMute\(mute: boolean, callback: AsyncCallback\): void +setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | -------------------- | --------- | ---------------------------------------------------------------------------------------------- | -| mute | boolean | Yes | Mute status to set. The value true means to mute the microphone, and false means the opposite. | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | --------------------------------------------- | +| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | -**Example:** +**Example** ``` audioManager.setMicrophoneMute(true, (err) => { @@ -1460,30 +1436,27 @@ audioManager.setMicrophoneMute(true, (err) => { }); ``` - ### setMicrophoneMute -setMicrophoneMute\(mute: boolean\): Promise +setMicrophoneMute(mute: boolean): Promise<void> Mutes or unmutes the microphone. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device - -**Parameters:** +**System capability**: SystemCapability.Multimedia.Audio.Device -| Name | Type | Mandatory | Description | -| --------- | -------------------- | --------- | ---------------------------------------------------------------------------------------------- | -| mute | boolean | Yes | Mute status to set. The value true means to mute the microphone, and false means the opposite. | +**Parameters** -**Return value:** +| Name| Type | Mandatory| Description | +| ------ | ------- | ---- | --------------------------------------------- | +| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| -| Type | Description | -| ------------------- | ----------------------------------- | -| Promise | Promise used to return the result. | +**Return value** - +| Type | Description | +| ------------------- | ------------------------------- | +| Promise<void> | Promise used to return the result.| -**Example:** +**Example** ``` audioManager.setMicrophoneMute(true).then(() => { @@ -1491,25 +1464,23 @@ audioManager.setMicrophoneMute(true).then(() => { }); ``` - ### isMicrophoneMute -isMicrophoneMute\(callback: AsyncCallback\): void +isMicrophoneMute(callback: AsyncCallback<boolean>): void -Checks whether the microphone is muted. This API uses an asynchronous callback to return the query result. +Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the mute status of the microphone. The value true means that the microphone is muted, and false means the opposite. | +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ------------------------------------------------------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the mute status of the microphone. The value **true** means that the microphone is muted, and **false** means the opposite.| -**Example:** +**Example** ``` -var audioManager = audio.getAudioManager(); audioManager.isMicrophoneMute((err, value) => { if (err) { console.error('Failed to obtain the mute status of the microphone. ${err.message}'); @@ -1519,25 +1490,24 @@ audioManager.isMicrophoneMute((err, value) => { }); ``` - ### isMicrophoneMute -isMicrophoneMute\(\): Promise +isMicrophoneMute(): Promise<boolean> + +Checks whether the microphone is muted. This API uses a promise to return the result. -Checks whether the microphone is muted. This API uses a promise to return the query result. +**System capability**: SystemCapability.Multimedia.Audio.Device -**System capability:** SystemCapability.Multimedia.Audio.Device +**Return value** -**Return value:** +| Type | Description | +| ---------------------- | ------------------------------------------------------------ | +| Promise<boolean> | Promise used to return the mute status of the microphone. The value **true** means that the microphone is muted, and **false** means the opposite.| -| Type | Description | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| Promise | Promise used to return the mute status of the microphone. The value true means that the microphone is muted, and false means the opposite. | +**Example** -**Example:** ``` -var audioManager = audio.getAudioManager(); audioManager.isMicrophoneMute().then((value) => { console.log('Promise returned to indicate that the mute status of the microphone is obtained.', + value); }); @@ -1547,20 +1517,20 @@ audioManager.isMicrophoneMute().then((value) => { on(type: 'volumeChange', callback: Callback\): void -Subscribes to system volume change events. This API uses a callback to get volume change events. +Subscribes to system volume change events. This is a system API and cannot be called by third-party applications. -**System capability:** SystemCapability.Multimedia.Audio.Volume +**System capability**: SystemCapability.Multimedia.Audio.Volume -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :--------------------------------------| :-------------| :------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to. 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 get the system volume change event. | +| 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.| +| callback | Callback<[VolumeEvent](#volumeevent8)> | Yes | Callback used to return the system volume change event. | -**Example:** +**Example** ``` audioManager.on('volumeChange', (volumeEvent) => { @@ -1570,25 +1540,24 @@ audioManager.on('volumeChange', (volumeEvent) => { }); ``` - ### on('ringerModeChange')8+ on(type: 'ringerModeChange', callback: Callback\): void -Subscribes to ringer mode change events. This API uses a callback to get ringer mode changes. +Subscribes to ringer mode change events. This is a system API and cannot be called by third-party applications. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :----------------------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| type | string | Yes | Type of the event to subscribe to. 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 get the updated ringer mode. | +| 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.| +| callback | Callback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the updated ringer mode. | -**Example:** +**Example** ``` audioManager.on('ringerModeChange', (ringerMode) => { @@ -1600,18 +1569,18 @@ audioManager.on('ringerModeChange', (ringerMode) => { on(type: 'deviceChange', callback: Callback): void -Subscribes to device change events. When a device is connected/disconnected, registered clients will receive the callback. +Subscribes to device change events. When a device is connected or disconnected, registered clients will receive the callback. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :-------------------------------------------------- | :---------| :---------------------------------------------------------------------------------------------------------------------------------------------- | -| type | string | Yes | Type of the event to subscribe to. The value 'deviceChange' means the device change event, which is triggered when a device change is detected. | -| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | Yes | Callback used to obtain the device update details. | +| 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.| +| callback | Callback<[DeviceChangeAction](#DeviceChangeAction)\> | Yes | Callback used to return the device update details. | -**Example:** +**Example** ``` audioManager.on('deviceChange', (deviceChanged) => { @@ -1626,20 +1595,18 @@ audioManager.on('deviceChange', (deviceChanged) => { off(type: 'deviceChange', callback?: Callback): void -Unsubscribes from audio device connection change events. - -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +Unsubscribes from device change events. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :-------------------------------------------------- | :---------| :-------------------------------------------------- | -| type | string | Yes | Type of the event to unsubscribe from. | -| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to obtain the device update details. | +| 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.| +| callback | Callback<[DeviceChangeAction](#DeviceChangeAction)> | No | Callback used to return the device update details. | -**Example:** +**Example** ``` audioManager.off('deviceChange', (deviceChanged) => { @@ -1647,26 +1614,23 @@ audioManager.off('deviceChange', (deviceChanged) => { }); ``` - ### on('interrupt') on(type: 'interrupt', interrupt: AudioInterrupt, callback: Callback\): void -Subscribes to audio interrupt events. When the application's audio is interrupted by another playback event, the application will receive the callback. - -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +Subscribes to audio interruption events. When the application's audio is interrupted by another playback event, the application will receive the callback. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| --------- | --------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| type | string | Yes | Type of event to subscribe to. The value 'interrupt' means the audio interrupt event, which is triggered when the audio playback of the current application is interrupted by another application.| -| interrupt | AudioInterrupt | Yes | Audio interrupt event type. | -| callback | Callback<[InterruptAction](#interruptaction)> | Yes | Audio interrupt event callback method. | +| 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.| +| interrupt | AudioInterrupt | Yes | Audio interruption event type. | +| callback | Callback<[InterruptAction](#interruptaction)> | Yes | Callback invoked for the audio interruption event. | -**Example:** +**Example** ``` var interAudioInterrupt = { @@ -1690,21 +1654,19 @@ this.audioManager.on('interrupt', interAudioInterrupt, (InterruptAction) => { off(type: 'interrupt', interrupt: AudioInterrupt, callback?: Callback\): void -Unsubscribes from audio interrupt events. +Unsubscribes from audio interruption events. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**Parameters** -**Parameters:** +| 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.| +| interrupt | AudioInterrupt | Yes | Audio interruption event type. | +| callback | Callback<[InterruptAction](#interruptaction)> | No | Callback invoked for the audio interruption event. | -| Name | Type | Mandatory | Description | -| --------- | --------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| type | string | Yes | Type of event to unsubscribe from. The value 'interrupt' means the audio interrupt event, which is triggered when the audio playback of the current application is interrupted by another application. | -| interrupt | AudioInterrupt | Yes | Audio interrupt event type. | -| callback | Callback<[InterruptAction](#interruptaction)> | No | Audio interrupt event callback method. | - -**Example:** +**Example** ``` var interAudioInterrupt = { @@ -1720,25 +1682,24 @@ this.audioManager.off('interrupt', interAudioInterrupt, (InterruptAction) => { }); ``` - ### setAudioScene8+ setAudioScene\(scene: AudioScene, callback: AsyncCallback\): void -Sets the audio scene mode to change audio strategies. This API uses an asynchronous callback to return the result. +Sets an audio scene. This API uses an asynchronous callback to return the result. This is a system API and cannot be called by third-party applications. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------------------ | :-------- | :---------------------------------- | -| scene | AudioScene | Yes | Audio scene mode. | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| :------- | :----------------------------------- | :--- | :------------------- | +| scene | AudioScene | Yes | Audio scene to set. | +| callback | AsyncCallback | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err) => { @@ -1750,32 +1711,29 @@ audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err) => { }); ``` - ### setAudioScene8+ setAudioScene\(scene: AudioScene\): Promise -Sets the audio scene mode to change audio strategies. This API uses a promise to return the result. +Sets an audio scene. This API uses a promise to return the result. This is a system API and cannot be called by third-party applications. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :-------------------------------------- | :-------- | :---------------- | -| scene | AudioScene | Yes | Audio scene mode. | +| Name| Type | Mandatory| Description | +| :----- | :----------------------------------- | :--- | :------------- | +| scene | AudioScene | Yes | Audio scene to set.| +**Return value** -**Return value:** +| Type | Description | +| :------------- | :------------------- | +| Promise | Promise used to return the result.| -| Type | Description | -| :------------- | :---------------------------------- | -| Promise | Promise used to return the result. | - - -**Example:** +**Example** ``` audioManager.setAudioScene(audio.AudioSceneMode.AUDIO_SCENE_PHONE_CALL).then(() => { @@ -1785,22 +1743,21 @@ audioManager.setAudioScene(audio.AudioSceneMode.AUDIO_SCENE_PHONE_CALL).then(() }); ``` - ### getAudioScene8+ getAudioScene\(callback: AsyncCallback\): void -Obtains the audio scene mode. This API uses an asynchronous callback to return the query result. +Obtains the audio scene. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Communication +**System capability**: SystemCapability.Multimedia.Audio.Communication -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :-------------------------------------------------- | :-------- | :-------------------------------------------- | -| callback | AsyncCallback<AudioScene> | Yes | Callback used to return the audio scene mode. | +| Name | Type | Mandatory| Description | +| :------- | :-------------------------------------------------- | :--- | :--------------------------- | +| callback | AsyncCallback<AudioScene> | Yes | Callback used to return the audio scene.| -**Example:** +**Example** ``` audioManager.getAudioScene((err, value) => { @@ -1817,18 +1774,17 @@ audioManager.getAudioScene((err, value) => { getAudioScene\(\): Promise -Obtains the audio scene mode. This API uses a promise to return the query result. - -**System capability:** SystemCapability.Multimedia.Audio.Communication +Obtains the audio scene. This API uses a promise to return the result. -**Return value:** +**System capability**: SystemCapability.Multimedia.Audio.Communication -| Type | Description | -| :-------------------------------------------- | :------------------------------------------- | -| Promise<AudioScene> | Promise used to return the audio scene mode. | +**Return value** +| Type | Description | +| :-------------------------------------------- | :--------------------------- | +| Promise<AudioScene> | Promise used to return the audio scene.| -**Example:** +**Example** ``` audioManager.getAudioScene().then((value) => { @@ -1842,20 +1798,18 @@ audioManager.getAudioScene().then((value) => { Describes an audio device. -**System capability:** SystemCapability.Multimedia.Audio.Device +**System capability**: SystemCapability.Multimedia.Audio.Device -| Name | Type | Readable | Writable | Description | -| ---------- | ------------------------- | -------- | -------- | ------------------ | -| deviceRole | [DeviceRole](#devicerole) | Yes | No | Audio device role. | -| deviceType | [DeviceType](#devicetype) | Yes | No | Audio device type. | +| Name | Type | Readable| Writable| Description | +| ---------- | ------------------------- | ---- | ---- | ---------- | +| deviceRole | [DeviceRole](#devicerole) | Yes | No | Device role.| +| deviceType | [DeviceType](#devicetype) | Yes | No | Device type.| ## AudioDeviceDescriptors Array of [AudioDeviceDescriptor](#audiodevicedescriptor), which is read-only. -**System capability:** SystemCapability.Multimedia.Audio.Device - -**Example:** +**Example** ``` import audio from '@ohos.multimedia.audio'; @@ -1880,45 +1834,40 @@ promise.then(function (value) { } }); ``` -## AudioRenderer8+ - -Provides related APIs for audio rendering. Before calling the AudioRenderer API, you need to create an instance through [createAudioRenderer](#audiocreateaudiorenderer8). -**System capability:** SystemCapability.Multimedia.Audio.Renderer - -### state8+ +## AudioRenderer8+ -readonly state: AudioState +Provides APIs for audio rendering. Before calling any API in **AudioRenderer**, you must use [createAudioRenderer](#audiocreateaudiorenderer8) to create an **AudioRenderer** instance. -Defines the current render state. +### Attributes -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -| Name | Type | Readable | Writable | Description | -| :---- | :-------------------------- | :------- | :------- | :------------------ | -| state | [AudioState](#audiostate8) | Yes | No | Audio render state. | +| Name | Type | Readable| Writable| Description | +| ----- | -------------------------- | ---- | ---- | ------------------ | +| state8+ | [AudioState](#audiostate8) | Yes | No | Audio renderer state.| -**Example:** +**Example** ``` - var state = audioRenderer.state; +var state = audioRenderer.state; ``` ### getRendererInfo8+ getRendererInfo(callback: AsyncCallback): void -Obtains the renderer information provided while creating a renderer instance. This API uses an asynchronous callback to return the result. +Obtains the renderer information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------------------------------------- | :-------- | :------------------------------------------------ | -| callback | AsyncCallback<[AudioRendererInfo](#audiorendererinfo8)> | Yes | Callback used to return the renderer information. | +| Name | Type | Mandatory| Description | +| :------- | :------------------------------------------------------- | :--- | :--------------------- | +| callback | AsyncCallback<[AudioRendererInfo](#audiorendererinfo8)\> | Yes | Callback used to return the renderer information.| -**Example:** +**Example** ``` audioRenderer.getRendererInfo((err, rendererInfo) => { @@ -1929,22 +1878,21 @@ audioRenderer.getRendererInfo((err, rendererInfo) => { }); ``` - ### getRendererInfo8+ getRendererInfo(): Promise -Obtains the renderer information provided while creating a renderer instance. This API uses a promise to return the result. +Obtains the renderer information of this **AudioRenderer** instance. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :-------------------------------------------------- | :----------------------------------------------- | -| Promise<[AudioRendererInfo](#audiorendererinfo8)> | Promise used to return the renderer information. | +| Type | Description | +| -------------------------------------------------- | ------------------------------- | +| Promise<[AudioRendererInfo](#audiorendererinfo8)\> | Promise used to return the renderer information.| -**Example:** +**Example** ``` audioRenderer.getRendererInfo().then((rendererInfo) => { @@ -1956,24 +1904,23 @@ audioRenderer.getRendererInfo().then((rendererInfo) => { console.log('AudioFrameworkRenderLog: RendererInfo :ERROR: '+err.message); resultFlag = false; }); - ``` ### getStreamInfo8+ getStreamInfo(callback: AsyncCallback): void -Obtains the renderer stream information. This API uses an asynchronous callback to return the result. +Obtains the stream information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------------------------------------ | :-------- | :---------------------------------------------- | -| callback | AsyncCallback<[AudioStreamInfo](#audiostreaminfo8)\> | Yes | Callback used to return the stream information. | +| Name | Type | Mandatory| Description | +| :------- | :--------------------------------------------------- | :--- | :------------------- | +| callback | AsyncCallback<[AudioStreamInfo](#audiostreaminfo8)\> | Yes | Callback used to return the stream information.| -**Example:** +**Example** ``` audioRenderer.getStreamInfo((err, streamInfo) => { @@ -1989,17 +1936,17 @@ audioRenderer.getStreamInfo((err, streamInfo) => { getStreamInfo(): Promise -Obtains the renderer stream information. This API uses a promise to return the result. +Obtains the stream information of this **AudioRenderer** instance. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :------------------------------------------------- | :--------------------------------------------- | -| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information. | +| Type | Description | +| :--------------------------------------------- | :--------------------- | +| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| -**Example:** +**Example** ``` audioRenderer.getStreamInfo().then((streamInfo) => { @@ -2011,7 +1958,6 @@ audioRenderer.getStreamInfo().then((streamInfo) => { }).catch((err) => { console.log('ERROR: '+err.message); }); - ``` ### start8+ @@ -2020,16 +1966,15 @@ start(callback: AsyncCallback): void Starts the renderer. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :-------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the result. | -| | | | | +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioRenderer.start((err) => { @@ -2047,15 +1992,15 @@ start(): Promise Starts the renderer. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise used to return the result.| -**Example:** +**Example** ``` audioRenderer.start().then(() => { @@ -2065,23 +2010,21 @@ audioRenderer.start().then(() => { }); ``` - ### pause8+ pause(callback: AsyncCallback\): void Pauses rendering. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :------------------------------------ | -| callback | AsyncCallback | Yes | Callback used to return the result. | -| | | | | +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioRenderer.pause((err) => { @@ -2099,15 +2042,15 @@ pause(): Promise\ Pauses rendering. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise used to return the result.| -**Example:** +**Example** ``` audioRenderer.pause().then(() => { @@ -2123,16 +2066,15 @@ drain(callback: AsyncCallback\): void Drains the playback buffer. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :---------------------------------------| -| callback | AsyncCallback | Yes | Callback used to return the result. | -| | | | | +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioRenderer.drain((err) => { @@ -2150,15 +2092,15 @@ drain(): Promise\ Drains the playback buffer. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise used to return the result.| -**Example:** +**Example** ``` audioRenderer.drain().then(() => { @@ -2168,22 +2110,21 @@ audioRenderer.drain().then(() => { }); ``` - ### stop8+ stop(callback: AsyncCallback\): void Stops rendering. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioRenderer.stop((err) => { @@ -2201,15 +2142,15 @@ stop(): Promise\ Stops rendering. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise used to return the result.| -**Example:** +**Example** ``` audioRenderer.stop().then(() => { @@ -2219,22 +2160,21 @@ audioRenderer.stop().then(() => { }); ``` - ### release8+ release(callback: AsyncCallback\): void Releases the renderer. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioRenderer.release((err) => { @@ -2252,15 +2192,15 @@ release(): Promise\ Releases the renderer. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise used to return the result.| -**Example:** +**Example** ``` audioRenderer.release().then(() => { @@ -2276,16 +2216,16 @@ write(buffer: ArrayBuffer, callback: AsyncCallback\): void Writes the buffer. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :--------------------------------------------------------------------------------------------------- | -| buffer | ArrayBuffer | Yes | Buffer to be written. | -| callback | AsyncCallback | Yes | Returns the number of bytes written if the operation is successful; returns an error code otherwise. | +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | --------------------------------------------------- | +| buffer | ArrayBuffer | Yes | Buffer to be written. | +| callback | AsyncCallback\ | Yes | Returns the number of bytes written if the operation is successful; returns an error code otherwise.| -**Example:** +**Example** ``` import audio from '@ohos.multimedia.audio'; @@ -2303,22 +2243,21 @@ audioRenderer.write(buf, (err, writtenbytes) => { }); ``` - ### write8+ write(buffer: ArrayBuffer): Promise\ Writes the buffer. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :--------------- | :--------------------------------------------------------------------------------------------------- | -| Promise | Returns the number of bytes written if the operation is successful; returns an error code otherwise. | +| Type | Description | +| ---------------- | ------------------------------------------------------------ | +| Promise\ | Returns the number of bytes written if the operation is successful; returns an error code otherwise.| -**Example:** +**Example** ``` import audio from '@ohos.multimedia.audio'; @@ -2343,17 +2282,17 @@ audioRenderer.write(buf).then((writtenbytes) => { getAudioTime(callback: AsyncCallback\): void -Obtains the timestamp in Unix epoch time (starts from January 1, 1970), in nanoseconds. This API uses an asynchronous callback to return the result. +Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :--------------------- | :-------- | :------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the timestamp. | +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ---------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the timestamp.| -**Example:** +**Example** ``` audioRenderer.getAudioTime((err, timestamp) => { @@ -2361,22 +2300,21 @@ audioRenderer.getAudioTime((err, timestamp) => { }); ``` - ### getAudioTime8+ getAudioTime(): Promise\ -Obtains the timestamp in Unix epoch time (starts from January 1, 1970), in nanoseconds. This API uses a promise to return the result. +Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :--------------- | :------------------------------------ | -| Promise | Promise used to return the timestamp. | +| Type | Description | +| ---------------- | ----------------------- | +| Promise\ | Promise used to return the timestamp.| -**Example:** +**Example** ``` audioRenderer.getAudioTime().then((timestamp) => { @@ -2386,22 +2324,21 @@ audioRenderer.getAudioTime().then((timestamp) => { }); ``` - ### getBufferSize8+ getBufferSize(callback: AsyncCallback\): void Obtains a reasonable minimum buffer size in bytes for rendering. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :--------------------- | :-------- | :--------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the buffer size. | +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the buffer size.| -**Example:** +**Example** ``` audioRenderer.getBufferSize((err, bufferSize) => { @@ -2413,22 +2350,21 @@ let buf = new ArrayBuffer(bufferSize); ss.readSync(buf); ``` - ### getBufferSize8+ getBufferSize(): Promise\ Obtains a reasonable minimum buffer size in bytes for rendering. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :--------------- | :-------------------------------------- | -| Promise | Promise used to return the buffer size. | +| Type | Description | +| ---------------- | --------------------------- | +| Promise\ | Promise used to return the buffer size.| -**Example:** +**Example** ``` audioRenderer.getBufferSize().then((bufferSize) => { @@ -2445,16 +2381,16 @@ setRenderRate(rate: AudioRendererRate, callback: AsyncCallback\): void Sets the render rate. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------------------------ | :-------- | :---------------------------------- | -| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------- | ---- | ------------------------ | +| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL, (err) => { @@ -2466,28 +2402,27 @@ audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL, (err) => }); ``` - ### setRenderRate8+ setRenderRate(rate: AudioRendererRate): Promise\ Sets the render rate. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :--- | :--------------------------------------- | :-------- | :----------------- | -| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------------- | ---- | ------------ | +| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate.| -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise used to return the result.| -**Example:** +**Example** ``` audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL).then(() => { @@ -2503,15 +2438,15 @@ getRenderRate(callback: AsyncCallback\): void Obtains the current render rate. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------------------------------------- | :-------- | :--------------------------------------------- | -| callback | AsyncCallback<[AudioRendererRate](#audiorendererrate8)\> | Yes | Callback used to return the audio render rate. | +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------- | ---- | ------------------ | +| callback | AsyncCallback<[AudioRendererRate](#audiorendererrate8)> | Yes | Callback used to return the audio render rate.| -**Example:** +**Example** ``` audioRenderer.getRenderRate((err, renderrate) => { @@ -2519,22 +2454,21 @@ audioRenderer.getRenderRate((err, renderrate) => { }); ``` - ### getRenderRate8+ getRenderRate(): Promise\ Obtains the current render rate. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Return value:** +**Return value** -| Type | Description | -| :-------------------------------------------------- | :-------------------------------------------- | -| Promise<<[AudioRendererRate](#audiorendererrate8)\> | Promise used to return the audio render rate. | +| Type | Description | +| ------------------------------------------------- | ------------------------- | +| Promise<[AudioRendererRate](#audiorendererrate8)> | Promise used to return the audio render rate.| -**Example:** +**Example** ``` audioRenderer.getRenderRate().then((renderRate) => { @@ -2544,23 +2478,22 @@ audioRenderer.getRenderRate().then((renderRate) => { }); ``` - ### on('interrupt')9+ on(type: 'interrupt', callback: Callback\): void -Subscribes to audio interrupt events. This API uses a callback to get interrupt events. The interrupt event is triggered when audio rendering is interrupted. +Subscribes to audio interruption events. This API uses a callback to get interrupt events. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :-------------------------------------------- | :-------- | :---------------------------------------------- | -| type | string | Yes | Type of the playback event to subscribe to. | -| callback | Callback<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to listen for interrupt callback. | +| 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.| +| callback | Callback<[InterruptEvent](#interruptevent9)> | Yes | Callback used to return the audio interruption event. | -**Example:** +**Example** ``` audioRenderer.on('interrupt', (interruptEvent) => { @@ -2594,19 +2527,19 @@ audioRenderer.on('interrupt', (interruptEvent) => { on(type: 'markReach', frame: number, callback: (position: number) => {}): void -Subscribes to mark reached events. When the number of frames rendered reaches the value of the frame parameter, the callback is invoked. +Subscribes to mark reached events. When the number of frames rendered reaches the value of the **frame** parameter, the callback is invoked. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------ | :-------- | :----------------------------------------------------------------------- | -| type | string | Yes | Type of the renderer event to subscribe to. | -| 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. | +| 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.| +| 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. | -**Example:** +**Example** ``` audioRenderer.on('markReach', 1000, (position) => { @@ -2623,15 +2556,15 @@ off(type: 'markReach'): void Unsubscribes from mark reached events. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------ | :-------- | :----------------------------------------------- | -| type | string | Yes | Type of the renderer event to unsubscribe from. | +| Name| Type | Mandatory| Description | +| :----- | :----- | :--- | :------------------------------------------------ | +| type | string | Yes | Type of event to unsubscribe from. The value is fixed at **markReach**.| -**Example:** +**Example** ``` audioRenderer.off('markReach'); @@ -2641,19 +2574,19 @@ audioRenderer.off('markReach'); on(type: "periodReach", frame: number, callback: (position: number) => {}): void -Subscribes to period reached events. When the period of frame rendering reaches the value of frame parameter, the callback is invoked. +Subscribes to period reached events. When the period of frame rendering reaches the value of the **frame** parameter, the callback is invoked. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------ | :-------- | :--------------------------------------------------------------------------------- | -| type | string | Yes | Type of the renderer event to subscribe to. | -| 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. | +| 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.| +| 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. | -**Example:** +**Example** ``` audioRenderer.on('periodReach', 1000, (position) => { @@ -2669,15 +2602,15 @@ off(type: 'periodReach'): void Unsubscribes from period reached events. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------ | :-------- | :----------------------------------------------- | -| type | string | Yes | Type of the renderer event to unsubscribe from. | +| Name| Type | Mandatory| Description | +| :----- | :----- | :--- | :-------------------------------------------------- | +| type | string | Yes | Type of event to unsubscribe from. The value is fixed at **periodReach**.| -**Example:** +**Example** ``` audioRenderer.off('periodReach') @@ -2689,16 +2622,16 @@ on(type: 'stateChange', callback: Callback): void Subscribes to state change events. -**System capability:** SystemCapability.Multimedia.Audio.Renderer +**System capability**: SystemCapability.Multimedia.Audio.Renderer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------- | :-------- | :--------------------------------------------------------------------------------------- | -| type | string | Yes | Type of the event to subscribe to. The value 'stateChange' means the state change event. | -| callback | [AudioState](#audiostate8) | Yes | Callback used to return the state change. | +| Name | Type | Mandatory| Description | +| :------- | :------------------------- | :--- | :------------------------------------------ | +| type | string | Yes | Type of event to subscribe to. The value **stateChange** means the state change event.| +| callback | [AudioState](#audiostate8) | Yes | Callback used to return the state change. | -**Example:** +**Example** ``` audioRenderer.on('stateChange', (state) => { @@ -2713,42 +2646,37 @@ audioRenderer.on('stateChange', (state) => { ## AudioCapturer8+ -Provides related APIs for audio capture. Before calling the API of AudioCapturer, you need to create an instance through [createAudioCapturer](#audiocreateaudiocapturer8). - -### state8+ +Provides APIs for audio capture. Before calling any API in **AudioCapturer**, you must use [createAudioCapturer](#audiocreateaudiocapturer8) to create an **AudioCapturer** instance. -readonly state: AudioState +### Attributes -Defines the current capture state. +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**System capability:** SystemCapability.Multimedia.Audio.Capturer +| Name | Type | Readable| Writable| Description | +| :---- | :------------------------- | :--- | :--- | :--------------- | +| state8+ | [AudioState](#audiostate8) | Yes| No | Audio capturer state.| -| Name | Type | Readable | Writable | Description | -| :---- | :------------------------- | :------- | :------- | :------------------- | -| state | [AudioState](#audiostate8) | Yes | No | Audio capture state. | - -**Example:** +**Example** ``` var state = audioCapturer.state; ``` - ### getCapturerInfo8+ getCapturerInfo(callback: AsyncCallback): void -Obtains the capturer information provided while creating a capturer instance. This API uses an asynchronous callback to return the result. +Obtains the capturer information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------------------------------------- | :-------- | :------------------------------------------------ | -| callback | AsyncCallback<[AudioCapturerInfo](#audiocapturerinfo)\> | Yes | Callback used to return the capturer information. | +| Name | Type | Mandatory| Description | +| :------- | :-------------------------------- | :--- | :----------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the capturer information.| -**Example:** +**Example** ``` audioCapturer.getCapturerInfo((err, capturerInfo) => { @@ -2767,17 +2695,17 @@ audioCapturer.getCapturerInfo((err, capturerInfo) => { getCapturerInfo(): Promise -Obtains the capturer information provided while creating a capturer instance. This API uses a promise to return the result. +Obtains the capturer information of this **AudioCapturer** instance. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Return value:** +**Return value** -| Type | Description | -| :-------------------------------------------------- | :----------------------------------------------- | -| Promise<[AudioCapturerInfo](#audiocapturerinfo)\> | Promise used to return the capturer information. | +| Type | Description | +| :------------------------------------------------ | :---------------------------------- | +| Promise<[AudioCapturerInfo](#audiocapturerinfo)\> | Promise used to return the capturer information.| -**Example:** +**Example** ``` audioCapturer.getCapturerInfo().then((audioParamsGet) => { @@ -2792,24 +2720,23 @@ audioCapturer.getCapturerInfo().then((audioParamsGet) => { }).catch((err) => { console.log('AudioFrameworkRecLog: CapturerInfo :ERROR: '+err.message); }); - ``` ### getStreamInfo8+ getStreamInfo(callback: AsyncCallback): void -Obtains the capturer stream information. This API uses an asynchronous callback to return the result. +Obtains the stream information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :----------------------------------------------------------- | :-------- | :---------------------------------------------- | -| callback | AsyncCallback<[AudioStreamInfo](#audiostreaminfo8)\> | Yes | Callback used to return the stream information. | +| Name | Type | Mandatory| Description | +| :------- | :--------------------------------------------------- | :--- | :------------------------------- | +| callback | AsyncCallback<[AudioStreamInfo](#audiostreaminfo8)\> | Yes | Callback used to return the stream information.| -**Example:** +**Example** ``` audioCapturer.getStreamInfo((err, streamInfo) => { @@ -2829,17 +2756,17 @@ audioCapturer.getStreamInfo((err, streamInfo) => { getStreamInfo(): Promise -Obtains the capturer stream information. This API uses a promise to return the result. +Obtains the stream information of this **AudioCapturer** instance. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Return value:** +**Return value** -| Type | Description | -| :---------------------------------------------------- | :----------------------------------------------- | -| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information. | +| Type | Description | +| :--------------------------------------------- | :------------------------------ | +| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| -**Example:** +**Example** ``` audioCapturer.getStreamInfo().then((audioParamsGet) => { @@ -2851,7 +2778,6 @@ audioCapturer.getStreamInfo().then((audioParamsGet) => { }).catch((err) => { console.log('getStreamInfo :ERROR: ' + err.message); }); - ``` ### start8+ @@ -2860,15 +2786,15 @@ start(callback: AsyncCallback): void Starts capturing. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :-------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| :------- | :------------------- | :--- | :----------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioCapturer.start((err) => { @@ -2887,15 +2813,15 @@ start(): Promise Starts capturing. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| :------------- | :---------------------------- | +| Promise | Promise used to return the result.| -**Example:** +**Example** ``` audioCapturer.start().then(() => { @@ -2918,15 +2844,15 @@ stop(callback: AsyncCallback): void Stops capturing. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| :------- | :------------------- | :--- | :----------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the result.| -**Example:** +**Example** ``` audioCapturer.stop((err) => { @@ -2945,15 +2871,15 @@ stop(): Promise Stops capturing. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| :------------- | :---------------------------- | +| Promise | Promise used to return the result.| -**Example:** +**Example** ``` audioCapturer.stop().then(() => { @@ -2969,22 +2895,21 @@ audioCapturer.stop().then(() => { }); ``` - ### release8+ release(callback: AsyncCallback): void -Releases the capturer. This API uses an asynchronous callback to return the result. +Releases this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :---------------------- | :-------- | :------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| :------- | :------------------- | :--- | :---------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the result. | -**Example:** +**Example** ``` audioCapturer.release((err) => { @@ -3001,20 +2926,19 @@ audioCapturer.release((err) => { release(): Promise -Releases the capturer. This API uses a promise to return the result. +Releases this **AudioCapturer** instance. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Return value:** +**Return value** -| Type | Description | -| :------------- | :--------------------------------- | -| Promise | Promise used to return the result. | +| Type | Description | +| :------------- | :---------------------------- | +| Promise | Promise used to return the result.| -**Example:** +**Example** ``` - audioCapturer.release().then(() => { console.info('AudioFrameworkRecLog: ---------RELEASE RECORD---------'); console.info('AudioFrameworkRecLog: Capturer release : SUCCESS'); @@ -3027,7 +2951,6 @@ audioCapturer.release().then(() => { console.info('AudioFrameworkRecLog: Capturer stop:ERROR : '+err.message); stateFlag=false }); - ``` @@ -3035,19 +2958,19 @@ audioCapturer.release().then(() => { read(size: number, isBlockingRead: boolean, callback: AsyncCallback): void -Reads the buffer from the audio capturer. This API uses an asynchronous callback to return the result. +Reads the buffer. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------------- | :-------------------------- | :-------- | :-------------------------------------------- | -| size | number | Yes | Number of bytes to read. | -| isBlockingRead | boolean | Yes | Whether the read operation should be blocked. | -| callback | AsyncCallback | Yes | Callback used to return the buffer. | +| Name | Type | Mandatory| Description | +| :------------- | :-------------------------- | :--- | :------------------------------- | +| size | number | Yes | Number of bytes to read. | +| isBlockingRead | boolean | Yes | Whether to block the read operation. | +| callback | AsyncCallback | Yes | Callback used to return the buffer.| -**Example:** +**Example** ``` audioCapturer.read(bufferSize, true, async(err, buffer) => { @@ -3062,24 +2985,24 @@ audioCapturer.read(bufferSize, true, async(err, buffer) => { read(size: number, isBlockingRead: boolean): Promise -Reads the buffer from the audio capturer. This API uses a promise to return the result. +Reads the buffer. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------------- | :--------- | :-------- | :-------------------------------------------- | -| size | number | Yes | Number of bytes to read. | -| isBlockingRead | boolean | Yes | Whether the read operation should be blocked. | +| Name | Type | Mandatory| Description | +| :------------- | :------ | :--- | :--------------- | +| size | number | Yes | Number of bytes to read. | +| isBlockingRead | boolean | Yes | Whether to block the read operation.| -**Return value:** +**Return value** -| Type | Description | -| :-------------------- | :----------------------------------------------------------------------------------------------- | -| Promise | Returns the buffer data read if the operation is successful; returns an error code otherwise. | +| Type | Description | +| :-------------------- | :----------------------------------------------------- | +| Promise | Returns the buffer data read if the operation is successful; returns an error code otherwise.| -**Example:** +**Example** ``` audioCapturer.read(bufferSize, true).then((buffer) => { @@ -3094,18 +3017,17 @@ audioCapturer.read(bufferSize, true).then((buffer) => { getAudioTime(callback: AsyncCallback): void -Obtains the timestamp in Unix epoch time (starts from January 1, 1970), in nanoseconds. This API uses an asynchronous callback to return the result. +Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :--------------------- | :-------- | :------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the timestamp. | -| | | | | +| Name | Type | Mandatory| Description | +| :------- | :--------------------- | :--- | :----------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the timestamp.| -**Example:** +**Example** ``` audioCapturer.getAudioTime((err, timestamp) => { @@ -3118,17 +3040,17 @@ audioCapturer.getAudioTime((err, timestamp) => { getAudioTime(): Promise -Obtains the timestamp in Unix epoch time (starts from January 1, 1970), in nanoseconds. This API uses a promise to return the result. +Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Return value:** +**Return value** -| Type | Description | -| :--------------- | :------------------------------------ | -| Promise | Promise used to return the timestamp. | +| Type | Description | +| :--------------- | :---------------------------- | +| Promise | Promise used to return the timestamp.| -**Example:** +**Example** ``` audioCapturer.getAudioTime().then((audioTime) => { @@ -3136,7 +3058,6 @@ audioCapturer.getAudioTime().then((audioTime) => { }).catch((err) => { console.info('AudioFrameworkRecLog: AudioCapturer Created : ERROR : '+err.message); }); - ``` @@ -3146,16 +3067,15 @@ getBufferSize(callback: AsyncCallback): void Obtains a reasonable minimum buffer size in bytes for capturing. This API uses an asynchronous callback to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :--------------------- | :-------- | :--------------------------------------- | -| callback | AsyncCallback | Yes | Callback used to return the buffer size. | -| | | | | +| Name | Type | Mandatory| Description | +| :------- | :--------------------- | :--- | :----------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the buffer size.| -**Example:** +**Example** ``` audioCapturer.getBufferSize((err, bufferSize) => { @@ -3170,21 +3090,22 @@ audioCapturer.getBufferSize((err, bufferSize) => { }); ``` + ### getBufferSize8+ getBufferSize(): Promise Obtains a reasonable minimum buffer size in bytes for capturing. This API uses a promise to return the result. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Return value:** +**Return value** -| Type | Description | -| :--------------- | :-------------------------------------- | -| Promise | Promise used to return the buffer size. | +| Type | Description | +| :--------------- | :---------------------------------- | +| Promise | Promise used to return the buffer size.| -**Example:** +**Example** ``` audioCapturer.getBufferSize().then((bufferSize) => { @@ -3199,23 +3120,24 @@ audioCapturer.getBufferSize().then((bufferSize) => { }); ``` + ### on('markReach')8+ on(type: 'markReach', frame: number, callback: (position: number) => {}): void -Subscribes to mark reached events. When the number of frames captured reaches the value of the frame parameter, the callback is invoked. +Subscribes to mark reached events. When the number of frames captured reaches the value of the **frame** parameter, the callback is invoked. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------ | :-------- | :----------------------------------------------------------------------- | -| type | string | Yes | Type of the capturer event to subscribe to. | -| 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. | +| 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. | +| 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.| -**Example:** +**Example** ``` audioCapturer.on('markReach', 1000, (position) => { @@ -3225,22 +3147,21 @@ audioCapturer.on('markReach', 1000, (position) => { }); ``` - ### off('markReach')8+ off(type: 'markReach'): void -Unsubscribes from the mark reached events. +Unsubscribes from mark reached events. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------ | :-------- | :---------------------------------------------- | -| type | string | Yes | Type of the capturer event to unsubscribe from. | +| 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.| -**Example:** +**Example** ``` audioCapturer.off('markReach'); @@ -3250,19 +3171,19 @@ audioCapturer.off('markReach'); on(type: "periodReach", frame: number, callback: (position: number) => {}): void -Subscribes to period reached events. When the period of frame capturing reaches the value of frame parameter, the callback is invoked. +Subscribes to mark reached events. When the period of frame capturing reaches the value of the **frame** parameter, the callback is invoked. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------ | :-------- | :--------------------------------------------------------------------------------- | -| type | string | Yes | Type of the capturer event to subscribe to. | -| 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. | +| 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.| +| 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. | -**Example:** +**Example** ``` audioCapturer.on('periodReach', 1000, (position) => { @@ -3278,15 +3199,15 @@ off(type: 'periodReach'): void Unsubscribes from period reached events. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------ | :-------- | :---------------------------------------------- | -| type | string | Yes | Type of the capturer event to unsubscribe from. | +| 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.| -**Example:** +**Example** ``` audioCapturer.off('periodReach') @@ -3298,16 +3219,16 @@ on(type: 'stateChange', callback: Callback): void Subscribes to state change events. -**System capability:** SystemCapability.Multimedia.Audio.Capturer +**System capability**: SystemCapability.Multimedia.Audio.Capturer -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------------- | :-------- | :--------------------------------------------------------------------------------------- | -| type | string | Yes | Type of the event to subscribe to. The value 'stateChange' means the state change event. | -| callback | [AudioState](#audiostate8) | Yes | Callback used to return the state change. | +| Name | Type | Mandatory| Description | +| :------- | :------------------------- | :--- | :------------------------------------------ | +| type | string | Yes | Type of event to subscribe to. The value **stateChange** means the state change event.| +| callback | [AudioState](#audiostate8) | Yes | Callback used to return the state change. | -**Example:** +**Example** ``` audioCapturer.on('stateChange', (state) => { diff --git a/en/application-dev/reference/apis/js-apis-image.md b/en/application-dev/reference/apis/js-apis-image.md index 8d00068ceb8fcce01332ec03b1cca23613254354..5b564c7addd10b39e5873bf50faa84efc9ff1ad6 100644 --- a/en/application-dev/reference/apis/js-apis-image.md +++ b/en/application-dev/reference/apis/js-apis-image.md @@ -1,16 +1,16 @@ # Image Processing -> **NOTE** +> **NOTE**
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import -``` +```js import image from '@ohos.multimedia.image'; ``` ## image.createPixelMap8+ -createPixelMap(colors: ArrayBuffer, options: InitializetionOptions): Promise\ +createPixelMap(colors: ArrayBuffer, options: InitializationOptions): Promise\ Creates a **PixelMap** object. This API uses a promise to return the result. @@ -21,7 +21,7 @@ Creates a **PixelMap** object. This API uses a promise to return the result. | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | | colors | ArrayBuffer | Yes | Color array. | -| options | [InitializetionOptions](#initializationoptions8) | Yes | Pixel properties, including the alpha type, size, scale mode, pixel format, and editable.| +| options | [InitializationOptions](#initializationoptions8) | Yes | Pixel properties, including the alpha type, size, scale mode, pixel format, and editable.| **Return value** @@ -39,7 +39,7 @@ image.createPixelMap(Color, opts) ## image.createPixelMap8+ -createPixelMap(colors: ArrayBuffer, options: InitializetionOptions, callback: AsyncCallback\): void +createPixelMap(colors: ArrayBuffer, options: InitializationOptions, callback: AsyncCallback\): void Creates a **PixelMap** object. This API uses an asynchronous callback to return the result. @@ -50,7 +50,7 @@ Creates a **PixelMap** object. This API uses an asynchronous callback to return | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------ | ---- | -------------------------- | | colors | ArrayBuffer | Yes | Color array. | -| options | [InitializetionOptions](#initializationoptions8) | Yes | Pixel properties. | +| options | [InitializationOptions](#initializationoptions8) | Yes | Pixel properties. | | callback | AsyncCallback\<[PixelMap](#pixelmap7)> | Yes | Callback used to return the **PixelMap** object.| **Example** @@ -66,9 +66,11 @@ Provides APIs to read or write image pixel map data and obtain image pixel map i ### Attributes -| Name | Type | Readable| Writable| Description | -| ----------------------- | ------- | ---- | ---- | ------------------------------------------------------------ | -| isEditable7+ | boolean | Yes | No | Whether the image pixel map is editable.
**System capability**: SystemCapability.Multimedia.Image| +**System capability**: SystemCapability.Multimedia.Image + +| Name | Type | Readable| Writable| Description | +| ----------------------- | ------- | ---- | ---- | -------------------------- | +| isEditable7+ | boolean | Yes | No | Whether the image pixel map is editable.| ### readPixelsToBuffer7+ @@ -468,7 +470,7 @@ Creates an **ImageSource** instance based on the URI. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ---------------------------------- | -| uri | string | Yes | Image source URI. Currently, only the local absolute path is supported.| +| uri | string | Yes | Image path. Currently, only the application sandbox path is supported.| **Return value** @@ -479,7 +481,8 @@ Creates an **ImageSource** instance based on the URI. **Example** ```js -const imageSourceApi = image.createImageSource('/data/local/tmp/test.jpg') +let path = this.context.getApplicationContext().fileDirs + "test.jpg"; +const imageSourceApi = image.createImageSource(path); ``` ## image.createImageSource7+ @@ -514,9 +517,11 @@ Provides APIs to obtain image information. Before calling any API in **ImageSour ### Attributes +**System capability**: SystemCapability.Multimedia.Image + | Name | Type | Readable| Writable| Description | | ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | -| supportedFormats | Array\ | Yes | No | Supported image formats, including png, jpeg, wbmp, bmp, gif, webp, and heif.
**System capability**: SystemCapability.Multimedia.Image| +| supportedFormats | Array\ | Yes | No | Supported image formats, including png, jpeg, wbmp, bmp, gif, webp, and heif.| ### getImageInfo @@ -793,13 +798,15 @@ Provide APIs to pack images. Before calling any API in **ImagePacker**, you must ### Attributes -| Name | Type | Readable| Writable| Description | -| ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | -| supportedFormats | Array\ | Yes | No | Supported image format, which can be jpeg.
**System capability**: SystemCapability.Multimedia.Image| +**System capability**: SystemCapability.Multimedia.Image + +| Name | Type | Readable| Writable| Description | +| ---------------- | -------------- | ---- | ---- | -------------------------- | +| supportedFormats | Array\ | Yes | No | Supported image format, which can be jpeg.| ### packing -packing(source: ImageSource, option: PackingOption, callback: AsyncCallback>): void +packing(source: ImageSource, option: PackingOption, callback: AsyncCallback\): void Packs an image. This API uses an asynchronous callback to return the result. @@ -811,7 +818,7 @@ Packs an image. This API uses an asynchronous callback to return the result. | -------- | ---------------------------------- | ---- | ---------------------------------- | | source | [ImageSource](#imagesource) | Yes | Image to pack. | | option | [PackingOption](#packingoption) | Yes | Option for image packing. | -| callback | AsyncCallback> | Yes | Callback used to return the packed data.| +| callback | AsyncCallback\ | Yes | Callback used to return the packed data.| **Example** @@ -822,7 +829,7 @@ imagePackerApi.packing(imageSourceApi, packOpts, data => {}) ### packing -packing(source: ImageSource, option: PackingOption): Promise> +packing(source: ImageSource, option: PackingOption): Promise\ Packs an image. This API uses a promise to return the result. @@ -839,7 +846,7 @@ Packs an image. This API uses a promise to return the result. | Type | Description | | :--------------------------- | :-------------------------------------------- | -| Promise> | Promise used to return the packed data.| +| Promise\ | Promise used to return the packed data.| **Example** @@ -850,7 +857,7 @@ imagePackerApi.packing(imageSourceApi, packOpts) .catch(error => {}) ``` -### packing +### packing8+ packing(source: PixelMap, option: PackingOption, callback: AsyncCallback\): void @@ -873,9 +880,9 @@ let packOpts = { format:["image/jpeg"], quality:98 } imagePackerApi.packing(pixelMapApi, packOpts, data => {}) ``` -### packing +### packing8+ -packing(source: PixelMap, option: PackingOption): Promise> +packing(source: PixelMap, option: PackingOption): Promise\ Packs an image. This API uses a promise to return the result. @@ -883,16 +890,16 @@ Packs an image. This API uses a promise to return the result. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------------------------------- | ---- | -------------- | +| Name| Type | Mandatory| Description | +| ------ | ------------------------------- | ---- | ------------------ | | source | [PixelMap](#pixelmap) | Yes | **PixelMap** object to pack.| -| option | [PackingOption](#packingoption) | Yes | Option for image packing.| +| option | [PackingOption](#packingoption) | Yes | Option for image packing. | **Return value** | Type | Description | | :--------------------------- | :-------------------------------------------- | -| Promise> | Promise used to return the packed data.| +| Promise\ | Promise used to return the packed data.| **Example** @@ -944,6 +951,345 @@ Releases this **ImagePacker** instance. This API uses a promise to return the re }).catch((error)=>{}) ``` +## image.createImageReceiver9+ + +createImageReceiver(width: number, height: number, format: number, capacity: number): ImageReceiver + +Create an **ImageReceiver** instance by specifying the image width, height, format, and capacity. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ---------------------- | +| width | number | Yes | Default image width. | +| height | number | Yes | Default image height. | +| format | number | Yes | Image format. | +| capacity | number | Yes | Maximum number of images that can be accessed at the same time.| + +**Return value** + +| Type | Description | +| -------------------------------- | --------------------------------------- | +| [ImageReceiver](#imagereceiver9) | Returns an **ImageReceiver** instance if the operation is successful.| + +**Example** + +```js +var receiver = image.createImageReceiver(8192, 8, 4, 8) +``` + +## ImageReceiver9+ + +Provides APIs to obtain the surface ID of a component, read the latest image, read the next image, and release the **ImageReceiver** instance. + +Before calling any APIs in **ImageReceiver**, you must create an **ImageReceiver** instance. + +### Attributes + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +| Name | Type | Readable| Writable| Description | +| --------------------- | ---------------------------- | ---- | ---- | ------------------ | +| size9+ | [Size](#size) | Yes | No | Image size. | +| capacity9+ | number | Yes | No | Maximum number of images that can be accessed at the same time.| +| format9+ | [ImageFormat](#imageformat9) | Yes | No | Image format. | + +### getReceivingSurfaceId9+ + +getReceivingSurfaceId(callback: AsyncCallback\): void + +Obtains a surface ID for the camera or other components. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the surface ID.| + +**Example** + +```js + receiver.getReceivingSurfaceId((err, id) => {}); +``` + +### getReceivingSurfaceId9+ + +getReceivingSurfaceId(): Promise\ + +Obtains a surface ID for the camera or other components. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Return value** + +| Type | Description | +| ---------------- | -------------------- | +| Promise\ | Promise used to return the surface ID.| + +**Example** + +```js +receiver.getReceivingSurfaceId().then( id => { + }).catch(error => { + }) +``` + +### readLatestImage9+ + +readLatestImage(callback: AsyncCallback\): void + +Reads the latest image from the **ImageReceiver** instance. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------- | ---- | ------------------------ | +| callback | AsyncCallback<[Image](#image9)> | Yes | Callback used to return the latest image.| + +**Example** + +```js + receiver.readLatestImage((err, img) => { }); +``` + +### readLatestImage9+ + +readLatestImage(): Promise\ + +Reads the latest image from the **ImageReceiver** instance. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Return value** + +| Type | Description | +| ------------------------- | ------------------ | +| Promise<[Image](#image8)> | Promise used to return the latest image.| + +**Example** + +```js +receiver.readLatestImage().then(img => {}) + .catch(error => {}) +``` + +### readNextImage9+ + +readNextImage(callback: AsyncCallback\): void + +Reads the next image from the **ImageReceiver** instance. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------- | ---- | -------------------------- | +| callback | AsyncCallback<[Image](#image9)> | Yes | Callback used to return the next image.| + +**Example** + +```js +receiver.readNextImage((err, img) => {}); +``` + +### readNextImage9+ + +readNextImage(): Promise\ + +Reads the next image from the **ImageReceiver** instance. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Return value** + +| Type | Description | +| ------------------------- | -------------------- | +| Promise<[Image](#image9)> | Promise used to return the next image.| + +**Example** + +```js + receiver.readNextImage().then(img => { + }).catch(error => { + }) +``` + +### on('imageArrival')9+ + +on(type: 'imageArrival', callback: AsyncCallback\): void + +Listens for image arrival events. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------------------------------------ | +| type | string | Yes | Type of event to listen for. The value is fixed at **imageArrival**, which is triggered when an image is received.| +| callback | AsyncCallback\ | Yes | Callback invoked for the event. | + +**Example** + +```js + receiver.on('imageArrival', () => {}) +``` + +### release9+ + +release(callback: AsyncCallback\): void + +Releases this **ImageReceiver** instance. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------ | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js + receiver.release(() => {}) +``` + +### release9+ + +release(): Promise\ + +Releases this **ImageReceiver** instance. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +**Return value** + +| Type | Description | +| -------------- | ------------------ | +| Promise\ | Promise used to return the result.| + +**Example** + +```js + receiver.release().then(() => {}) + .catch(error => {}) +``` + +## Image9+ + +Provides APIs for basic image operations, including obtaining image information and reading and writing image data. An **Image** instance is returned when [readNextImage](#readnextimage9) and [readLatestImage](#readlatestimage9) are called. + +### Attributes + +**System capability**: SystemCapability.Multimedia.Image.Core + +| Name | Type | Readable| Writable| Description | +| --------------------- | ------------------ | ---- | ---- | -------------------------------------------------- | +| clipRect9+ | [Region](#region7) | Yes | Yes | Image area to be cropped. | +| size9+ | [Size](#size) | Yes | No | Image size. | +| format9+ | number | Yes | No | Image format. For details, see [PixelMapFormat](#pixelmapformat7).| + +### getComponent9+ + +getComponent(componentType: ComponentType, callback: AsyncCallback\): void + +Obtains the component buffer from the **Image** instance based on the color component type. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------- | --------------------------------------- | ---- | -------------------- | +| componentType | [ComponentType](#componenttype9) | Yes | Color component type of the image. | +| callback | AsyncCallback<[Component](#component9)> | Yes | Callback used to return the component buffer.| + +**Example** + +```js + img.getComponent(4, (err, component) => {}) +``` + +### getComponent9+ + +getComponent(componentType: ComponentType): Promise\ + +Obtains the component buffer from the **Image** instance based on the color component type. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Image.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------- | -------------------------------- | ---- | ---------------- | +| componentType | [ComponentType](#componenttype9) | Yes | Color component type of the image.| + +**Return value** + +| Type | Description | +| --------------------------------- | --------------------------------- | +| Promise<[Component](#component9)> | Promise used to return the component buffer.| + +**Example** + +```js +img.getComponent(4).then(component => { }) +``` + +### release9+ + +release(callback: AsyncCallback\): void + +Releases this **Image** instance. This API uses an asynchronous callback to return the result. + +The corresponding resources must be released before another image arrives. + +**System capability**: SystemCapability.Multimedia.Image.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | -------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +img.release(() =>{ }) +``` + +### release9+ + +release(): Promise\ + +Releases this **Image** instance. This API uses a promise to return the result. + +The corresponding resources must be released before another image arrives. + +**System capability**: SystemCapability.Multimedia.Image.Core + +**Return value** + +| Type | Description | +| -------------- | --------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +img.release().then(() =>{ + }).catch(error => { + }) +``` + ## PositionArea7+ Describes area information in an image. @@ -954,8 +1300,8 @@ Describes area information in an image. | ------ | ------------------ | ---- | ---- | ------------------------------------------------------------ | | pixels | ArrayBuffer | Yes | No | Pixels of the image. | | offset | number | Yes | No | Offset for data reading. | -| stride | number | Yes | No | Number of bytes from one row of pixels in memory to the next row of pixels in memory. The value of **stride** must be greater than or equal to the value of **region.size.width** multiplied by 4. | -| region | [Region](#region8) | Yes | No | Region to read or write. The width of the region to write plus the X coordinate cannot be greater than the width of the original image. The height of the region to write plus the Y coordinate cannot be greater than the height of the original image.| +| stride | number | Yes | No | Number of bytes from one row of pixels in memory to the next row of pixels in memory. The value of **stride** must be greater than or equal to the value of **region.size.width** multiplied by 4. | +| region | [Region](#region7) | Yes | No | Region to read or write. The width of the region to write plus the X coordinate cannot be greater than the width of the original image. The height of the region to write plus the Y coordinate cannot be greater than the height of the original image.| ## ImageInfo @@ -980,7 +1326,7 @@ Describes the size of an image. ## PixelMapFormat7+ -Enumerates pixel map formats. +Enumerates the pixel formats of images. **System capability**: SystemCapability.Multimedia.Image @@ -992,7 +1338,7 @@ Enumerates pixel map formats. ## AlphaType9+ -Enumerates alpha types. +Enumerates the alpha types of images. **System capability**: SystemCapability.Multimedia.Image @@ -1005,7 +1351,7 @@ Enumerates alpha types. ## ScaleMode9+ -Enumerates scale modes. +Enumerates the scale modes of images. **System capability**: SystemCapability.Multimedia.Image @@ -1016,19 +1362,21 @@ Enumerates scale modes. ## InitializationOptions8+ +Defines pixel map initialization options. + **System capability**: SystemCapability.Multimedia.Image -| Name | Type | Readable| Writable| Description | -| ----------- | ---------------------------------- | ---- | ---- | -------------- | -| alphaType9+ | [AlphaType](#alphatype9) | Yes | Yes | Alpha type. | -| editable | boolean | Yes | Yes | Whether the image is editable. | -| pixelFormat | [PixelMapFormat](#pixelmapformat7) | Yes | Yes | Pixel map format. | -| scaleMode9+ | [ScaleMode](#scalemode9) | Yes | Yes | Scale mode. | -| size | [Size](#size) | Yes | Yes | Image size.| +| Name | Type | Readable| Writable| Description | +| ---------------------- | ---------------------------------- | ---- | ---- | -------------- | +| alphaType9+ | [AlphaType](#alphatype9) | Yes | Yes | Alpha type. | +| editable | boolean | Yes | Yes | Whether the image is editable. | +| pixelFormat | [PixelMapFormat](#pixelmapformat7) | Yes | Yes | Pixel map format. | +| scaleMode9+ | [ScaleMode](#scalemode9) | Yes | Yes | Scale mode. | +| size | [Size](#size) | Yes | Yes | Image size.| ## DecodingOptions7+ -Describes the decoding options. +Defines image decoding options. **System capability**: SystemCapability.Multimedia.Image @@ -1056,7 +1404,7 @@ Describes region information. ## PackingOption -Describes the option for image packing. +Defines the option for image packing. **System capability**: SystemCapability.Multimedia.Image @@ -1092,3 +1440,40 @@ Describes the exchangeable image file format (Exif) information of an image. | GPS_LONGITUDE | "GPSLongitude" | Image longitude. | | GPS_LATITUDE_REF | "GPSLatitudeRef" | Latitude reference, for example, N or S.| | GPS_LONGITUDE_REF | "GPSLongitudeRef" | Longitude reference, for example, W or E.| + +## ImageFormat9+ + +Enumerates the image formats. + +**System capability**: SystemCapability.Multimedia.Image.Core + +| Name | Default Value| Description | +| ------------ | ------ | -------------------- | +| YCBCR_422_SP | 1000 | YCBCR422 semi-planar format.| +| JPEG | 2000 | JPEG encoding format. | + +## ComponentType9+ + +Enumerates the color component types of images. + +**System capability**: SystemCapability.Multimedia.Image.ImageReceiver + +| Name | Default Value| Description | +| ----- | ------ | ----------- | +| YUV_Y | 1 | Luminance component. | +| YUV_U | 2 | Chrominance component. | +| YUV_V | 3 | Chrominance component. | +| JPEG | 4 | JPEG type.| + +## Component9+ + +Describes the color components of an image. + +**System capability**: SystemCapability.Multimedia.Image.Core + +| Name | Type | Readable| Writable| Description | +| ------------- | -------------------------------- | ---- | ---- | ------------ | +| componentType | [ComponentType](#componenttype9) | Yes | No | Color component type. | +| rowStride | number | Yes | No | Row stride. | +| pixelStride | number | Yes | No | Pixel stride. | +| byteBuffer | ArrayBuffer | Yes | No | Component buffer.| diff --git a/en/application-dev/reference/apis/js-apis-medialibrary.md b/en/application-dev/reference/apis/js-apis-medialibrary.md index 6b1b11f9e17627eea877edf5b34b25551f25ce24..46ad60a5fe4baee84f673dee354d688e1be4b2a2 100644 --- a/en/application-dev/reference/apis/js-apis-medialibrary.md +++ b/en/application-dev/reference/apis/js-apis-medialibrary.md @@ -28,7 +28,13 @@ Obtains a **MediaLibrary** instance, which is used to access and modify personal | ----------------------------- | :---- | | [MediaLibrary](#medialibrary) | **MediaLibrary** instance.| -**Example** +**Example (from API version 9)** + +``` +var media = mediaLibrary.getMediaLibrary(this.context); +``` + +**Example (API version 8)** ``` import featureAbility from '@ohos.ability.featureAbility'; @@ -246,7 +252,7 @@ Creates a media asset. This API uses a promise to return the result. ``` async function example() { - // Create an image file in promise mode + // Create an image file in promise mode. let mediaType = mediaLibrary.MediaType.IMAGE; let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; const path = await media.getPublicDirectory(DIR_IMAGE); @@ -437,13 +443,13 @@ var media = mediaLibrary.getMediaLibrary(context); media.release() ``` -### storeMediaAsset +### storeMediaAsset(deprecated) storeMediaAsset(option: MediaAssetOption, callback: AsyncCallback<string>): void Stores a media asset. This API uses an asynchronous callback to return the URI that stores the media asset. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -467,19 +473,19 @@ mediaLibrary.getMediaLibrary().storeMediaAsset(option, (err, value) => { console.log("An error occurred when storing the media asset."); return; } - console.log("Media asset stored. "); + console.log("Media asset stored."); // Obtain the URI that stores the media asset. }); ``` -### storeMediaAsset +### storeMediaAsset(deprecated) storeMediaAsset(option: MediaAssetOption): Promise<string> Stores a media asset. This API uses a promise to return the URI that stores the media asset. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -512,13 +518,13 @@ mediaLibrary.getMediaLibrary().storeMediaAsset(option).then((value) => { ``` -### startImagePreview +### startImagePreview(deprecated) startImagePreview(images: Array<string>, index: number, callback: AsyncCallback<void>): void Starts image preview, with the first image to preview specified. This API can be used to preview local images whose URIs start with **dataability://** or online images whose URIs start with **https://**. It uses an asynchronous callback to return the execution result. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -526,7 +532,7 @@ This API is defined but not implemented in OpenHarmony 3.1 Release. It will be a | Name | Type | Mandatory | Description | | -------- | ------------------------- | ---- | ---------------------------------------- | -| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **https://** or **dataability://**.| +| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **dataability://** or **https://**.| | index | number | Yes | Index of the first image to preview. | | callback | AsyncCallback<void> | Yes | Callback used to return the image preview result. If the preview fails, an error message is returned. | @@ -537,7 +543,7 @@ let images = [ "dataability:///media/xxxx/2", "dataability:///media/xxxx/3" ]; -/* Online image usage mode +/* Preview online images. let images = [ "https://media.xxxx.com/image1.jpg", "https://media.xxxx.com/image2.jpg" @@ -554,13 +560,13 @@ mediaLibrary.getMediaLibrary().startImagePreview(images, index, (err) => { ``` -### startImagePreview +### startImagePreview(deprecated) startImagePreview(images: Array<string>, callback: AsyncCallback<void>): void Starts image preview. This API can be used to preview local images whose URIs start with **dataability://** or online images whose URIs start with **https://**. It uses an asynchronous callback to return the execution result. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -578,7 +584,7 @@ let images = [ "dataability:///media/xxxx/2", "dataability:///media/xxxx/3" ]; -/* Online image usage mode +/* Preview online images. let images = [ "https://media.xxxx.com/image1.jpg", "https://media.xxxx.com/image2.jpg" @@ -594,13 +600,13 @@ mediaLibrary.getMediaLibrary().startImagePreview(images, (err) => { ``` -### startImagePreview +### startImagePreview(deprecated) startImagePreview(images: Array<string>, index?: number): Promise<void> Starts image preview, with the first image to preview specified. This API can be used to preview local images whose URIs start with dataability:// or online images whose URIs start with https://. It uses a promise to return the execution result. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -608,7 +614,7 @@ This API is defined but not implemented in OpenHarmony 3.1 Release. It will be a | Name | Type | Mandatory | Description | | ------ | ------------------- | ---- | ---------------------------------------- | -| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **https://** or **dataability://**.| +| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **dataability://** or **https://**.| | index | number | No | Index of the first image to preview. If this parameter is not specified, the default value **0** is used. | **Return value** @@ -624,7 +630,7 @@ let images = [ "dataability:///media/xxxx/2", "dataability:///media/xxxx/3" ]; -/* Online image usage mode +/* Preview online images. let images = [ "https://media.xxxx.com/image1.jpg", "https://media.xxxx.com/image2.jpg" @@ -639,13 +645,13 @@ mediaLibrary.getMediaLibrary().startImagePreview(images, index).then(() => { ``` -### startMediaSelect +### startMediaSelect(deprecated) startMediaSelect(option: MediaSelectOption, callback: AsyncCallback<Array<string>>): void Starts media selection. This API uses an asynchronous callback to return the list of URIs that store the selected media assets. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -674,13 +680,13 @@ mediaLibrary.getMediaLibrary().startMediaSelect(option, (err, value) => { ``` -### startMediaSelect +### startMediaSelect(deprecated) startMediaSelect(option: MediaSelectOption): Promise<Array<string>> Starts media selection. This API uses a promise to return the list of URIs that store the selected media assets. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -723,7 +729,7 @@ Provides APIs for encapsulating file asset attributes. | Name | Type | Readable| Writable| Description | | ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ | | id | number | Yes | No | File asset ID. | -| uri | string | Yes | No | File asset URI, for example, dataability:///media/image/2. | +| uri | string | Yes | No | File asset URI, for example, **dataability:///media/image/2**. | | mimeType | string | Yes | No | Extended file attributes. | | mediaType8+ | [MediaType](#mediatype8) | Yes | No | Media type. | | displayName | string | Yes | Yes | Display file name, including the file name extension. | @@ -821,7 +827,7 @@ async function example() { commitModify(callback: AsyncCallback<void>): void -Commits the modification of this file asset to the database. This API uses an asynchronous callback to return the result. +Commits the modification in this file asset to the database. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA @@ -857,7 +863,7 @@ async function example() { commitModify(): Promise<void> -Commits the modification of this file asset to the database. This API uses a promise to return the result. +Commits the modification in this file asset to the database. This API uses a promise to return the result. **Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA @@ -893,6 +899,8 @@ open(mode: string, callback: AsyncCallback<number>): void Opens this file asset. This API uses an asynchronous callback to return the result. +Note: Currently, the write operations are mutually exclusive. After the write operation is complete, you must call **close** to release the resource. + **Required permissions**: ohos.permission.READ_MEDIA (when **mode** is set to **r**) and ohos.permission.WRITE_MEDIA (when **mode** is set to **w**) **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -901,7 +909,7 @@ Opens this file asset. This API uses an asynchronous callback to return the resu | Name | Type | Mandatory | Description | | -------- | --------------------------- | ---- | ----------------------------------- | -| mode | string | Yes | Mode of opening the file, for example, **r** (read-only), **w** (write-only), and **rw** (read-write).| +| mode | string | Yes | Mode of opening the file, for example, **'r'** (read-only), **'w'** (write-only), and **'rw'** (read-write).| | callback | AsyncCallback<number> | Yes | Callback used to return the file handle. | **Example** @@ -928,6 +936,8 @@ open(mode: string): Promise<number> Opens this file asset. This API uses a promise to return the result. +Note: Currently, the write operations are mutually exclusive. After the write operation is complete, you must call **close** to release the resource. + **Required permissions**: ohos.permission.READ_MEDIA (when **mode** is set to **r**) and ohos.permission.WRITE_MEDIA (when **mode** is set to **w**) **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -1009,7 +1019,7 @@ close(fd: number): Promise<void> Closes this file asset. This API uses a promise to return the result. -**Required permissions**: ohos.permission.READ_MEDIA (when **mode** is set to **r**) and ohos.permission.WRITE_MEDIA (when **mode** is set to **w**) +**Required permissions**: ohos.permission.READ_MEDIA (when **mode** is set to **'r'**) and ohos.permission.WRITE_MEDIA (when **mode** is set to **'w'**) **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -1531,7 +1541,7 @@ Checks whether the cursor is in the last row of the result set. | Type | Description | | ------- | ---------------------------------- | -| boolean | Returns **true** if the cursor is in the last row of the result set; returns *false** otherwise.| +| boolean | Returns **true** if the cursor is in the last row of the result set; returns *false* otherwise.| **Example** @@ -1566,7 +1576,7 @@ async function example() { close(): void -Releases and invalidates this **FetchFileResult** instance. Other APIs cannot be invoked after the instance is released. +Releases and invalidates this **FetchFileResult** instance. Other APIs in this instance cannot be invoked after it is released. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core @@ -1965,7 +1975,7 @@ Provides APIs to implement a physical album. commitModify(callback: AsyncCallback<void>): void -Commits the modification of the album attributes to the database. This API uses an asynchronous callback to return the result. +Commits the modification in the album attributes to the database. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA @@ -2002,7 +2012,7 @@ async function example() { commitModify(): Promise<void> -Commits the modification of the album attributes to the database. This API uses a promise to return the result. +Commits the modification in the album attributes to the database. This API uses a promise to return the result. **Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA @@ -2204,7 +2214,7 @@ Describes options for fetching media files. | ----------------------- | ------------------- | ---- | ---- | ---- | ------------------------------------------------------------ | | selections | string | Yes | Yes | Yes | Conditions for fetching files. The enumerated values in [FileKey](#filekey8) are used as the column names of the conditions. Example:
selections: mediaLibrary.FileKey.MEDIA_TYPE + '= ? OR' +mediaLibrary.FileKey.MEDIA_TYPE + '= ?',| | selectionArgs | Array<string> | Yes | Yes | Yes | Value of the condition, which corresponds to the value of the condition column in **selections**.
Example:
selectionArgs: [mediaLibrary.MediaType.IMAGE.toString(), mediaLibrary.MediaType.VIDEO.toString()], | -| order8+ | string | Yes | Yes | No | Sorting mode of the search results, which can be ascending or descending. The enumerated values in [FileKey](#filekey8) are used as the columns for sorting the search results. Example:
Ascending: order: mediaLibrary.FileKey.DATE_ADDED + " AESC"
Descending: order: mediaLibrary.FileKey.DATE_ADDED + " DESC"| +| order | string | Yes | Yes | No | Sorting mode of the search results, which can be ascending or descending. The enumerated values in [FileKey](#filekey8) are used as the columns for sorting the search results. Example:
Ascending: order: mediaLibrary.FileKey.DATE_ADDED + " AESC"
Descending: order: mediaLibrary.FileKey.DATE_ADDED + " DESC"| | uri8+ | string | Yes | Yes | No | File URI. | | networkId8+ | string | Yes | Yes | No | Network ID of the registered device. | | extendArgs8+ | string | Yes | Yes | No | Extended parameters for fetching the files. Currently, no extended parameters are available. | @@ -2218,30 +2228,30 @@ Describes the image size. | width | number | Yes | Yes | Image width, in pixels.| | height | number | Yes | Yes | Image height, in pixels.| -## MediaAssetOption +## MediaAssetOption(deprecated) Implements the media asset option. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core -| Name | Type | Mandatory | Description | -| ------------ | ------ | ---- | ---------------------------------------- | -| src | string | Yes | Absolute path of the local file of the application. | -| mimeType | string | Yes | Multipurpose Internet Mail Extensions (MIME) type of the media.
The value can be 'image/\*', 'video/\*', 'audio/\*' or 'file\*'.| -| relativePath | string | No | Custom path for storing media assets, for example, 'Pictures/'. If this parameter is unspecified, media assets are stored in the default path.
Default path of images: 'Pictures/'
Default path of videos: 'Videos/'
Default path of audios: 'Audios/'
Default path of files: 'Documents/'| +| Name | Type | Mandatory| Description | +| ------------ | ------ | ---- | ------------------------------------------------------------ | +| src | string | Yes | Application sandbox oath of the local file. | +| mimeType | string | Yes | Multipurpose Internet Mail Extensions (MIME) type of the media.
The value can be 'image/\*', 'video/\*', 'audio/\*' or 'file\*'.| +| relativePath | string | No | Custom path for storing media assets, for example, 'Pictures/'. If this parameter is unspecified, media assets are stored in the default path.
Default path of images: 'Pictures/'
Default path of videos: 'Videos/'
Default path of audios: 'Audios/'
Default path of files: 'Documents/'| -## MediaSelectOption +## MediaSelectOption(deprecated) Describes media selection option. -This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. +> **NOTE**
This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core | Name | Type | Mandatory | Description | | ----- | ------ | ---- | -------------------- | | type | string | Yes | Media type, which can be **image**, **media**, or **video**. Currently, only **media** is supported.| -| count | number | Yes | Number of media assets selected. If **count** is set to **1**, one media asset can be selected. If **count** is greater than **1**, multiple media assets can be selected. | +| count | number | Yes | Number of media assets selected. The value starts from 1, which indicates that one media asset can be selected. |