diff --git a/en/application-dev/media/audio-management.md b/en/application-dev/media/audio-management.md index 0f4dc93fa334eced5b30cf1d005f5e210223e271..db344ecdd7e78f7fa42775636732cf55543090ea 100644 --- a/en/application-dev/media/audio-management.md +++ b/en/application-dev/media/audio-management.md @@ -50,6 +50,11 @@ You use audio management APIs to set and obtain volume, and get information abou

Enumerates device types.

+

AudioScene

+ +

Enumerates audio scenes.

+ + @@ -74,42 +79,87 @@ You use audio management APIs to set and obtain volume, and get information abou

getVolume(audioType: AudioVolumeType, callback: AsyncCallback<number>): void

-

Obtains the volume of a stream asynchronously and uses a callback to return the execution result.

+

Obtains the volume of a stream asynchronously and uses a callback to return the result.

getVolume(audioType: AudioVolumeType): Promise<number>

-

Obtains the volume of a stream asynchronously and uses a Promise to return the execution result.

+

Obtains the volume of a stream asynchronously and uses a Promise to return the result.

getMinVolume(audioType: AudioVolumeType, callback: AsyncCallback<number>): void

-

Obtains the minimum volume of a stream asynchronously and uses a callback to return the execution result.

+

Obtains the minimum volume of a stream asynchronously and uses a callback to return the result.

getMinVolume(audioType: AudioVolumeType): Promise<number>

-

Obtains the minimum volume of a stream asynchronously and uses a Promise to return the execution result.

+

Obtains the minimum volume of a stream asynchronously and uses a Promise to return the result.

getMaxVolume(audioType: AudioVolumeType, callback: AsyncCallback<number>): void

-

Obtains the maximum volume of a stream asynchronously and uses a callback to return the execution result.

+

Obtains the maximum volume of a stream asynchronously and uses a callback to return the result.

getMaxVolume(audioType: AudioVolumeType): Promise<number>

-

Obtains the maximum volume of a stream asynchronously and uses a Promise to return the execution result.

+

Obtains the maximum volume of a stream asynchronously and uses a Promise to return the result.

getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void

-

Obtains the device list asynchronously and uses a callback to return the execution result.

+

Obtains the device list asynchronously and uses a callback to return the result.

getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors>

-

Obtains the device list asynchronously and uses a Promise to return the execution result.

+

Obtains the device list asynchronously and uses a Promise to return the result.

+ + +

setDeviceActive(deviceType: ActiveDeviceType, active: boolean, callback: AsyncCallback<void>): void

+ +

Activates the device asynchronously and uses a callback to return the execution result.

+ + +

setDeviceActive(deviceType: ActiveDeviceType, active: boolean): Promise<void>

+ +

Activates the device asynchronously and uses a Promise to return the execution result.

+ + +

isDeviceActive(deviceType: ActiveDeviceType, callback: AsyncCallback<boolean>): void

+ +

Checks whether a device is active asynchronously and uses a callback to return the result.

+ + +

isDeviceActive(deviceType: ActiveDeviceType): Promise<boolean>

+ +

Checks whether a device is active asynchronously and uses a Promise to return the result.

+ + +

on(type: 'deviceChange', callback: AsyncCallback<DeviceChangeAction>): void

+ +

Subscribes to device change events. Registered clients will receieve the callback when a device is connected/disconnected.

+ + +

setAudioScene(scene: AudioScene, callback: AsyncCallback<void>): void

+ +

Sets the audio scene mode asynchronously and uses a callback to return the execution result.

+ + +

setAudioScene(scene: AudioScene): Promise<void>

+ +

Sets the audio scene mode asynchronously and uses a Promise to return the execution result.

+ + +

getAudioScene(callback: AsyncCallback<AudioScene>): void

+ +

Obtains the audio scene mode asynchronously and uses a callback to return the result.

+ + +

getAudioScene(): Promise<AudioScene>

+ +

