Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 78f1f7a9 编写于 作者: W wusongqing
浏览文件
操作

updated docs 

Signed-off-by: Nwusongqing <wusongqing@huawei.com>
上级 be5bdb7e
显示空白变更内容
内联 并排
Showing with 636 addition and 286 deletion
en/application-dev/media/audio-playback.md
浏览文件 @ 78f1f7a9
......@@ -2,127 +2,178 @@
## When to Use
You use audio playback APIs to convert audio data into audible analog signals, play the audio signals using output devices, and manage playback tasks.
You can use audio playback APIs to convert audio data into audible analog signals, play the signals using output devices, and manage playback tasks.
**Figure 1** Playback status
![](figures/playback-status.png "playback-status")
## Available APIs
**Table 1** APIs for audio playback
| API| Description|
| -------- | -------- |
| media.createAudioPlayer() | Creates an **AudioPlayer** instance.|
| AudioPlayer | Provides audio playback features. For details, see the table below.|
**Table 2** AudioPlayer methods
| Method| Description|
| -------- | -------- |
| release() | Releases audio resources.|
| play() | Starts audio playback.|
| pause() | Pauses playback.|
| stop() | Stops playback.|
| reset()<sup>7+</sup> | Resets the audio source to be played.|
| setVolume(vol:&nbsp;number) | Sets playback volume.|
| seek(timeMs:&nbsp;number) | Changes the playback position.|
| src:string | Defines the URI of an audio file to play.|
| state:AudioState | Defines the playback state.|
| currentTime:number | Defines the current playback position.|
| duration:number | Defines the playback duration. The value **-1** is returned if the data source does not support playback position change, for example, in the real-time streaming media scenario.|
| loop:boolean | Defines whether to loop audio playback.|
| on('play',&nbsp;function&nbsp;callback) | Subscribes to the playback start event.|
| on('pause',&nbsp;function&nbsp;callback) | Subscribes to the playback pause event.|
| on('stop',&nbsp;function&nbsp;callback) | Subscribes to the playback stop event.|
| on('reset',&nbsp;function&nbsp;callback) | Subscribes to the playback reset event.|
| on('finish',function&nbsp;callback) | Subscribes to the playback end event.|
| on('error',&nbsp;function&nbsp;callback) | Subscribes to the playback error event.|
| on('dataload',&nbsp;function&nbsp;callback) | Subscribes to the data loading event.|
| on('volumeChange',&nbsp;function&nbsp;callback) | Subscribes to the volume change event.|
| on('timeUpdate',&nbsp;function&nbsp;callback) | Subscribes to the progress change event.|
1. Create an audio player.
```
import media from '@ohos.multimedia.media';
var player = media.createAudioPlayer();
```
2. Set the subscription events.
```
player.on('play', (err, action) => {
if (err) {
console.error('Error returned in the play() callback.');
return;
}
console.info('Current player duration: '+ player.duration);
console.info('Current player time: ' + player.currentTime);
console.info('Current player status: '+player.state);
console.info('Pause MP3');
player.pause();
});
player.on('pause', (err, action) => {
if (err) {
console.error('Error returned in the pause() callback.');
return;
}
console.info('Current player status: ' + player.state);
console.info('Current player time: ' + player.currentTime);
player.seek(30000); // Seek for 30 seconds.
![en-us_image_20220117](figures/en-us_image_20220117.jpg)
## How to Develop
For details about the APIs used for audio playback, see [js-apis-media.md](../reference/apis/js-apis-media.md).
### Full-Process Scenario
The full audio playback process includes creating an instance, setting the URI, playing audio, seeking to the playback position, setting the volume, pausing playback, obtaining track information, stopping playback, resetting resources, and releasing resources.
For details about the **src** media source input types supported by **AudioPlayer**, see the [src attributes](../reference/apis/js-apis-media.md#audioplayer_Attributes).
```js
function SetCallBack(audioPlayer) {
audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully.
console.info('audio set source success');
// The playback page is ready. You can click the Play button to start the playback.
});
player.on('stop', (err, action) => {
if (err) {
console.error('Error returned in the stop() callback.');
return;
}
console.info('stop callback invoked. State:' + player.state);
player.reset();
audioPlayer.on('play', () => { // Set the 'play' event callback.
console.info('audio play success');
// The Play button is changed to the pausable state.
});
player.on('dataLoad', (err, action) => {
if (err) {
console.error('Error returned in the dataLoad() callback.');
return;
}
console.info('dataLoad callback invoked. Current time: ' + player.currentTime);
console.info('Duration of the source:' + player.duration);
player.play();
audioPlayer.on('pause', () => { // Set the 'pause' event callback.
console.info('audio pause success');
// The Play button is changed to the playable state.
});
player.on('reset', (err, action) => {
if (err) {
console.error('Error returned in the reset() callback.');
audioPlayer.on('stop', () => { // Set the 'stop' event callback.
console.info('audio stop success');
// The playback stops, the playback progress bar returns to 0, and the Play button is changed to the playable state.
});
audioPlayer.on('reset', () => { // Set the 'reset' event callback.
console.info('audio reset success');
// You can reconfigure the src attribute to play another audio file.
});
audioPlayer.on('timeUpdate', (seekDoneTime) => {// Set the 'timeUpdate' event callback.
if (typeof(seekDoneTime) == 'undefined') {
console.info('audio seek fail');
return;
}
console.info('reset callback invoked.');
player.release();
console.info('audio seek success, and seek time is ' + seekDoneTime);
// The playback progress bar is updated to the seek position.
});
player.on('finish', (err, action) => {
if (err) {
console.error('Error returned in the finish() callback.');
return;
audioPlayer.on('volumeChange', () => { // Set the 'volumeChange' event callback.
console.info('audio volumeChange success');
// Display the updated volume.
});
audioPlayer.on('finish', () => { // Set the 'finish' event callback, which is triggered when the playback is complete.
console.info('audio play finish');
});
audioPlayer.on('error', (error) => { // Set the 'error' event callback.
console.info(`audio error called, errName is ${error.name}`);
console.info(`audio error called, errCode is ${error.code}`);
console.info(`audio error called, errMessage is ${error.message}`);
});
}
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('audio key is ' + item);
console.info('audio value is ' + property);
}
}
// 1. Create an audioPlayer instance.
let audioPlayer = media.createAudioPlayer();
SetCallBack(audioPlayer); // Set the event callbacks.
// 2. Set the URI of the audio file.
audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; // Set the src attribute and trigger the 'dataLoad' event callback.
// 3. Play the audio.
audioPlayer.play(); // The play() method can be invoked only after the 'dataLoad' event callback is complete. The 'play' event callback is triggered.
// 4. Seek to the playback position.
audioPlayer.seek(30000); // Trigger the 'timeUpdate' event callback, and seek to 30000 ms for playback.
// 5. Set the volume.
audioPlayer.setVolume(0.5); // Trigger the 'volumeChange' event callback.
// 6. Pause the playback.
audioPlayer.pause(); // Trigger the 'pause' event callback and pause the playback.
// 7. Obtain the track information.
audioPlayer.getTrackDescription((error, arrlist) => { // Obtain the audio track information in callback mode.
if (typeof (arrlist) != 'undefined') {
for (let i = 0; i < arrlist.length; i++) {
printfDescription(arrlist[i]);
}
console.info('finish callback invoked.');
});
player.on('timeUpdate', (seekTime, action) => {
console.info('Seek time: ' + seekTime);
console.info('Current player time: ' + player.currentTime);
var newTime = player.currentTime;
if(newTime == 30000) {
console.info('Seek succeeded. New time: ' + newTime);
} else {
console.error('Seek failed: ', + newTime);
console.log(`audio getTrackDescription fail, error:${error.message}`);
}
player.stop();
});
// 8. Stop playback.
audioPlayer.stop(); // Trigger the 'stop' event callback.
// 9. Reset the playback resources.
audioPlayer.reset(); // Trigger the 'reset' event callback, and reconfigure the src attribute to switch to the next song.
// 10. Release the resource.
audioPlayer.release(); // Release the AudioPlayer resource.
audioPlayer = undefined;
```
### Normal Playback Scenario
```js
function SetCallBack(audioPlayer) {
audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully.
console.info('audio set source success');
audioPlayer.play(); // Call the play() method to start the playback and trigger the 'play' event callback.
});
audioPlayer.on('play', () => { // Set the 'play' event callback.
console.info('audio play success');
});
audioPlayer.on('finish', () => { // Set the 'finish' event callback, which is triggered when the playback is complete.
console.info('audio play finish');
audioPlayer.release(); // Release the AudioPlayer instance.
audioPlayer = undefined;
});
}
let audioPlayer = media.createAudioPlayer(); // Create an AudioPlayer instance.
SetCallBack(audioPlayer); // Set the event callbacks.
/* Set the URI of the audio file selected by the user. */
audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; // Set the src attribute and trigger the 'dataLoad' event callback.
```
### Switching to the Next Song
```js
function SetCallBack(audioPlayer) {
audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully.
console.info('audio set source success');
audioPlayer.play(); // Call the play() method to start the playback and trigger the 'play' event callback.
});
audioPlayer.on('play', () => { // Set the 'play' event callback.
console.info('audio play success');
});
audioPlayer.on('finish', () => { // Set the 'finish' event callback, which is triggered when the playback is complete.
console.info('audio play finish');
audioPlayer.release(); // Release the AudioPlayer instance.
audioPlayer = undefined;
});
}
let audioPlayer = media.createAudioPlayer(); // Create an AudioPlayer instance.
SetCallBack(audioPlayer); // Set the event callbacks.
/* Set the URI of the audio file selected by the user. */
audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; // Set the src attribute and trigger the 'dataLoad' event callback.
/* Send the instruction to switch to the next song after a period of time. */
audioPlayer.reset();
audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/next.mp3';
```
### Looping a Song
```js
function SetCallBack(audioPlayer) {
audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully.
console.info('audio set source success');
audioPlayer.play(); // Call the play() method to start the playback and trigger the 'play' event callback.
});
audioPlayer.on('play', () => { // Set the 'play' event callback.
console.info('audio play success');
});
player.on('error', (err) => {
console.error('Player error: ${err.message}');
audioPlayer.on('finish', () => { // Set the 'finish' event callback, which is triggered when the playback is complete.
console.info('audio play finish');
audioPlayer.release(); // Release the AudioPlayer instance.
audioPlayer = undefined;
});
```
}
3. Start playback.
```
var audioSourceMp3 = 'file://test.mp3';
player.src = audioSourceMp3;
player.loop = true;
```
let audioPlayer = media.createAudioPlayer(); // Create an AudioPlayer instance.
SetCallBack(audioPlayer); // Set the event callbacks.
/* Set the URI of the audio file selected by the user. */
audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; // Set the src attribute and trigger the 'dataLoad' event callback.
audioPlayer.loop = true; // Set the loop playback attribute.
```
en/application-dev/reference/apis/js-apis-media.md
浏览文件 @ 78f1f7a9
# Audio Playback and Recording
# Media
The multimedia subsystem provides a set of simple and easy-to-use APIs for you to access the system and use media resources.
This subsystem offers various media services covering audio and video, which provide the following capabilities:
- Audio playback ([AudioPlayer](#audioplayer))
- Audio recording ([AudioRecorder](#audiorecorder))
The following capabilities will be provided in the future: video playback, video recording, data source audio/video playback, audio/video encoding and decoding, container encapsulation and decapsulation, and media capability query.
## Modules to Import
```
```js
import media from '@ohos.multimedia.media';
```
## Required Permissions
None
## media.createAudioPlayer
Creates an **AudioPlayer** instance.
createAudioPlayer(): [AudioPlayer](#audioplayer)
Creates an **AudioPlayer** instance in synchronous mode.
**Return values**
| Type | Description |
| Type| Description|
| --------------------------- | ------------------------------------------------------------ |
| [AudioPlayer](#audioplayer) | Returns the **AudioPlayer** instance if the operation is successful; returns **null** otherwise. |
| [AudioPlayer](#audioplayer) | Returns the **AudioPlayer** instance if the operation is successful; returns **null** otherwise. After the instance is created, you can start, pause, or stop audio playback.|
**Example**
```js
var audioPlayer = media.createAudioPlayer();
```
## media.createAudioPlayerAsync<sup>8+</sup>
createAudioPlayerAsync(callback: AsyncCallback\<[AudioPlayer](#audioplayer)>): void
Creates an **AudioPlayer** instance in asynchronous mode. This method uses a callback to return the result.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------------------------ | ---- | ------------------------------ |
| callback | AsyncCallback<[AudioPlayer](#audioplayer)> | Yes| Callback used to return the **AudioPlayer** instance created.|
**Example**
```js
media.createAudioPlayerAsync((error, audio) => {
if (typeof(audio) != 'undefined') {
audioPlayer = audio;
console.info('audio createAudioPlayerAsync success');
} else {
console.info(`audio createAudioPlayerAsync fail, error:${error.message}`);
}
});
```
var audioplayer = media.createAudioPlayer();
## media.createAudioPlayerAsync<sup>8+</sup>
createAudioPlayerAsync: Promise<[AudioPlayer](#audioplayer)>
Creates an **AudioPlayer** instance in asynchronous mode. This method uses a promise to return the result.
**Return values**
| Type| Description|
| ------------------------------------ | ----------------------------------- |
| Promise<[AudioPlayer](#audioplayer)> | Promise used to return the **AudioPlayer** instance created.|
**Example**
```js
function failureCallback(error) {
console.info(`audio failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`audio catchCallback, error:${error.message}`);
}
await media.createAudioPlayerAsync.then((audio) => {
if (typeof(audio) != 'undefined') {
audioPlayer = audio;
console.info('audio createAudioPlayerAsync success');
} else {
console.info('audio createAudioPlayerAsync fail');
}
}, failureCallback).catch(catchCallback);
```
## media.createAudioRecorder
createAudioRecorder(): AudioRecorder
Creates an **AudioRecorder** instance to control audio recording.
**Return values**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| [AudioRecorder](#audiorecorder) | Returns the **AudioRecorder** instance if the operation is successful; returns **null** otherwise. |
| Type| Description|
| ------------------------------- | ----------------------------------------- |
| [AudioRecorder](#audiorecorder) | Returns the **AudioRecorder** instance if the operation is successful; returns **null** otherwise.|
**Example**
......@@ -44,255 +107,486 @@ Creates an **AudioRecorder** instance to control audio recording.
var audiorecorder = media.createAudioRecorder();
```
## MediaErrorCode<sup>8+</sup>
Enumerates the media error codes.
| Name| Value| Description|
| -------------------------- | ---- | -------------------------------------- |
| MSERR_OK | 0 | The operation is successful.|
| MSERR_NO_MEMORY | 1 | Failed to allocate memory. The system may have no available memory.|
| MSERR_OPERATION_NOT_PERMIT | 2 | No permission to perform this operation.|
| MSERR_INVALID_VAL | 3 | Invalid input parameter.|
| MSERR_IO | 4 | An I/O error occurs.|
| MSERR_TIMEOUT | 5 | The operation times out.|
| MSERR_UNKNOWN | 6 | An unknown error occurs.|
| MSERR_SERVICE_DIED | 7 | Invalid server.|
| MSERR_INVALID_STATE | 8 | The operation is not allowed in the current state.|
| MSERR_UNSUPPORTED | 9 | The operation is not supported in the current version.|
## MediaType<sup>8+</sup>
Enumerates the media types.
| Name| Value| Description|
| ------------------- | ---- | ------------------ |
| MEDIA_TYPE_AUD | 0 | Media.|
| MEDIA_TYPE_VID | 1 | Video.|
| MEDIA_TYPE_SUBTITLE | 2 | Subtitle. (under development)|
## CodecMimeType<sup>8+</sup>
Enumerates the codec MIME types.
| Name| Value| Description|
| ------------ | ----------------- | ------------------------ |
| AUDIO_MPEG | "audio/mpeg" | Audio in MPEG format.|
| AUDIO_AAC | "audio/mp4a-latm" | Audio in MP4A-LATM format.|
| AUDIO_VORBIS | "audio/vorbis" | Audio in Vorbis format.|
| AUDIO_FLAC | "audio/flac" | Audio in FLAC format.|
## MediaDescriptionKey<sup>8+</sup>
Enumerates the media description keys.
| Name| Value| Description|
| ------------------------ | --------------- | ------------------------------------------------------------ |
| MD_KEY_TRACK_INDEX | "track_index" | Track index, which is a number.|
| MD_KEY_TRACK_TYPE | "track_type" | Track type, which is a number. For details, see [MediaType](#mediatype8).|
| MD_KEY_CODEC_MIME | "codec_mime" | Codec MIME type, which is a string.|
| MD_KEY_DURATION | "duration" | Media duration, which is a number, in units of ms.|
| MD_KEY_BITRATE | "bitrate" | Bit rate, which is a number, in units of bit/s.|
| MD_KEY_WIDTH | "width" | Video width, which is a number, in units of pixel.|
| MD_KEY_HEIGHT | "height" | Video height, which is a number, in units of pixel.|
| MD_KEY_FRAME_RATE | "frame_rate" | Video frame rate, which is a number, in units of 100 fps.|
| MD_KEY_AUD_CHANNEL_COUNT | "channel_count" | Number of audio channels, which is a number.|
| MD_KEY_AUD_SAMPLE_RATE | "sample_rate" | Sampling rate, which is a number, in units of Hz.|
## BufferingInfoType<sup>8+</sup>
Enumerates the buffering event types.
| Name| Value| Description|
| ----------------- | ---- | -------------------------- |
| BUFFERING_START | 1 | Buffering starts.|
| BUFFERING_END | 2 | Buffering ends.|
| BUFFERING_PERCENT | 3 | Buffering progress, in percent.|
| CACHED_DURATION | 4 | Cache duration, in milliseconds.|
## AudioPlayer
Manages and plays audio. Before calling a method of **AudioPlayer**, you must use [createAudioPlayer()](#mediacreateaudioplayer) to create an **AudioPlayer** instance.
Manages and plays audio. Before calling a method of the **AudioPlayer** class, you must call [createAudioPlayer()](#media.createaudioplayer) or [createAudioPlayerAsync()](#media.createaudioplayerasync8) to create an [AudioPlayer](#audioplayer) instance.
For details about the audio playback demo, see [Audio Playback Development](.../media/audio-playback.md).
### Attributes
### Attributes<a name=audioplayer_Attributes></a>
| Name | Type | Readable | Writable | Description |
| ----------- | ------------------------- | -------- | -------- | ------------------------------------------------------------ |
| src | string | Yes | Yes | Audio media URI. Popular audio formats (mp4, aac, mp3, and ogg) are supported. The value can be a local absolute path starting with **file://**. |
| loop | boolean | Yes | Yes | Whether to loop audio playback. The value **true** means to loop playback. |
| currentTime | number | Yes | No | Current playback position. |
| duration | number | Yes | No | Audio duration. |
| state | [AudioState](#audiostate) | Yes | No | Playback status. |
| Name| Type| Readable| Writable| Description|
| ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ |
| src | string | Yes| Yes| Audio media URI. The mainstream audio formats (MP4, AAC, MP3, and OGG) are supported. <br>**Examples of supported URIs**:<br>1. Local absolute path: file:///data/data/ohos.xxx.xxx/files/test.mp4<br>![en-us_image_0000001164217678](figures/en-us_image_0000001164217678.png)<br>2. HTTP network playback path (under development)<br>3. HLS network playback path (under development)<br>4. FD playback (under development)<br>**Precautions**: <br>Media files can be played only after the read permission is granted.|
| loop | boolean | Yes| Yes| Whether to loop audio playback. The value **true** means to loop audio playback, and **false** means the opposite.|
| currentTime | number | Yes| No| Current audio playback position.|
| duration | number | Yes| No| Audio duration.|
| state | [AudioState](#audiostate) | Yes| No| Audio playback state.|
### play
### play<a name=audioplayer_play></a>
play\(\): void
play(): void
Starts audio playback.
Starts to play audio resources. This method can be called only after the [dataLoad](#on('play' | 'pause' | 'stop' | 'reset' | 'dataload' | 'finish' | 'volumechange')) event is triggered.
**Example**
```
audioplayer.src = 'file:///data/media/sounds.mp4';
audioplayer.on('play', () => {
console.log('Playback starts.');
```js
audioPlayer.on('play', () => { // Set the 'play' event callback.
console.log('audio play success');
});
audioplayer.play();
audioPlayer.play();
```
### pause
### pause<a name=audioplayer_pause></a>
pause\(\): void
pause(): void
Pauses audio playback.
**Example**
```
audioplayer.src = 'file:///data/media/sounds.mp4';
audioplayer.on('pause', () => {
console.log('Playback paused.');
```js
audioPlayer.on('pause', () => { // Set the 'pause' event callback.
console.log('audio pause success');
});
audioplayer.pause();
audioPlayer.pause();
```
### stop<a name=audioplayer_stop></a>
### stop
stop\(\): void
stop(): void
Stops audio playback.
**Example**
```
audioplayer.src = 'file:///data/media/sounds.mp4';
audioplayer.on('stop',() => {
console.log('Playback stopped.');
```js
audioPlayer.on('stop', () => { // Set the 'stop' event callback.
console.log('audio stop success');
});
audioplayer.stop();
audioPlayer.stop();
```
### reset<sup>7+</sup><a name=audioplayer_reset></a>
### seek
reset(): void
seek\(timeMs: number\): void
Switches the audio resource to be played.
**Example**
```js
audioPlayer.on('reset', () => { // Set the 'reset' event callback.
console.log('audio reset success');
});
audioPlayer.reset();
```
### seek<a name=audioplayer_seek></a>
seek(timeMs: number): void
Seeks to the specified playback position.
**Parameters**
| Name | Type | Mandatory | Description |
| ------ | ------ | --------- | ----------------------------- |
| timeMs | number | Yes | Playback position to seek to. |
| Name| Type| Mandatory| Description|
| ------ | ------ | ---- | ------------------------------ |
| timeMs | number | Yes| Position to seek to, in milliseconds.|
**Example**
```
audioplayer.src = 'file:///data/media/sounds.mp4';
audioplayer.on('timeupdate', (action) => {
var newTime = audioplayer.currenTime;
if(newTime >= 30000) {
console.info('Seek succeeded. New time: ' + newTime);
} else {
console.info('Seek failed.');
```js
audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback.
if (typeof (seekDoneTime) == 'undefined') {
console.info('audio seek fail');
return;
}
console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
});
audioplayer.seek(30000);
audioPlayer.seek(30000); // Seek to 30000 ms.
```
### setVolume
### setVolume<a name=audioplayer_setvolume></a>
setVolume\(vol: number\): void
setVolume(vol: number): void
Sets the volume.
**Parameters**
| Name | Type | Mandatory | Description |
| ---- | ------ | --------- | ------------------------------------------------------------ |
| vol | number | Yes | Relative volume. The value ranges from 0.00 to 1.00. The value **1** indicates the maximum volume (100%). |
| Name| Type| Mandatory| Description|
| ------ | ------ | ---- | ------------------------------------------------------------ |
| vol | number | Yes| Relative volume. The value ranges from 0.00 to 1.00. The value **1** indicates the maximum volume (100%).|
**Example**
```
audioplayer.src = 'file:///data/media/sounds.mp4';
audioplayer.on('volumeChange', () => {
console.log('Playback volume changed.');
```js
audioPlayer.on('volumeChange', () => { // Set the 'volumeChange' event callback.
console.log('audio volumeChange success');
});
audioplayer.setVolume(1);
audioPlayer.setVolume(1); // Set the volume to 100%.
```
### reset<sup>7+</sup>
### release<a name=audioplayer_release></a>
reset\(\): void
release(): void
Switches the audio resource to be played.
Releases this **AudioPlayer** instance.
**Example**
```
audioplay.reset();
```js
audioPlayer.release();
audioPlayer = undefined;
```
### release
### getTrackDescription<sup>8+</sup><a name=audioplayer_gettrackdescription1></a>
release\(\): void
getTrackDescription(callback: AsyncCallback<Array<[MediaDescription](#mediadescription8)>>): void
Releases audio resources.
Obtains the audio track information. This method uses a callback to return the result.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | Yes| Callback used to return the audio track information obtained.|
**Example**
```js
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('audio key is ' + item);
console.info('audio value is ' + property);
}
}
audioPlayer.getTrackDescription((error, arrlist) => {
if (typeof (arrlist) != 'undefined') {
for (let i = 0; i < arrlist.length; i++) {
printfDescription(arrlist[i]);
}
} else {
console.log(`audio getTrackDescription fail, error:${error.message}`);
}
});
```
audioplay.release();
### getTrackDescription<sup>8+</sup><a name=audioplayer_gettrackdescription2></a>
getTrackDescription(): Promise<Array<[MediaDescription](#mediadescription8)>>
Obtains the audio track information. This method uses a promise to return the result.
**Return values**
| Type| Description|
| ------------------------------------------------------ | ------------------------------- |
| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise used to return the audio track information obtained.|
**Example**
```js
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('audio key is ' + item);
console.info('audio value is ' + property);
}
}
function failureCallback(error) {
console.info(`audio failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`audio catchCallback, error:${error.message}`);
}
await audioPlayer.getTrackDescription.then((arrlist) => {
if (typeof (arrlist) != 'undefined') {
arrayDescription = arrlist;
} else {
console.log('audio getTrackDescription fail');
}
}, failureCallback).catch(catchCallback);
for (let i = 0; i < arrayDescription.length; i++) {
printfDescription(arrayDescription[i]);
}
```
### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')
### on('bufferingUpdate')<sup>8+</sup>
Listens for audio playback events.
on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void
on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void)
Subscribes to the audio buffering update event.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | --------- | ------------------------------------------------------------ |
| type | string | Yes | Type of the playback event to listen for. The following events are supported: **play**, **pause**, **stop**, **reset**, **dataLoad**, **finish**, and **volumeChange**.<br>- The **play** event is triggered when audio playback starts. <br/>- The **pause** event is triggered when audio playback is paused.<br/>- The **stop** event is triggered when audio playback stops.<br/>- The **reset** event is triggered when the player is reset.<br/>- The **dataLoad** event is triggered when audio data is loaded.<br/>- The **finish** event is triggered when audio playback is finished.<br/>- The **volumeChange** event is triggered when the playback volume changes. |
| callback | function | Yes | Callback used to listen for the playback event. |
| Name| Type| Mandatory| Description|
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to, which is 'bufferingUpdate' in this example.|
| callback | (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void | Yes| Callback invoked when the event is triggered. <br>When [BufferingInfoType](#bufferinginfotype8) is set to **BUFFERING_PERCENT** or **CACHED_DURATION**, **value** is valid. Otherwise, **value** is fixed at **0**.|
**Example**
```js
audioPlayer.on('bufferingUpdate', (infoType, value) => {
console.log('audio bufferingInfo type: ' + infoType);
console.log('audio bufferingInfo value: ' + value);
});
```
audioplayer.src = 'file://xxx/sounds.mp4';
audioplayer.on('play', () => {
console.log('Playback starts.');
### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')
on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void
Subscribes to the audio playback events.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ---------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to. The following events are supported: 'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange' <br>- The 'play' event is triggered when the [play()](#audioplayer_play) method is called and audio playback starts. <br>- The 'pause' event is triggered when the [pause()](#audioplayer_pause) method is called and audio playback is paused. <br>- The 'stop' event is triggered when the [stop()](#audioplayer_stop) method is called and audio playback stops. <br>- The 'reset' event is triggered when the [reset()](#audioplayer_reset) method is called and audio playback is reset. <br>- The 'dataLoad' event is triggered when the audio data is loaded, that is, when the **src** attribute is configured. <br>- The 'finish' event is triggered when the audio playback is finished. <br>- The 'volumeChange' event is triggered when the [setVolume()](#audioplayer_setvolume) method is called and the playback volume is changed.|
| callback | () => void | Yes| Callback invoked when the event is triggered.|
**Example**
```js
let audioPlayer = media.createAudioPlayer(); // Create an AudioPlayer instance.
audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully.
console.info('audio set source success');
audioPlayer.play(); // Start the playback and trigger the 'play' event callback.
});
audioplayer.play();
audioPlayer.on('play', () => { // Set the 'play' event callback.
console.info('audio play success');
audioPlayer.seek(30000); // Call the seek() method and trigger the 'timeUpdate' event callback.
});
audioPlayer.on('pause', () => { // Set the 'pause' event callback.
console.info('audio pause success');
audioPlayer.stop(); // Stop the playback and trigger the 'stop' event callback.
});
audioPlayer.on('reset', () => { // Set the 'reset' event callback.
console.info('audio reset success');
audioPlayer.release(); // Release the AudioPlayer instance.
audioPlayer = undefined;
});
audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback.
if (typeof(seekDoneTime) == "undefined") {
console.info('audio seek fail');
return;
}
console.info('audio seek success, and seek time is ' + seekDoneTime);
audioPlayer.setVolume(0.5); // Set the volume to 50% and trigger the 'volumeChange' event callback.
});
audioPlayer.on('volumeChange', () => { // Set the 'volumeChange' event callback.
console.info('audio volumeChange success');
audioPlayer.pause(); // Pause the playback and trigger the 'pause' event callback.
});
audioPlayer.on('finish', () => { // Set the 'finish' event callback.
console.info('audio play finish');
audioPlayer.stop(); // Stop the playback and trigger the 'stop' event callback.
});
audioPlayer.on('error', (error) => { // Set the 'error' event callback.
console.info(`audio error called, errName is ${error.name}`);
console.info(`audio error called, errCode is ${error.code}`);
console.info(`audio error called, errMessage is ${error.message}`);
});
audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp4'; // Set the src attribute and trigger the 'dataLoad' event callback.
```
### on('timeUpdate')
on(type: 'timeUpdate', callback: Callback\<number>): void
Listens for audio playback timestamp update events.
Subscribes to the 'timeUpdate' event.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------- | --------- | ------------------------------------------------------------ |
| type | string | Yes | Type of the playback event to listen for. Only the **timeUpdate** event is supported.<br>- The **timeUpdate** event is triggered when the audio playback timestamp is updated. It is also triggered when the **seek** method is called. |
| callback | Callback&lt;number&gt; | Yes | Callback used to listen for the playback event. |
| Name| Type| Mandatory| Description|
| -------- | ----------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to, which is 'timeUpdate' in this method. <br>The 'timeUpdate' event is triggered when the [seek()](#audioplayer_seek) method is called.|
| callback | Callback\<number> | Yes| Callback invoked when the event is triggered. The input parameter of the callback is the time when the seek operation is successful.|
**Example**
```
audioplayer.src = 'file://xxx/sounds.mp4';
audioplayer.on('timeupdate', (newTime ) => {
if(newTime >= 30000) {
console.info('Seek succeeded. New time: ' + newTime);
} else {
console.info('Seek failed.');
```js
audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback.
if (typeof (seekDoneTime) == 'undefined') {
console.info('audio seek fail');
return;
}
console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
});
audioplayer.seek(30000);
audioPlayer.seek(30000); // Seek to 30000 ms.
```
### on('error')
on(type: 'error', callback: ErrorCallback): void
Listens for playback error events.
Subscribes to the audio playback error event.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------------- | --------- | ------------------------------------------------------------ |
| type | string | Yes | Type of the playback error event to listen for.<br>- The **error** event is triggered when an error occurs during audio playback. |
| callback | ErrorCallback | Yes | Callback used to listen for the playback event. |
| Name| Type| Mandatory| Description|
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to, which is 'error' in this method. <br>The 'error' event is triggered when an error occurs during audio playback.|
| callback | ErrorCallback | Yes| Callback invoked when the event is triggered.|
**Example**
```
audioplayer.src = 'file:///data/sounds.mp4';
audioplayer.on('error', (err) => {
console.info('error callback info: ' + err);
```js
audioPlayer.on('error', (error) => { // Set the error event callback.
console.info(`audio error called, errName is ${error.name}`); // Print the error name.
console.info(`audio error called, errCode is ${error.code}`); // Print the error code.
console.info(`audio error called, errMessage is ${error.message}`);// Print the detailed description of the error type.
});
audioplayer.setVolume(30000);
audioPlayer.setVolume(3); // Set volume to an invalid value to trigger the 'error' event.
```
## AudioState
Describes the audio playback state.
Describes the audio playback state. You can obtain the state through the **state** attribute.
| Name| Type| Description|
| ------------------ | ------ | -------------- |
| idle | string | Audio playback is idle.|
| playing | string | Audio playback is in progress.|
| paused | string | Audio playback is paused.|
| stopped | string | Audio playback is stopped.|
| error<sup>8+</sup> | string | Audio playback is in the error state.|
## MediaDescription<sup>8+</sup>
### [key : string] : any
Defines media information in key-value mode.
| Name| Type| Description|
| ----- | ------ | ------------------------------------------------------------ |
| key | string | Key of the media information. For details about the keys, see [MediaDescriptionKey](#mediadescriptionkey8).|
| value | any | Value of the key. For details about the values, see [MediaDescriptionKey](#mediadescriptionkey8).|
| Name | Description |
| ------- | -------------------------- |
| idle | Audio playback is idle. |
| playing | The audio is being played. |
| paused | Audio playback is paused. |
| stopped | Audio playback is stopped. |
**Example**
```js
function printfItemDescription(obj, key) {
let property = obj[key];
console.info('audio key is ' + key);
console.info('audio value is ' + property);
}
audioPlayer.getTrackDescription((error, arrlist) => {
if (typeof (arrlist) != 'undefined') {
for (let i = 0; i < arrlist.length; i++) {
printfItemDescription(arrlist[i], MD_KEY_TRACK_TYPE); // Print the MD_KEY_TRACK_TYPE value of each track.
}
} else {
console.log(`audio getTrackDescription fail, error:${error.message}`);
}
});
```
## AudioRecorder
Provides methods to record audio. Before calling an **AudioRecorder** method, you must use [createAudioRecorder\(\)](#mediacreateaudiorecorder) to create an **AudioRecorder** instance.
Implements audio recording. Before calling a method of the **AudioRecorder** class, you must call [createAudioRecorder()](#createaudiorecorder-audiorecorder) to create an **AudioRecorder** instance.
### prepare
prepare(config: AudioRecorderConfig): void
Prepares for recording.
**Parameters**
| Name | Type | Mandatory | Description |
| ------ | ------------------------------------------- | --------- | ------------------------------------------------------------ |
| config | [AudioRecorderConfig](#audiorecorderconfig) | Yes | Recording parameters, including the audio output URI, encoding format, sampling rate, and number of audio channels |
| Name| Type| Mandatory| Description|
| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ |
| config | [AudioRecorderConfig](#audiorecorderconfig) | Yes| Recording parameters, including the audio output URI, encoding format, sampling rate, and number of audio channels.|
**Example**
```
let audioRecorderConfig = {
```
let audioRecorderConfig = {
audioEncoder : AAC_LC ,
audioEncodeBitRate : 22050,
audioSampleRate : 22050,
numberOfChannels : 2,
format : AAC_ADTS,
uri : 'file:///data/accounts/account_0/appdata/appdata/recorder/test.m4a',
}
audiorecorder.prepare(audioRecorderConfig)
```
}
audiorecorder.prepare(audioRecorderConfig)
```
### start
start(): void
......@@ -321,6 +615,8 @@ audiorecorder.stop();
release(): void
Releases this **AudioRecorder** instance.
**Example**
```
......@@ -333,7 +629,7 @@ reset(): void
Resets audio recording.
Before resetting audio recording, you must call **stop\(\)** to stop recording. After audio recording is reset, you must call **prepare\(\)** to set the recording configurations for another recording.
Before resetting audio recording, you must call **stop()** to stop recording. After audio recording is reset, you must call **prepare()** to set the recording configurations for another recording.
**Example**
......@@ -345,14 +641,14 @@ audiorecorder.reset();
on(type: 'prepare' | 'start' | 'stop' | 'release' | 'reset', callback: () => void): void
Listens for audio recording events.
Subscribes to the audio recording events.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | --------- | ------------------------------------------------------------ |
| type | string | Yes | Type of the audio recording event to listen for. The following events are supported: **prepare**, **start**, **stop**, **release**, and **reset**.<br>- The **prepare** event is triggered when the audio recording preparation is complete.<br/>- The **start** event is triggered when audio recording starts.<br/>- The **stop** event is triggered when audio recording stops.<br/>- The **release** event is triggered when resources related to audio recording are released.<br/>- The **reset** event is triggered when audio recording is reset. |
| callback | function | Yes | Callback used to listen for the audio recording event. |
| Name| Type| Mandatory| Description|
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to. The following events are supported: 'prepare'\|'start'\|'stop'\|'release'\|'reset' <br/>- The 'prepare' event is triggered when audio recording preparation is complete. <br/>- The 'start' event is triggered when audio recording starts. <br/>- The 'stop' event is triggered when audio recording is stopped. <br/>- The 'release' event is triggered when the resources related to audio recording are released. <br/>- The 'reset' event is triggered when audio recording is reset.|
| callback | function | Yes| Callback invoked when the event is triggered.|
**Example**
......@@ -367,41 +663,44 @@ audiorecorder.on('prepare', () => {
on(type: 'error', callback: ErrorCallback): void
Listens for audio recording error events.
Subscribes to the audio recording error event.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | --------- | ------------------------------------------------------------ |
| type | string | Yes | Type of the audio recording error event to listen for.<br>- The **error** event is triggered when an error occurs during audio recording. |
| callback | function | Yes | Callback used to listen for the audio recording event. |
| Name| Type| Mandatory| Description|
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to, which is 'error' in this method. <br/>The 'error' event is triggered when an error occurs during audio recording.|
| callback | ErrorCallback | Yes| Callback invoked when the event is triggered.|
## AudioRecorderConfig
Describes audio recording configurations.
| Name | Type | Mandatory | Description |
| ------------------ | --------------------------------------- | --------- | ------------------------------------------------------------ |
| audioEncoder | [AudioEncoder](#audioencoder) | No | Audio encoding format. The default value is **AAC_LC**. |
| audioEncodeBitRate | number | No | Bit rate for audio encoding. The default value is **48000**. |
| audioSampleRate | number | No | Audio sampling rate. The default value is **48000**. |
| numberOfChannels | number | No | Number of audio channels. The default value is **2**. |
| format | [AudioOutputFormat](#audiooutputformat) | No | Audio output format. The default value is **MPEG_4**. |
| uri | string | Yes | Audio output URI. The following types of URIs are supported:<br/>1. Absolute path:<br>file:///data/data/ohos.xxx.xxx/cache/test.mp4![en-us_image_0000001164217678](figures/en-us_image_0000001164217678.png)<br/> 2. Path with the file descriptor (FD): file://1 (FD number) |
| Name| Type| Mandatory| Description|
| ------------------ | --------------------------------------- | ---- | ------------------------------------------------------------ |
| audioEncoder | [AudioEncoder](#audioencoder) | No| Audio encoding format. The default value is **AAC_LC**.|
| audioEncodeBitRate | number | No| Audio encoding bit rate. The default value is **48000**.|
| audioSampleRate | number | No| Audio sampling rate. The default value is **48000**.|
| numberOfChannels | number | No| Number of audio channels. The default value is **2**.|
| format | [AudioOutputFormat](#audiooutputformat) | No| Audio output format. The default value is **MPEG_4**.|
| uri | string | Yes| Audio output URI. The following URI types are supported:<br/> 1. Absolute file path: file:///data/data/ohos.xxx.xxx/cache/test.mp4![en-us_image_0000001164217678](figures/en-us_image_0000001164217678.png)<br/>2. FD path: file://1&nbsp;(fd&nbsp;number)|
## AudioEncoder
Enumerates audio encoding formats.
Enumerates the audio encoding formats.
| Name| Default Value| Description|
| ------ | ------ | ------------------------------------------------------------ |
| AAC_LC | 3 | Advanced Audio Coding Low Complexity (AAC-LC).|
| Name | Default Value | Description |
| ------ | ------------- | ---------------------------------------------- |
| AAC_LC | 3 | Advanced Audio Coding Low Complexity (AAC-LC). |
## AudioOutputFormat
Enumerates audio output formats.
Enumerates the audio output formats.
| Name | Default Value | Description |
| -------- | ------------- | ------------------------------------------------------------ |
| MPEG_4 | 2 | MPEG-4. |
| AAC_ADTS | 6 | Audio Data Transport Stream (ADTS), a transmission stream format of Advanced Audio Coding (AAC) audio. |
\ No newline at end of file
| Name| Default Value| Description|
| -------- | ------ | ------------------------------------------------------------ |
| MPEG_4 | 2 | MPEG-4.|
| AAC_ADTS | 6 | Audio Data Transport Stream (ADTS), which is a transport stream format of AAC-based audio.|
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或