Audio模块用于提供音频的录制和播放功能,可调用系统的麦克风设备进行录音操作,也可调用系统的扬声器设备播放音频文件。通过plus.audio获取音频管理对象。
常量:
方法:
getRecorder: 获取当前设备的录音对象
对象:
回调方法:
权限:
5+功能模块(permissions)
{
// ...
"permissions":{
// ...
"Audio": {
"description": "音频"
}
}
}
设备的扬声器音频输出线路
plus.audio.ROUTE_SPEAKER;
说明:
Number
类型
音频输出线路常量,值为0。音频播放时在设备的扬声器输出。
设备听筒音频输出线路
plus.audio.ROUTE_EARPIECE;
说明:
Number
类型
音频输出线路常量,值为1。音频播放时在设备的听筒输出。
获取当前设备的录音对象
AudioRecorder plus.audio.getRecorder();
说明:
获取当前设备的录音对象,进行录音操作,录音对象是设备的独占资源,在同一时间仅可执行一个录音操作,否则可能会导致操作失败。
参数:
返回值:
AudioRecorder
: 录音对象
平台支持:
Android
- 2.2+
(支持)
:
支持录制"amr"、"3gp"、"aac"等格式文件。
注:aac格式要求android4.4及以上系统。
iOS
- 4.3+
(支持)
:
支持录制"wav"、"aac"、"amr"、"mp3"等格式文件。
示例:
Audio Example// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
var r = null;
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
r = plus.audio.getRecorder();
}
function startRecord() {
if ( r == null ) {
alert( "Device not ready!" );
return;
}
r.record( {filename:"_doc/audio/"}, function () {
alert( "Audio record success!" );
}, function ( e ) {
alert( "Audio record failed: " + e.message );
} );
}
function stopRecord() {
r.stop();
}
创建音频播放器对象
AudioPlayer plus.audio.createPlayer(styles);
AudioPlayer plus.audio.createPlayer(path);
说明:
用于播放音频文件,可以直接传入音频文件地址或音频播放参数对象AudioPlayerStyles。
返回播放对象,可调用其play方法开始播放。
参数:
styles:
字符串(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"等格式文件。
支持播放网络路径音频,以http/https开头,如“http://demo.dcloud.net.cn/test/audio/apple.mp3”。
示例:
Audio Example// 扩展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();
}
录音对象
interface AudioRecorder {
readonly attribute String[] supportedSamplerates;
readonly attribute String[] supportedFormats;
function record( option, successCB, errorCB );
function stop();
}
属性:
方法:
record: 调用设备麦克风进行录音操作
stop: 结束录音操作
数组,设备录音支持的采用率
说明:
String
类型
只读属性
属性类型为Array(String),若不支持此属性则返回空数组对象。支持的录音采样率,字符串格式为“采样频率”,如“8000”;其单位为Hz。
数组,设备录音支持的文件格式
说明:
String
类型
只读属性
属性类型为Array(String),若不支持此属性则返回空数组对象。支持的录音文件的格式,字符串格式为文件格式后缀名,如"mp3"、"aac"、"wav"等。
平台支持:
Android
- 2.2+
(支持)
:
Android平台支持"amr"、"3gp"格式,默认为"amr"。
iOS
- 4.5+
(支持)
:
iOS平台支持"aac"、"wav"、"amr"格式,默认为"wav"。
调用设备麦克风进行录音操作
void recorder.record( option, successCB, errorCB );
说明:
调用设备麦克风开始录音操作,录音完成需调用stop方法停止。录音完成后将通过successCB回调返回录音后的文件数据。
参数:
styles:
successCB:
errorCB:
返回值:
void
: 无
示例:
// 录音操作
var r = plus.audio.getRecorder();
r.record( {filename:"_doc/audio/"}, function () {
alert( "Audio record success!" );
}, function ( e ) {
alert( "Audio record failed: " + e.message );
} );
结束录音操作
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();
音频播放对象
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方法创建。
方法:
添加事件监听器
void player.addEventListener(event, listener, capture);
说明:
向音频播放对象添加事件监听器,当指定的事件发生时,将触发listener函数的执行。
可多次调用此方法添加多个监听器,当监听的事件发生时,将按照添加的先后顺序执行。
参数:
event:
listener:
capture:
(
Boolean
)
可选捕获事件流顺序,暂无效果
返回值:
void
: 无
关闭音频播放对象
void player.close();
说明:
关闭操作将释放音频播放对象所占用的资源,关闭后不再可用。
参数:
无
返回值:
void
: 无
音频缓冲的时间点
Number player.getBuffered();
说明:
表示当前播放时间点到此时间点内容已缓冲。
单位为秒(s),,返回值可能是小数。
参数:
无
返回值:
Number
: 音频缓冲的时间点
获取音频的总长度
Number player.getDuration();
说明:
单位为秒(s),返回值可能是小数,若长度未知则返回-1。
如果还未获取到音频流信息则返回NaN,此时需要延迟获取。
参数:
无
返回值:
Number
: 音频的总长度
获取音频的当前播放位置
Number player.getPosition();
说明:
获取音频流当前播放的位置(已播放的长度),单位为秒(s),返回值可能是小数。
如果当前还未开始播放则返回0。
参数:
无
返回值:
Number
: 当前音频播放位置
音频播放的参数
var player.setStyles(key);
说明:
获取指定key的参数值,key取值范围为AudioPlayerStyles的所有参数。
如果未设置key的参数,参数有默认值则返回默认,无默认值则返回undefined。
参数:
key:
(
String
)
可选获取参数的key名称
如果不传入参数key,则获取所有参数信息。
返回值:
var
: 由传入的key决定返回类型,如果不设置key,则返回json格式数据。
当前是否暂停或停止状态
Boolean player.isPaused();
说明:
当前音频为暂停或停止状态则返回true,否则返回false。
参数:
无
返回值:
Boolean
:
true表示当前为暂停或停止状态,false则表示当前为播放状态。
播放音频
void player.play(successCB, errorCB);
参数:
successCB:
当音频文件播放完成时回调。
errorCB:
当音频文件播放发生错误时回调。
返回值:
void
: 无
示例:
// 播放操作
var p = plus.audio.createPlayer();
p.play( function () {
alert( "Audio play success!" );
}, function ( e ) {
alert( "Audio play failed: " + e.message );
} );
暂停播放
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();
移除事件监听器
void player.removeEventListener(event, listener);
说明:
从音频播放对象中移除通过addEventListener方法添加的事件监听器,若没有查找到对应的事件监听器,则无任何作用。
参数:
event:
listener:
返回值:
void
: 无
恢复播放
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();
跳到指定位置
void player.seekTo(position);
说明:
当前处于播放或暂停状态才能跳到指定播放位置,否则调用此方法无任何作用。
参数:
position:
(
Number
)
必选要跳到的位置
单位为秒(s),精确到小数点后3位。
返回值:
void
: 无
停止播放
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();
音频输出线路
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 );
设置音频播放模式
void player.setSessionCategory(category);
说明:
可设置是否和其它音频同时输出。
注意:必须在调用play方法前设置才生效。
参数:
category:
(
String
)
必选音频播放模式
可取值:
"ambient" - 不中止其他声音播放,不能后台播放,静音后无声音;
"soloAmbient" - 中止其他声音播放,不能后台播放,静音后无声音;
"playback" - 中止其他声音,可以后台播放,静音后有声音。
默认值为"playback"。
返回值:
void
: 无
平台支持:
Android
(支持)
:
HBuilderX2.7.14+版本开始支持"ambient",不支持"soloAmbient"和"playback",默认终止其它声音播放,可后台播放。
iOS
- ALL
(支持)
设置音频播放的参数
void player.setStyles(styles);
说明:
用于动态更新音频播放的参数。
·
参数:
styles:
返回值:
void
: 无
音频播放控件事件类型
常量:
"canplay": (String
类型
)音频可以播放事件
"play": (String
类型
)音频播放事件
"pause": (String
类型
)音频暂停事件
"stop": (String
类型
)音频停止事件
"ended": (String
类型
)音频自然播放结束事件
"error": (String
类型
)音频播放错误事件
"waiting": (String
类型
)音频加载中事件
"seeking": (String
类型
)音频进行seek操作事件
"seeked": (String
类型
)音频完成seek操作事件
"prev": (String
类型
)上一曲操作事件
用户在后台播放控制器上点击上一曲按钮时触发,未开启后台控制器则不触发此事件。
"next": (String
类型
)下一曲操作事件
用户在后台播放控制器上点击下一曲按钮时触发,未开启后台控制器则不触发此事件。
音频播放对象的参数
属性:
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。
音频录制的参数
属性:
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"。
录音操作成功回调
void onSuccess( recordFile ) {
// Get record file code.
}
说明:
麦克风录音操作成功的回调函数,在录音操作完成调用stop()方法时调用。
参数:
recordFile:
(
String
)
必选录音操作保存的音频文件路径
返回值:
void
: 无
播放音频文件操作成功回调
void onCompleted() {
// Play audio file completed code.
}
说明:
音频播放操作成功的回调函数,在音频播放完成或调用stop()方法时触发。
参数:
无
返回值:
void
: 无
音频操作失败回调
void onError( error ) {
// Handle audio error
}
参数:
error:
(
Exception
)
必选音频操作的错误信息
返回值:
void
: 无