Obtains the audio scene mode asynchronously and uses a Promise to return the result.

@@ -261,6 +311,18 @@ You use audio management APIs to set and obtain volume, and get information abou +**Table 8** AudioScene enums + +Enumerates audio scenes. + +| Name | Description | +| :----------------------------- | :---------------------------- | +| AUDIO_SCENE_DEFAULT = 0 | Default audio scene.
| +| AUDIO_SCENE_RINGING = 1 | Ringing audio scene.
| +| AUDIO_SCENE_PHONE_CALL = 2 | Phone call audio scene.
| +| AUDIO_SCENE_VOICE_CHAT = 3 | Voice chat audio scene.
| + + ## Development Procedure 1. Obtain an audio manager. @@ -269,7 +331,7 @@ You use audio management APIs to set and obtain volume, and get information abou const audioManager = audio.getAudioManager(); ``` -2. Set the audio stream volume. +2. Obtain the audio stream volume. ``` audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err, value) => { @@ -280,3 +342,53 @@ You use audio management APIs to set and obtain volume, and get information abou console.log(`Media getVolume ${value}`); }); ``` + +## Usage + +**setAudioScene** + +**Example** + +Here's an example of how to use setAudioScene to change the audio strategy for the phone call scene. + +1. Obtain an audio manager. + + ``` + const audioManager = audio.getAudioManager(); + ``` + +2. Change the audio scene to phone call. + + ``` + audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err) => { + if (err) { + console.error('Failed to set the audio scene mode.​ ${err.message}'); + return; + } + console.log('Audio scene mode setting is successful.'); + }); + ``` + +**getAudioScene** + +**Example** + +Here's an example of how to use getAudioScene to obtain the current audio scene. + +1. Obtain an audio manager. + + ``` + const audioManager = audio.getAudioManager(); + ``` + +2. Obtain the current audio scene. + + ``` + audioManager.getAudioScene((err, value) => { + if (err) { + console.error('Failed to obtain the audio scene mode.​ ${err.message}'); + return; + } + console.log('Audio scene mode ${value)'); + }) + ``` diff --git a/en/application-dev/reference/apis/js-apis-audio.md b/en/application-dev/reference/apis/js-apis-audio.md index 85d2dc6b01ebe7dc2dc97e3965985ae1a61efb52..d67f15fe822237a159103eb93b7f3aa8b14aad08 100644 --- a/en/application-dev/reference/apis/js-apis-audio.md +++ b/en/application-dev/reference/apis/js-apis-audio.md @@ -282,6 +282,13 @@ Enumerates audio device types.

Microphone.
System capabilities: SystemCapability.Multimedia.Audio.Device

+

USB_HEADSET

+ +

22

+ +

USB Type-C Headset.
System capabilities: SystemCapability.Multimedia.Audio.Device

