audio

Audio模块用于提供音频的录制和播放功能，可调用系统的麦克风设备进行录音操作，也可调用系统的扬声器设备播放音频文件。通过plus.audio获取音频管理对象。

常量：

方法：

对象：

回调方法：

权限：

5+功能模块（permissions）

  2. {
  3. // ...
  4. "permissions":{
  5.     // ...
  6.     "Audio": {
  7.         "description": "音频"
  8.     }
  9. }
  10. }
  11.

ROUTE_SPEAKER

设备的扬声器音频输出线路

  2. plus.audio.ROUTE_SPEAKER;
  3.

说明：

Number类型

音频输出线路常量，值为0。音频播放时在设备的扬声器输出。

ROUTE_EARPIECE

设备听筒音频输出线路

  2. plus.audio.ROUTE_EARPIECE;
  3.

说明：

Number类型

音频输出线路常量，值为1。音频播放时在设备的听筒输出。

getRecorder

获取当前设备的录音对象

  2. AudioRecorder plus.audio.getRecorder();
  3.

说明：

获取当前设备的录音对象，进行录音操作，录音对象是设备的独占资源，在同一时间仅可执行一个录音操作，否则可能会导致操作失败。

参数：

返回值：

AudioRecorder: 录音对象

平台支持：

  • Android- 2.2+(支持): 支持录制"amr"、"3gp"、"aac"等格式文件。注：aac格式要求android4.4及以上系统。
  • iOS- 4.3+(支持): 支持录制"wav"、"aac"、"amr"、"mp3"等格式文件。

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8">
  6.     <title>Audio Example</title>
  7.     <script type="text/javascript">
  8. // 扩展API加载完毕后调用onPlusReady回调函数 
  9. document.addEventListener( "plusready", onPlusReady, false );
  10. var r = null; 
  11. // 扩展API加载完毕，现在可以正常调用扩展API 
  12. function onPlusReady() { 
  13.     r = plus.audio.getRecorder(); 
  14. }
  15. function startRecord() {
  16.     if ( r == null ) {
  17.         alert( "Device not ready!" );
  18.         return; 
  19.     } 
  20.     r.record( {filename:"_doc/audio/"}, function () {
  21.         alert( "Audio record success!" );
  22.     }, function ( e ) {
  23.         alert( "Audio record failed: " + e.message );
  24.     } );
  25. }
  26. function stopRecord() {
  27.     r.stop(); 
  28. }
  29.     </script>
  30.     </head>
  31.     <body>
  32.         <input type="button" value="Start Record" onclick="startRecord();"/> 
  33.         <br/>
  34.         <input type="button" value="Stop Record" onclick="stopRecord();"/>
  35.     </body>
  36. </html>
  37.

uni-app使用plus注意事项

createPlayer

创建音频播放器对象


AudioPlayer plus.audio.createPlayer(styles);
AudioPlayer plus.audio.createPlayer(path);

说明：

用于播放音频文件，可以直接传入音频文件地址或音频播放参数对象AudioPlayerStyles。返回播放对象，可调用其play方法开始播放。

参数：

  • styles: (AudioPlayerStyles|String)必选 音频播放参数字符串（String）类型表示音频文件路径；JSON对象则表示音频播放参数对象AudioPlayerStyles，HBuilderX1.9.0及以上版本支持。

返回值：

AudioPlayer: 音频播放对象

平台支持：

  • Android- 2.2+(支持): 支持"aac"、"3gp"、"amr"、"mp3"、"mp4"、"mid"、"ogg"、"wav"等格式文件。支持播放网络路径音频，以http/https开头，如“http://demo.dcloud.net.cn/test/audio/apple.mp3”。
  • iOS- 4.3+(支持): 支持"aac"、"aiff"、"mp3"、"mid"、"wav"、"amr"等格式文件。暂不支持播放网络路径音频。

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <title>Audio Example</title>
    <script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API 
function onPlusReady() { 
}
var p = null; 
function startPlay() {
    if ( plus.audio == undefined ) {
        alert( "Device not ready!" );
    }
    p = plus.audio.createPlayer( "_Doc/Audio/test.mp3" );
    p.play( function () {
        alert( "Audio play success!" ); 
    }, function ( e ) {
        alert( "Audio play error: " + e.message ); 
    } ); 
}
function stopPlay() {
    p.stop();
}
    </script>
    </head>
    <body>
        <input type="button" value="Start Play" onclick="startPlay();"/> 
        <br/>
        <input type="button" value="Stop Play" onclick="stopPlay();"/>
    </body>
