diff --git a/en/application-dev/media/audio-playback.md b/en/application-dev/media/audio-playback.md index 0d1ab3179447e5301c727c649699a569bf5a3e63..2afa827c57fc2cc9703c7c8c3ac8ffb6ad54b26d 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 - -## 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 -![](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) => { +# 音频播放开发指导 + +- [场景介绍](#场景介绍) +- [接口说明](#接口说明) + +## 场景介绍 + +音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。 + +**图1** 音频播放状态机 +![zh-cn_image_0000001182608857](figures/zh-cn_image_0000001182608857.png) + + +## 接口说明 + +**表1** media + +| 接口名 | 描述 | +| -------- | -------- | +| media.createAudioPlayer() | 创建AudioPlayer实例。 | +| AudioPlayer | 提供音频播放相关功能，具体见表 音频播放相关的interface AudioPlayer。 | + +**表2** 音频播放相关的interface **AudioPlayer** + +| 接口名 | 描述 | +| -------- | -------- | +| release() | 释放音频资源。 | +| play() | 开始播放音频源。 | +| pause() | 暂停播放。 | +| stop() | 停止播放。 | +| reset()7+ | 重置播放音频源。 | +| setVolume(vol: number) | 改变音频播放音量 | +| seek(timeMs: number) | 改变播放位置。 | +| src:string | 音频播放的媒体URI。 | +| state:AudioState | 播放的状态属性。 | +| currentTime:number | 音频的当前播放位置。 | +| duration:number | 音频播放的时长(当数据源不支持改变播放位置时返回-1, 比如实时流媒体场景)。 | +| loop:boolean | 音频的循环播放属性。 | +| on('play', function callback) | 订阅音频播放开始事件。 | +| on('pause', function callback) | 订阅音频播放暂停事件。 | +| on('stop', function callback) | 订阅音频播放停止事件。 | +| on('reset', function callback) | 订阅音频播放重置事件。 | +| on('finish',function callback) | 订阅音频播放结束事件。 | +| on('error', function callback) | 订阅音频播放错误事件。 | +| on('dataload', function callback) | 订阅音频播放加载数据事件。 | +| on('volumeChange', function callback) | 订阅音频播放音量变化事件。 | +| on('timeUpdate', function callback) | 订阅音频播放进度改变事件。 | + + +1. 创建音频播放器。 + ``` + import media from '@ohos.multimedia.media'; + var player = media.createAudioPlayer(); + ``` + +2. 设置消息订阅事件。 + ``` + 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) => { + 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 stop() callback.'); - return; + console.error('Error returned in the finish() 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('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('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 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. 启动播放。 + ``` + var audioSourceMp3 = 'file://test.mp3'; + player.src = audioSourceMp3; + player.loop = true; + ```