+ + @@ -545,6 +552,61 @@ Describes ringtone options. | loop | boolean | Yes | Loop value. | +## DeviceChangeAction +Describes the device change type and device information. + +**System capabilities**: SystemCapability.Multimedia.Audio.Device + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------------------ | :--------------------- | :-------- | :------------------ | +| type | DeviceChangeType | Yes | Device change type. | +| deviceDescriptors | AudioDeviceDescriptors | Yes | Device information. | + + +## DeviceChangeType +Enumerates device change types. + +| Name | Default Value | Description | +| :--------------------- | :------------ | :---------------------------------------------------------------------------------------- | +| CONNECT | 0 | Device connection.
System capabilities: SystemCapability.Multimedia.Audio.Device | +| DISCONNECT | 1 | Device disconnection.
System capabilities: SystemCapability.Multimedia.Audio.Device | + + +## AudioCapturerInfo8+ +Describes audio capturer information. + +**System capabilities**: SystemCapability.Multimedia.Audio.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| :---------------| :----------------| :-------- | :-------------------- | +| source | SourceType | Yes | Audio source type. | +| capturerFlags | number | Yes | Audio capturer flags. | + + +## SourceType8+ +Enumerates source types. + +| Name | Default Value | Description | +| :--------------------- | :------------ | :------------------------------------------------------------------------------------- | +| SOURCE_TYPE_INVALID | -1 | Invalid source type.
System capabilities: SystemCapability.Multimedia.Audio.Core | +| SOURCE_TYPE_MIC | 0 | Mic source type.
System capabilities: SystemCapability.Multimedia.Audio.Core | + + +## AudioScene8+ +Enumerates audio scenes. + +| Name | Default Value | Description | +| :--------------------- | :------------ | :------------------------------------------------------------------------------------------------- | +| AUDIO_SCENE_DEFAULT | 0 | Default audio scene.
System capabilities: SystemCapability.Multimedia.Audio.Communication | +| AUDIO_SCENE_RINGING | 1 | Ringing audio scene.
System capabilities: SystemCapability.Multimedia.Audio.Communication | +| AUDIO_SCENE_PHONE_CALL | 2 | Phone call audio scene.
System capabilities: SystemCapability.Multimedia.Audio.Communication | +| AUDIO_SCENE_VOICE_CHAT | 3 | Voice chat audio scene.
System capabilities: SystemCapability.Multimedia.Audio.Communication | + + # AudioManager Implements audio volume and audio device management. @@ -2506,6 +2568,163 @@ audioManager.on('ringerModeChange', (ringerMode) => { }) ``` +## audioManager.on + +on(type: 'deviceChange', callback: Callback): void8+ + +Subscribes to device change events. When a device is connected/disconnected, registered clients will receive the callback. + +**System capabilities**: SystemCapability.Multimedia.Audio.Device + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :---------------------------- | :---------| :------------------------------------------------- | +| type | string | Yes | Type of the event to subscribe to. | +| callback | Callback | Yes | Callback used to obtain the device update details. | + +**Return value** + +None + +**Example** + +``` +audioManager.on('deviceChange', (deviceChanged) => { + console.info("device change type : " + deviceChanged.type); + console.info("device descriptor size : " + deviceChanged.deviceDescriptors.length); + console.info("device change descriptor : " + deviceChanged.deviceDescriptors[0].deviceRole); + console.info("device change descriptor : " + deviceChanged.deviceDescriptors[0].deviceType); +}) +``` + +## audioManager.setAudioScene + +setAudioScene\(scene: AudioScene, callback: AsyncCallback\): void8+ + +Sets the audio scene mode to change audio strategies. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Communication + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :------------------------------------ | :-------- | :---------------------------------- | +| scene | AudioScene | Yes | Audio scene mode. | +| callback | AsyncCallback | Yes | Callback used to return the result. | + + +**Return value** + +None + +**Example** + +``` +audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err) => { + if (err) { + console.error('Failed to set the audio scene mode.​ ${err.message}'); + return; + } + console.log('Callback invoked to indicate a successful setting of the audio scene mode.'); +}) +``` + + +## audioManager.setAudioScene + +setAudioScene\(scene: AudioScene\): Promise8+ + +Sets the audio scene mode to change audio strategies. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Communication + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :-------------------------------------- | :-------- | :---------------- | +| scene | AudioScene | Yes | Audio scene mode. | + + +**Return value** + +| Type | Description | +| :------------- | :---------------------------------- | +| Promise | Promise used to return the result. | + + +**Example** + +``` +audioManager.setAudioScene(audio.AudioSceneMode.AUDIO_SCENE_PHONE_CALL).then(() => { + console.log('Promise returned to indicate a successful setting of the audio scene mode.'); +}).catch ((err) => { + console.log('Failed to set the audio scene mode'); +}); +``` + + +## audioManager.getAudioScene + +getAudioScene\(callback: AsyncCallback\): void8+ + +Obtains the audio scene mode. This method uses an asynchronous callback to return the query result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Communication + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :-------------------------------------------------- | :-------- | :-------------------------------------------- | +| callback | AsyncCallback<AudioScene> | Yes | Callback used to return the audio scene mode. | + + +**Return value** + +None + +**Example** + +``` +audioManager.getAudioScene((err, value) => { + if (err) { + console.error('Failed to obtain the audio scene mode.​ ${err.message}'); + return; + } + console.log('Callback invoked to indicate that the audio scene mode is obtained.' + value); +}) +``` + + +## audioManager.getAudioScene + +getAudioScene\(\): Promise8+ + +Obtains the audio scene mode. This method uses a promise to return the query result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Communication + +**Parameters** + +None + +**Return value** + +| Type | Description | +| :-------------------------------------------- | :------------------------------------------- | +| Promise<AudioScene> | Promise used to return the audio scene mode. | + + +**Example** + +``` +audioManager.getAudioScene().then((value) => { + console.log('Promise returned to indicate that the audio scene mode is obtained.' + value); +}).catch ((err) => { + console.log('Failed to obtain the audio scene mode'); +}) +``` + # AudioDeviceDescriptor Describes an audio device. @@ -2591,7 +2810,7 @@ Defines the current render state. getRendererInfo(callback: AsyncCallback): void8+ -Gets the renderer information provided while creating a renderer instance. This method uses an asynchronous callback to return the result. +Obtains the renderer information provided while creating a renderer instance. This method uses an asynchronous callback to return the result. **System capabilities**: SystemCapability.Multimedia.Audio.Renderer @@ -2619,9 +2838,9 @@ audioRenderer.getRendererInfo((err, rendererInfo)=>{ ## audioRenderer.getRendererInfo -getParams(): Promise8+ +getRendererInfo(): Promise8+ -Gets the renderer information provided while creating a renderer instance. This method uses a promise to return the result. +Obtains the renderer information provided while creating a renderer instance. This method uses a promise to return the result. **System capabilities**: SystemCapability.Multimedia.Audio.Renderer @@ -2649,7 +2868,7 @@ console.log('Renderer flags:' + rendererInfo.rendererFlags); getStreamInfo(callback: AsyncCallback): void8+ -Gets the renderer stream information. This method uses an asynchronous callback to return the result. +Obtains the renderer stream information. This method uses an asynchronous callback to return the result. **System capabilities**: SystemCapability.Multimedia.Audio.Renderer @@ -2669,9 +2888,9 @@ None audioRenderer.getStreamInfo((err, streamInfo)=>{ console.log('Renderer GetStreamInfo:'); console.log('Renderer sampling rate:' + streamInfo.samplingRate); - console.log('Renderer channel:' + streamInfo.AudioChannel); - console.log('Renderer format:' + streamInfo.AudioSampleFormat); - console.log('Renderer encoding type:' + streamInfo.AudioEncodingType); + console.log('Renderer channel:' + streamInfo.channels); + console.log('Renderer format:' + streamInfo.sampleFormat); + console.log('Renderer encoding type:' + streamInfo.encodingType); }) ``` @@ -2679,7 +2898,7 @@ audioRenderer.getStreamInfo((err, streamInfo)=>{ getStreamInfo(): Promise8+ -Gets the renderer stream information. This method uses a promise to return the result. +Obtains the renderer stream information. This method uses a promise to return the result. **System capabilities**: SystemCapability.Multimedia.Audio.Renderer @@ -2699,9 +2918,9 @@ None let streamInfo = await audioRenderer.getStreamInfo(); console.log('Renderer GetStreamInfo:'); console.log('Renderer sampling rate:' + streamInfo.samplingRate); -console.log('Renderer channel:' + streamInfo.AudioChannel); -console.log('Renderer format:' + streamInfo.AudioSampleFormat); -console.log('Renderer encoding type:' + streamInfo.AudioEncodingType); +console.log('Renderer channel:' + streamInfo.channels); +console.log('Renderer format:' + streamInfo.sampleFormat); +console.log('Renderer encoding type:' + streamInfo.encodingType); ``` ## audioRenderer.start @@ -3067,7 +3286,7 @@ if (writtenbytes < 0) { getAudioTime(callback: AsyncCallback): void8+ -Obtains the timestamp. This method uses an asynchronous callback to return the result. +Obtains the timestamp in Unix epoch time (starts from January 1, 1970), in nanoseconds. This method uses an asynchronous callback to return the result. **System capabilities**: SystemCapability.Multimedia.Audio.Renderer @@ -3095,7 +3314,7 @@ audioRenderer.getAudioTime((err, timestamp)=>{ getAudioTime(): Promise8+ -Obtains the timestamp. This method uses a promise to return the result. +Obtains the timestamp in Unix epoch time (starts from January 1, 1970), in nanoseconds. This method uses a promise to return the result. **System capabilities**: SystemCapability.Multimedia.Audio.Renderer @@ -3121,7 +3340,7 @@ console.log('Current timestamp: ' + timestamp); getBufferSize(callback: AsyncCallback): void8+ -Obtains a reasonable minimum buffer size for rendering. This method uses an asynchronous callback to return the result. +Obtains a reasonable minimum buffer size in bytes for rendering. This method uses an asynchronous callback to return the result. **System capabilities**: SystemCapability.Multimedia.Audio.Renderer @@ -3153,7 +3372,7 @@ ss.readSync(buf); getBufferSize(): Promise8+ -Obtains a reasonable minimum buffer size for rendering. This method uses a promise to return the result. +Obtains a reasonable minimum buffer size in bytes for rendering. This method uses a promise to return the result. **System capabilities**: SystemCapability.Multimedia.Audio.Renderer @@ -3186,10 +3405,10 @@ Sets the render rate. This method uses an asynchronous callback to return the re **Parameters** -| Name | Type | Mandatory | Description | -| :------- | :------------------- | :-------- | :------------------------------------ | -| rate | AudioRendererRate | Yes | Audio render rate. | -| callback | AsyncCallback | Yes | Callback used to return the result. | +| Name | Type | Mandatory | Description | +| :------- | :------------------- | :-------- | :---------------------------------- | +| rate | AudioRendererRate | Yes | Audio render rate. | +| callback | AsyncCallback | Yes | Callback used to return the result. | **Return value** @@ -3336,6 +3555,114 @@ audioRenderer.on('interrupt', (interruptEvent) => { ``` +## audioRenderer.on + +on(type: 'markReach', frame: number, callback: (position: number)): void8+ + +Subscribes to mark reached events. When the number of frames rendered reaches the value of the frame parameter, the callback is invoked. + +**System capabilities**: SystemCapability.Multimedia.Audio.Renderer + +**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 | Callback | Yes | Callback invoked when the event is triggered. | + +**Return value** + +None + +**Example** + +``` +audioRenderer.on('markReach', 1000, (position) => { + if (position == "1000") { + console.log('ON Triggered successfully'); + } +}); +``` + + +## audioRenderer.off + +off(type: 'markReach'): void8+ + +Unsubscribes from mark reached events. + +**System capabilities**: SystemCapability.Multimedia.Audio.Renderer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :------------------------ | :-------- | :----------------------------------------------- | +| type | string | Yes | Type of the renderer event to unsubscribe from. | + +**Return value** + +None + +**Example** + +``` +audioRenderer.off('markReach'); +``` + +## audioRenderer.on + +on(type: 'periodReach', frame: number, callback: (position: number)): void8+ + +Subscribes to period reached events. When the period of frame rendering reaches the value of frame parameter, the callback is invoked. + +**System capabilities**: SystemCapability.Multimedia.Audio.Renderer + +**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 | Callback | Yes | Callback invoked when the event is triggered. | + +**Return value** + +None + +**Example** + +``` +audioRenderer.on('periodReach', 1000, (position) => { + if (position == "1000") { + console.log('ON Triggered successfully'); + } +}); +``` + +## audioRenderer.off + +off(type: 'periodReach'): void8+ + +Unsubscribes from period reached events. + +**System capabilities**: SystemCapability.Multimedia.Audio.Renderer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :------------------------ | :-------- | :----------------------------------------------- | +| type | string | Yes | Type of the renderer event to unsubscribe from. | + +**Return value** + +None + +**Example** + +``` +audioRenderer.off('periodReach') +``` ## SystemSoundManager @@ -4148,4 +4475,631 @@ Describes an audio device. | Name | Description | | -------- | -------- | -| AudioDeviceDescriptors | Array of **AudioDeviceDescriptor** objects. It is read-only.
**System capabilities:** SystemCapability.Multimedia.Audio.Device | \ No newline at end of file +| AudioDeviceDescriptors | Array of **AudioDeviceDescriptor** objects. It is read-only.
**System capabilities:** SystemCapability.Multimedia.Audio.Device | +# AudioCapturer +Provides APIs for audio recording. + + +## audioCapturer.state + +readonly state: AudioState 8+ + +Defines the current capture state. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +| Name | Type | Readable | Writable | Description | +| :---- | :--------- | :------- | :------- | :------------------- | +| state | AudioState | Yes | No | Audio capture state. | + +**Example** + +``` +var state = audioCapturer.state; +``` + + +## audioCapturer.getCapturerInfo + +getCapturerInfo(callback: AsyncCallback): void8+ + +Obtains the capturer information provided while creating a capturer instance. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :--------------------------------- | :-------- | :------------------------------------------------ | +| callback | AsyncCallback | Yes | Callback used to return the capturer information. | +| | | | | + +**Return value** + +None + +**Example** + +``` +audioCapturer.getCapturerInfo((err, capturerInfo)=>{ + if (err) { + console.error('Failed to get capture info'); + } else { + console.log('Capturer getCapturerInfo:'); + console.log('Capturer source:' + capturerInfo.source); + console.log('Capturer flags:' + capturerInfo.capturerFlags); + } +}) +``` + + +## audioCapturer.getCapturerInfo + +getCapturerInfo(): Promise8+ + +Obtains the capturer information provided while creating a capturer instance. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +None + +**Return value** + +| Type | Description | +| :---------------------------- | :----------------------------------------------- | +| Promise | Promise used to return the capturer information. | + +**Example** + +``` +audioCapturer.getCapturerInfo().then((capturerInfo) => { + console.log('Capturer getCapturerInfo:'); + console.log('Capturer source:' + capturerInfo.source); + console.log('Capturer flags:' + capturerInfo.capturerFlags); +}).catch ((err) => { + console.log("Failed to get capturer info"); +}); +``` + +## audioCapturer.getStreamInfo + +getStreamInfo(callback: AsyncCallback): void8+ + +Obtains the capturer stream information. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :--------------------------------- | :-------- | :---------------------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the stream information. | +| | | | | + +**Return value** + +None + +**Example** + +``` +audioCapturer.start((err)=>{ + if (err) { + console.error('Failed to get stream info'); + } else { + console.log('Capturer GetStreamInfo:'); + console.log('Capturer sampling rate:' + streamInfo.samplingRate); + console.log('Capturer channel:' + streamInfo.channels); + console.log('Capturer format:' + streamInfo.sampleFormat); + console.log('Capturer encoding type:' + streamInfo.encodingType); + } +}) +``` + +## audioCapturer.getStreamInfo + +getStreamInfo(): Promise8+ + +Obtains the capturer stream information. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +None + +**Return value** + +| Type | Description | +| :---------------------------- | :----------------------------------------------- | +| Promise | Promise used to return the stream information. | + +**Example** + +``` +audioCapturer.getStreamInfo().then((streamInfo) => { + console.log('Capturer GetStreamInfo:'); + console.log('Capturer sampling rate:' + streamInfo.samplingRate); + console.log('Capturer channel:' + streamInfo.channels); + console.log('Capturer format:' + streamInfo.sampleFormat); + console.log('Capturer encoding type:' + streamInfo.encodingType); +}).catch ((err) => { + console.log("Failed to get stream info"); +}); +``` + +## audioCapturer.start + +start(callback: AsyncCallback): void8+ + +Starts capturing. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :---------------------- | :-------- | :-------------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the result. | +| | | | | + +**Return value** + +None + +**Example** + +``` +audioCapturer.start((err)=>{ + if (err) { + console.error('Capturer start failed.'); + } else { + console.info('Capturer start success.'); + } +}) +``` + + +## audioCapturer.start + +start(): Promise8+ + +Starts capturing. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +None + +**Return value** + +| Type | Description | +| :------------- | :--------------------------------- | +| Promise | Promise used to return the result. | + +**Example** + +``` +audioCapturer.start().then(() => { + console.log("capturer start success"); +}).catch ((err) => { + console.log("Failed to start capturer"); +}); +``` + +## audioCapturer.stop + +stop(callback: AsyncCallback): void8+ + +Stops capturing. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :---------------------- | :-------- | :------------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the result. | +| | | | | + +**Return value** + +None + +**Example** + +``` +audioCapturer.stop((err)=>{ + if (err) { + console.error('Capturer stop failed'); + } else { + console.log('Capturer stopped.'); + } +}) +``` + + +## audioCapturer.stop + +stop(): Promise8+ + +Stops capturing. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +None + +**Return value** + +| Type | Description | +| :------------- | :--------------------------------- | +| Promise | Promise used to return the result. | + +**Example** + +``` +audioCapturer.stop().then(() => { + console.log("capturer stop success"); +}).catch ((err) => { + console.log("Failed to stop capturer"); +}); +``` + + +## audioCapturer.release + +release(callback: AsyncCallback): void8+ + +Releases the capturer. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :---------------------- | :-------- | :------------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the result. | +| | | | | + +**Return value** + +None + +**Example** + +``` +audioCapturer.release((err)=>{ + if (err) { + console.error('capturer release failed'); + } else { + console.log('capturer released.'); + } +}) +``` + + +## audioCapturer.release + +release(): Promise8+ + +Releases the capturer. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +None + +**Return value** + +| Type | Description | +| :------------- | :--------------------------------- | +| Promise | Promise used to return the result. | + +**Example** + +``` +audioCapturer.release().then(() => { + console.log("capturer release success"); +}).catch ((err) => { + console.log("Failed to release capturer"); +}); +``` + + +## audioCapturer.read + +read(size: number, isBlockingRead: boolean, callback: AsyncCallback): void8+ + +Reads the buffer from the audio capturer. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**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. | + +**Return value** + +None + +**Example** + +``` +audioCapturer.read(bufferSize, true, async(err, buffer) => { + if (!err) { + console.log("Success in reading the buffer data"); + var number = fileio.writeSync(fd, buffer); + } +}; +``` + + +## audioCapturer.read + +read(size: number, isBlockingRead: boolean): Promise8+ + +Reads the buffer from the audio capturer. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------------- | :-------------------------- | :-------- | :-------------------------------------------- | +| size | number | Yes | Number of bytes to read. | +| isBlockingRead | boolean | Yes | Whether the read operation should be blocked. | + +**Return value** + +| Type | Description | +| :-------------------- | :----------------------------------------------------------------------------------------------- | +| Promise | Returns the buffer data read if the operation is successful; returns an error code otherwise. | + +**Example** + +``` +audioCapturer.read(size, true).then((buffer) => { + console.log("Success in reading the buffer data"); + var number = fileio.writeSync(fd, buffer); +}).catch ((err) => { + console.log("Failed to read data!"); +}); +``` + + +## audioCapturer.getAudioTime + +getAudioTime(callback: AsyncCallback): void8+ + +Obtains the timestamp in Unix epoch time (starts from January 1, 1970), in nanoseconds. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :--------------------- | :-------- | :------------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the timestamp. | +| | | | | + +**Return value** + +None + +**Example** + +``` +audioCapturer.getAudioTime((err, timestamp)=>{ + console.log('Current timestamp: ' + timestamp); +}) +``` + + +## audioCapturer.getAudioTime + +getAudioTime(): Promise8+ + +Obtains the timestamp in Unix epoch time (starts from January 1, 1970), in nanoseconds. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +None + +**Return value** + +| Type | Description | +| :--------------- | :------------------------------------ | +| Promise | Promise used to return the timestamp. | + +**Example** + +``` +audioCapturer.getAudioTime().then((audioTime) => { + console.log("Success in getting the audio time"); +}).catch ((err) => { + console.log("Failed to get the audio time"); +}); +``` + + +## audioCapturer.getBufferSize + +getBufferSize(callback: AsyncCallback): void8+ + +Obtains a reasonable minimum buffer size in bytes for capturing. This method uses an asynchronous callback to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :--------------------- | :-------- | :--------------------------------------- | +| callback | AsyncCallback | Yes | Callback used to return the buffer size. | +| | | | | + +**Return value** + +None + +**Example** + +``` +audioCapturer.getBufferSize((err, bufferSize)=>{ + if (!err) { + console.log('BufferSize : ' + bufferSize); + var buffer = await audioCapturer.read(bufferSize, true); + } +}); +``` + + +## audioCapturer.getBufferSize + +getBufferSize(): Promise8+ + +Obtains a reasonable minimum buffer size in bytes for capturing. This method uses a promise to return the result. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +None + +**Return value** + +| Type | Description | +| :--------------- | :-------------------------------------- | +| Promise | Promise used to return the buffer size. | + +**Example** + +``` +audioCapturer.getBufferSize().then((bufferSize) => { + console.log("Success in getting the buffer size"); + var buffer = await audioCapturer.read(bufferSize, true); +}).catch ((err) => { + console.log("Failed to get the buffer size"); +}); +``` + + +## audioCapturer.on + +on(type: 'markReach', frame: number, callback: (position: number)): void8+ + +Subscribes to mark reached events. When the number of frames captured reaches the value of the frame parameter, the callback is invoked. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**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 | Callback | Yes | Callback invoked when the event is triggered. | + +**Return value** + +None + +**Example** + +``` +audioCapturer.on('markReach', 1000, (position) => { + if (position == "1000") { + console.log('ON Triggered successfully'); + } +}); +``` + + +## audioCapturer.off + +off(type: 'markReach'): void8+ + +Unsubscribes from the mark reached events. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :------------------------ | :-------- | :---------------------------------------------- | +| type | string | Yes | Type of the capturer event to unsubscribe from. | + +**Return value** + +None + +**Example** + +``` +audioCapturer.off('markReach'); +``` + +## audioCapturer.on + +on(type: 'periodReach', frame: number, callback: (position: number)): void8+ + +Subscribes to period reached events. When the period of frame capturing reaches the value of frame parameter, the callback is invoked. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**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 | Callback | Yes | Callback invoked when the event is triggered. | + +**Return value** + +None + +**Example** + +``` +audioCapturer.on('periodReach', 1000, (position) => { + if (position == "1000") { + console.log('ON Triggered successfully'); + } +}); +``` + +## audioCapturer.off + +off(type: 'periodReach'): void8+ + +Unsubscribes from period reached events. + +**System capabilities**: SystemCapability.Multimedia.Audio.Capturer + +**Parameters** + +| Name | Type | Mandatory | Description | +| :------- | :------------------------ | :-------- | :---------------------------------------------- | +| type | string | Yes | Type of the capturer event to unsubscribe from. | + +**Return value** + +None + +**Example** + +``` +audioCapturer.off('periodReach') +```