diff --git a/en/application-dev/media/audio-playback.md b/en/application-dev/media/audio-playback.md index 0d1ab3179447e5301c727c649699a569bf5a3e63..d2d2596e40035e761b7d2090ec2461628fa73742 100644 --- a/en/application-dev/media/audio-playback.md +++ b/en/application-dev/media/audio-playback.md @@ -1,237 +1,131 @@ -# Development Guidelines on Audio Playback +# Development Guidelines on Audio Playback -## When to Use +- [When to Use](#When-to-Use) +- [Available APIs](#Available-APIs) + +## 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. -**Figure 1** Playback status +**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 functions. For details, see AudioPlayer.

-
- -**Table 2** AudioPlayer methods - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Method

-

Description

-

release()

-

Releases audio resources.

-

play()

-

Starts audio playback.

-

pause()

-

Pauses playback.

-

stop()

-

Stops playback.

-

reset()7+

-

Resets the audio source to be played.

-

setVolume(vol: number)

-

Sets playback volume.

-

seek(timeMs: number)

-

Changes the playback position.

-

src:string

-

Defines the URI of an audio file to play.

-

state:AudioState

-

Defines a playback state.

-

currentTime:number

-

Defines the current playback position.

-

duration:number

-

Defines the playback duration.

-

loop:boolean

-

Defines whether to loop audio playback.

-

on('play', function callback)

-

Subscribes to the playback start event.

-

on('pause', function callback)

-

Subscribes to the playback pause event.

-

on('stop', function callback)

-

Subscribes to the playback stop event.

-

on('reset', function callback)

-

Subscribes to the playback reset event.

-

on('finish',function callback)

-

Subscribes to the playback end event.

-

on('error', function callback)

-

Subscribes to the playback error event.

-

on('dataload', function callback)

-

Subscribes to the data loading event.

-

on('volumeChange', function callback)

-

Subscribes to the volume change event.

-

on('timeUpdate', function 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) => { +## 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()7+ | Resets the audio source to be played.| +| setVolume(vol: number) | Sets playback volume.| +| seek(timeMs: 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', function callback) | Subscribes to the playback start event.| +| on('pause', function callback) | Subscribes to the playback pause event.| +| on('stop', function callback) | Subscribes to the playback stop event.| +| on('reset', function callback) | Subscribes to the playback reset event.| +| on('finish',function callback) | Subscribes to the playback end event.| +| on('error', function callback) | Subscribes to the playback error event.| +| on('dataload', function callback) | Subscribes to the data loading event.| +| on('volumeChange', function callback) | Subscribes to the volume change event.| +| on('timeUpdate', function 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 play() callback.'); + console.error('Error returned in the pause() callback.'); return; } - console.info('Current player duration: '+ player.duration); + console.info('Current player status: ' + player.state); 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. - }); - 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(); - }); - player.on('dataLoad', (err, action) => { + player.seek(30000); // Seek for 30 seconds. + }); + 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(); + }); + 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(); + }); + player.on('reset', (err, action) => { + if (err) { + console.error('Error returned in the reset() callback.'); + return; + } + console.info('reset callback invoked.'); + player.release(); + }); + player.on('finish', (err, action) => { if (err) { - console.error('Error returned in the dataLoad() callback.'); - return; + console.error('Error returned in the finish() callback.'); + return; } - console.info('dataLoad callback invoked. Current time: ' + player.currentTime); - console.info('Duration of the source:' + player.duration); - player.play(); - }); - player.on('reset', (err, action) => { - if (err) { - console.error('Error returned in the reset() callback.'); - return; + 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.info('reset callback invoked.'); - player.release(); - }); - player.on('finish', (err, action) => { - if (err) { - console.error('Error returned in the finish() callback.'); - return; - } - 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); - } - player.stop(); - }); - player.on('error', (err) => { - console.error('Player error: ${err.message}'); - }); - ``` - -3. Start playback. - - ``` - var audioSourceMp3 = 'file://test.mp3'; - player.src = audioSourceMp3; - player.loop = true; - ``` - - + player.stop(); + }); + player.on('error', (err) => { + console.error('Player error: ${err.message}'); + }); + ``` + +3. Start playback. + ``` + var audioSourceMp3 = 'file://test.mp3'; + player.src = audioSourceMp3; + player.loop = true; + ```