</html>

uni-app使用plus注意事项

AudioRecorder

录音对象


interface AudioRecorder {
    readonly attribute String[] supportedSamplerates;
    readonly attribute String[] supportedFormats;
    function record( option, successCB, errorCB );
    function stop();
}

属性：

方法：

  • record: 调用设备麦克风进行录音操作
  • stop: 结束录音操作

supportedSamplerates

数组，设备录音支持的采用率

说明：

String类型 只读属性

属性类型为Array(String)，若不支持此属性则返回空数组对象。支持的录音采样率，字符串格式为“采样频率”，如“8000”；其单位为Hz。

supportedFormats

数组，设备录音支持的文件格式

说明：

String类型 只读属性

属性类型为Array(String)，若不支持此属性则返回空数组对象。支持的录音文件的格式，字符串格式为文件格式后缀名，如"mp3"、"aac"、"wav"等。

平台支持：

  • Android- 2.2+(支持): Android平台支持"amr"、"3gp"格式，默认为"amr"。
  • iOS- 4.5+(支持): iOS平台支持"aac"、"wav"、"amr"格式，默认为"wav"。

record

调用设备麦克风进行录音操作


void recorder.record( option, successCB, errorCB );

说明：

调用设备麦克风开始录音操作，录音完成需调用stop方法停止。录音完成后将通过successCB回调返回录音后的文件数据。

参数：

返回值：

void: 无

示例：


// 录音操作
var r = plus.audio.getRecorder();
r.record( {filename:"_doc/audio/"}, function () {
    alert( "Audio record success!" );
}, function ( e ) {
    alert( "Audio record failed: " + e.message );
} );

uni-app使用plus注意事项

stop

结束录音操作


void recorder.stop();

说明：

结束录音操作，通知设备完成录音操作。录音完成后将调用record方法中传入的successCB回调返回录音文件。

参数：

无

返回值：

void: 无

示例：


// 录音操作
var r = plus.audio.getRecorder();
r.record( {filename:"_doc/audio/"}, function () {
    alert( "Audio record success!" );
}, function ( e ) {
    alert( "Audio record failed: " + e.message );
} );

// ...... 
// 停止录音
r.stop();

uni-app使用plus注意事项

AudioPlayer

音频播放对象


interface AudioPlayer {
    function void close();
    function Boolean isPaused();
    function void play(successCB, errorCB);
    function void pause();
    function void resume();
    function void stop();
    function void seekTo(position);
    function Number getBuffered();
    function Number getDuration();
    function Number getPosition();
    function void setRoute(route);
    function void setSessionCategory(category);
}

说明：

音频播放对象，用于音频文件的播放。不能通过new方法直接创建，只能通过audio.createPlayer方法创建。

方法：

addEventListener

添加事件监听器


void player.addEventListener(event, listener, capture);

说明：

向音频播放对象添加事件监听器，当指定的事件发生时，将触发listener函数的执行。可多次调用此方法添加多个监听器，当监听的事件发生时，将按照添加的先后顺序执行。

参数：

  • event: (AudioPlayerEvent)必选 音频播放事件类型
  • listener: (EventCallback)必选 监听事件发生时执行的回调函数
  • capture: (Boolean)可选 捕获事件流顺序，暂无效果

返回值：

void: 无

close

关闭音频播放对象


void player.close();

说明：

关闭操作将释放音频播放对象所占用的资源，关闭后不再可用。

参数：

无

返回值：

void: 无

getBuffered

音频缓冲的时间点


Number player.getBuffered();

说明：

表示当前播放时间点到此时间点内容已缓冲。单位为秒（s），，返回值可能是小数。

参数：

无

返回值：

Number: 音频缓冲的时间点

getDuration

获取音频的总长度


Number player.getDuration();

说明：

单位为秒（s），返回值可能是小数，若长度未知则返回-1。如果还未获取到音频流信息则返回NaN，此时需要延迟获取。

参数：

无

返回值：

Number: 音频的总长度

getPosition

获取音频的当前播放位置


Number player.getPosition();

说明：

获取音频流当前播放的位置（已播放的长度），单位为秒（s），返回值可能是小数。如果当前还未开始播放则返回0。

参数：

无

返回值：

Number: 当前音频播放位置

getStyles

