API Reference

Plugins

Native.js


audio

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

常量:

方法:

对象:

回调方法:

模块:

5+功能模块(permissions)


{
// ...
"permissions":{
	// ...
	"Audio": {
		"description": "音频"
	}
}
}
			

ROUTE_SPEAKER

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


plus.audio.ROUTE_SPEAKER;
				

说明:

Number 类型

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

ROUTE_EARPIECE

设备听筒音频输出线路


plus.audio.ROUTE_EARPIECE;
				

说明:

Number 类型

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

getRecorder

获取当前设备的录音对象


AudioRecorder plus.audio.getRecorder();
				

说明:

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

参数:

返回值:

AudioRecorder : 录音对象

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Audio Example</title>
	<script type="text/javascript">
// 扩展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(); 
}
	</script>
	</head>
	<body>
		<input type="button" value="Start Record" onclick="startRecord();"/> 
		<br/>
		<input type="button" value="Stop Record" onclick="stopRecord();"/>
	</body>
</html>
				

createPlayer

创建音频播放对象


AudioPlayer plus.audio.createPlayer( path );
				

说明:

创建一个音频文件播放对象,用于打开音频文件并播放。 可通过path参数指定要播放的音频文件。创建后返回播放对象,通过Audio.play方法开始播放。

参数:

返回值:

AudioPlayer : 音频播放对象

平台支持:

示例:


<!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>
				

AudioRecorder

录音对象


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

属性:

方法:

supportedSamplerates

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

说明:

String 类型 只读属性

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

supportedFormats

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

说明:

String 类型 只读属性

属性类型为Array(String),若不支持此属性则返回空数组对象。支持的录音文件的格式,字符串格式为文件格式后缀名,如"mp3"、"aac"、"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 );
} );
						

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();
						

AudioPlayer

音频播放对象


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

说明:

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

方法:

play

开始播放音频


void player.play( successCB, errorCB );
						

参数:

返回值:

void : 无

示例:


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

pause

暂停播放音频


void player.pause();
						

说明:

需先调用createPlayer方法创建音频播放对象,并开始播放。音频播放对象在播放状态才能暂停,在其它状态调用此方法无任何作用。

参数:

返回值:

void : 无

示例:


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

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();
						

stop

停止播放音频


void player.stop();
						

说明:

停止播放音频,音频播放对象在播放或暂停状态才能停止播放,在其它状态调用此方法无任何作用。 停止播放后如果需要继续播放,则需调用play方法重新开始播放。

参数:

返回值:

void : 无

示例:


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

seekTo

跳到指定位置播放音频


void player.seekTo( position );
						

说明:

跳到指定位置播放音频,音频播放对象在播放或暂停状态才能跳到指定播放音频,在其它状态调用此方法无任何作用。

参数:

返回值:

void : 无

getDuration

获取音频流的总长度


Number player.getDuration();
						

说明:

获取音频流的总长度,单位为秒,若长度未知则返回-1。如果还未获取到音频流信息则返回NaN,此时需要延迟获取此信息。

参数:

返回值:

Number : 音频流的总长度

getPosition

获取音频流当前播放的位置


Number player.getPosition();
						

说明:

获取音频流当前播放的位置(已播放的长度),单位为s。

参数:

返回值:

Number : 当前音频播放的位置,单位为s,如果音频文件未准备好则返回0。

setRoute

设置音频输出线路


void player.setRoute( route );
						

说明:

可在音频文件开始播放前或播放的过程中改变音频输出线路,默认使用扬声器(plus.audio.ROUTE_SPEAKER)输出线路。

参数:

返回值:

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 );
						

setSessionCategory

设置音频播放模式

说明:

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

参数:

返回值:

void : 无

平台支持:

RecordOptions

JSON对象,调用麦克风设备进行录音的参数

属性:

RecordSuccessCallback

录音操作成功回调


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

说明:

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

参数:

返回值:

void : 无

PlaySuccessCallback

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


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

说明:

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

参数:

返回值:

void : 无

AudioErrorCallback

音频操作失败回调


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

参数:

返回值:

void : 无