音频播放的参数


var player.setStyles(key);

说明：

获取指定key的参数值，key取值范围为AudioPlayerStyles的所有参数。如果未设置key的参数，参数有默认值则返回默认，无默认值则返回undefined。

参数：

  • key: (String)可选 获取参数的key名称如果不传入参数key，则获取所有参数信息。

返回值：

var: 由传入的key决定返回类型，如果不设置key，则返回json格式数据。

isPaused

当前是否暂停或停止状态


Boolean player.isPaused();

说明：

当前音频为暂停或停止状态则返回true，否则返回false。

参数：

无

返回值：

Boolean: true表示当前为暂停或停止状态，false则表示当前为播放状态。

play

播放音频


void player.play(successCB, errorCB);

参数：

  • successCB: (PlaySuccessCallback)必选 播放音频操作成功回调函数当音频文件播放完成时回调。
  • errorCB: (AudioErrorCallback)可选 播放音频操作错误回调函数当音频文件播放发生错误时回调。

返回值：

void: 无

示例：


// 播放操作
var p = plus.audio.createPlayer();
p.play( function () {
    alert( "Audio play success!" );
}, function ( e ) {
    alert( "Audio play failed: " + e.message );
} );

uni-app使用plus注意事项

pause

暂停播放


void player.pause();

说明：

当前处于播放状态才能暂停，否则调用此方法无任何作用。

参数：

无

返回值：

void: 无

示例：


// 播放操作
var p = plus.audio.createPlayer();
p.play( function () {
    alert( "Audio play success!" );
}, function ( e ) {
    alert( "Audio play failed: " + e.message );
} );
// ......
// 暂停播放
p.pause();

uni-app使用plus注意事项

removeEventListener

移除事件监听器


void player.removeEventListener(event, listener);

说明：

从音频播放对象中移除通过addEventListener方法添加的事件监听器，若没有查找到对应的事件监听器，则无任何作用。

参数：

返回值：

void: 无

resume

恢复播放


void player.resume();

说明：

当前处于暂停状态从暂停处开始恢复播放，非暂停状态调用此方法无任何作用。

参数：

无

返回值：

void: 无

示例：


// 播放操作
var p = plus.audio.createPlayer();
p.play( function () {
    alert( "Audio play success!" );
}, function ( e ) {
    alert( "Audio play failed: " + e.message );
} );
// ......
// 暂停播放
p.pause();
// ......
// 恢复播放
p.resume();

uni-app使用plus注意事项

seekTo

跳到指定位置


void player.seekTo(position);

说明：

当前处于播放或暂停状态才能跳到指定播放位置，否则调用此方法无任何作用。

参数：

  • position: (Number)必选 要跳到的位置单位为秒（s），精确到小数点后3位。

返回值：

void: 无

stop

停止播放


void player.stop();

说明：

当前处于播放或暂停状态才能停止播放，否则调用此方法无任何作用。停止的音频再播放会从头开始播放。

参数：

无

返回值：

void: 无

示例：


// 播放操作
var p = plus.audio.createPlayer();
p.play( function () {
    alert( "Audio play success!" );
}, function ( e ) {
    alert( "Audio play failed: " + e.message );
} );
// ......
// 停止播放
p.stop();

uni-app使用plus注意事项

setRoute

音频输出线路


void player.setRoute(route);

说明：

可取值：plus.audio.ROUTE_SPEAKER - 使用设备的扬声器输出；plus.audio.ROUTE_EARPIECE - 使用设备的听筒输出。默认值为plus.audio.ROUTE_SPEAKER。可在音频文件开始播放前或播放过程中改变音频输出线路。

参数：

  • route: (Number)必选 音频播放时输出线路

返回值：

void: 无

示例：


// 播放操作
var p = plus.audio.createPlayer();
// 切换到听筒线路
p.setRoute( plus.audio.ROUTE_EARPIECE );
p.play( function () {
    alert( "Audio play success!" );
}, function ( e ) {
    alert( "Audio play failed: " + e.message );
} );
//...
// 切换到扬声器线路
p.setRoute( plus.audio.ROUTE_SPEAKER );

uni-app使用plus注意事项

setSessionCategory

设置音频播放模式


void player.setSessionCategory(category);

说明：

可设置是否和其它音频同时输出。注意：必须在调用play方法前设置才生效。

参数：

  • category: (String)必选 音频播放模式可取值："ambient" - 不中止其他声音播放，不能后台播放，静音后无声音；"soloAmbient" - 中止其他声音播放，不能后台播放，静音后无声音；"playback" - 中止其他声音，可以后台播放，静音后有声音。默认值为"playback"。

返回值：

void: 无

平台支持：

  • Android(不支持): 调用此接口无任何效果。
  • iOS- ALL(支持)

setStyles

设置音频播放的参数


void player.setStyles(styles);

说明：

用于动态更新音频播放的参数。·

参数：

返回值：

void: 无

AudioPlayerEvent

音频播放控件事件类型

常量：

  • "canplay": (String类型)音频可以播放事件
  • "play": (String类型)音频播放事件
  • "pause": (String类型)音频暂停事件
  • "stop": (String类型)音频停止事件
  • "ended": (String类型)音频自然播放结束事件
  • "error": (String类型)音频播放错误事件
  • "waiting": (String类型)音频加载中事件
  • "seeking": (String类型)音频进行seek操作事件
  • "seeked": (String类型)音频完成seek操作事件

  • "prev": (String类型)上一曲操作事件用户在后台播放控制器上点击上一曲按钮时触发，未开启后台控制器则不触发此事件。

  • "next": (String类型)下一曲操作事件用户在后台播放控制器上点击下一曲按钮时触发，未开启后台控制器则不触发此事件。

AudioPlayerStyles

音频播放对象的参数

属性：

  • autoplay: (Boolean类型)是否自动开始播放true - 自动开始播放；false - 不自动开始播放。默认值为false。

  • backgroundControl: (Boolean类型)是否开启后台控制器开启后应用切换到后台可继续播放音频。iOS平台在系统锁屏界面显示播放控件；Android平台暂不支持。

  • coverImgUrl: (String类型)封面图地址在后台播放控制器上显示，未开启后台控制器则不显示。

  • epname: (String类型)专辑名在后台播放控制器上显示，未开启后台控制器则不显示。

  • loop: (Boolean类型)是否循环播放true - 循环播放；false - 不循环播放。默认值为false。

  • singer: (String类型)歌手名在后台播放控制器上显示，未开启后台控制器则不显示。

  • src: (String类型)音频资源的地址支持本地路径和网络路径。

  • startTime: (Number类型)开始播放的位置单位为秒（s），默认值为0。

  • title: (String类型)音频标题在后台播放控制器上显示，未开启后台控制器则不显示。

  • volume: (Number类型)音量取值范围为0-1，默认值为1。

AudioRecorderStyles

音频录制的参数

属性：

  • channels: (String类型)录音声道可取值："mono" - 单声道录音；"stereo" - 立体声道录音。默认值为"mono"。

平台支持

  • Android - ALL (不支持): 暂不支持，仅支持单通道录音。
  • iOS - 7.0+ (支持)
    • filename: (String类型)保存录音文件的路径可设置具体文件名，也可只设置路径，如果以“/”结尾则表明是路径，文件名由录音程序自动生成。如未设置则使用默认目录生成随机文件名称，默认目录为应用%APPID%下的documents目录。

  • samplerate: (String类型)录音文件的采样率需通过supportedSamplerates属性获取设备支持的采样率，若设置无效的值，则使用系统默认的采样率。

  • format: (String类型)录音文件的格式需通过supportedFormats属性获取设备支持的录音格式，若设置无效的值，则使用系统默认的录音格式。

平台支持

  • Android - 2.2+ (支持): Android平台支持"amr"、"3gp"格式，默认为"amr"。
  • iOS - 4.5+ (支持): iOS平台支持"wav"、"aac"、"amr"格式，默认为"wav"。

RecordSuccessCallback

录音操作成功回调


void onSuccess( recordFile ) {
    // Get record file code.
}

说明：

麦克风录音操作成功的回调函数，在录音操作完成调用stop()方法时调用。

参数：

  • recordFile: (String)必选 录音操作保存的音频文件路径

返回值：

void: 无

PlaySuccessCallback

播放音频文件操作成功回调


void onCompleted() {
    // Play audio file completed code.
}

说明：

音频播放操作成功的回调函数，在音频播放完成或调用stop()方法时触发。

参数：

无

返回值：

void: 无

AudioErrorCallback

音频操作失败回调


void onError( error ) {
    // Handle audio error
}

参数：

  • error: (DOMException)必选 音频操作的错误信息

返回值：

void: 无