音频播放 - Audio
Audio 对象提供音频播放功能,支持本地文件、网络流、项目文件等多种音频源。
源路径格式
Audio 支持以下路径格式:
http://或https://— 网络音频流file://— 文件 URIcontent://— ContentProvider URI- 绝对路径 — 如
/sdcard/music/bg.mp3 project://前缀 — 项目根目录的相对路径(如project://assets/bg.mp3)- 相对路径 — 默认按项目根目录解析
load(source)
参数: source {string} 音频资源路径
返回: {boolean} 是否载入成功
载入音频资源,不会自动播放。播放出口由 setPlayToSpeaker 决定,须在 load 之前调用。
let success = Audio.load('/sdcard/music/bg.mp3');
if (success) {
console.log('音频载入成功');
}play()
返回: {boolean} 是否播放成功
播放当前已加载的音频。
Audio.load('/sdcard/music/bg.mp3');
Audio.play();play(source)
参数: source {string} 音频资源路径
返回: {boolean} 是否成功
加载并播放音频,等同于先调用 load(source) 再调用 play()。
Audio.play('https://example.com/audio/bg.mp3');playAndRelease(source)
参数: source {string} 音频资源路径
返回: {boolean} 是否成功
加载并播放音频,播放结束后自动释放播放器资源。适合一次性的短音频(如提示音)。
Audio.playAndRelease('https://example.com/sfx/ding.mp3');pause()
返回: {boolean} 是否成功
暂停当前播放。
Audio.pause();stop()
返回: {boolean} 是否成功
停止播放,并将播放位置重置到开头。
Audio.stop();release()
返回: {void}
释放播放器资源。释放后如需再次播放需重新 load()。
Audio.release();seekTo(msec)
参数: msec {number} 跳转目标位置(毫秒)
返回: {boolean} 是否成功
跳转到音频的指定位置。
Audio.seekTo(30000); // 跳转到第30秒setLooping(looping)
参数: looping {boolean} 是否循环播放
返回: {boolean} 是否成功
设置是否循环播放当前音频。
Audio.setLooping(true); // 开启循环播放setVolume(leftVolume, rightVolume)
参数:
leftVolume {number}左声道音量,取值范围 0.0 ~ 1.0rightVolume {number}右声道音量,取值范围 0.0 ~ 1.0
返回: {boolean} 是否成功
设置左右声道的音量。
Audio.setVolume(0.8, 0.8); // 左右声道都设置为80%音量isPlaying()
返回: {boolean}
判断当前是否正在播放。
if (Audio.isPlaying()) {
console.log('正在播放');
}isLoaded()
返回: {boolean}
判断是否已加载音频资源。
getDuration()
返回: {number} 音频总时长(毫秒),未加载时返回 -1
获取当前加载的音频总时长。
let duration = Audio.getDuration();
console.log('音频时长:' + duration + 'ms');getCurrentPosition()
返回: {number} 当前播放位置(毫秒),未加载时返回 -1
获取当前播放到的位置。
let position = Audio.getCurrentPosition();
console.log('当前播放位置:' + position + 'ms');getCurrentSource()
返回: {string} 当前加载的音频源路径
获取当前已加载音频的源路径。
canPlayInBackground()
返回: {boolean}
检测是否具备后台播放能力(检查前台服务权限)。
hasForegroundServicePermission()
返回: {boolean}
是否已声明前台服务权限(Android 9+ 推荐使用前台服务来保持后台播放不被系统杀死)。
setPlayToSpeaker(speaker)
参数: speaker {boolean} true 强制内置扬声器;false 优先有线耳机 / 蓝牙外设(默认)
返回: {void}
设置播放出口。须在 load() / play(source) 之前调用,载入时才会生效。
关闭「转录外设」、需要手机麦克风录下扬声器声音时,传 true。走扬声器时会使用闹钟声道,避免抖音等前台应用把媒体音静掉。
Audio.setPlayToSpeaker(true); // 内置扬声器,给麦克风录
Audio.load(url);
Audio.play();boostVolume(percent)
参数: percent {number} 目标音量,取值范围 0 ~ 100
返回: {void}
播放前把对应系统声道临时调到指定百分比,并记住当前系统音量。走扬声器时改闹钟声道,走外设时改媒体声道。同时会申请短暂音频焦点。
Audio.boostVolume(80);restoreVolume()
返回: {void}
恢复 boostVolume 之前的系统音量,并释放音频焦点。建议放在 try/finally 里,播放或录入结束后务必调用。
Audio.restoreVolume();hasAudioOutput()
返回: {boolean} 是否已接入外接音频设备(有线耳机 / USB 耳机 / 蓝牙),不含内置扬声器。Android 9 以下始终返回 true。
启用「转录外设」时,可用此方法判断是否已插入耳机。
if (!Audio.hasAudioOutput()) {
console.log('请插入音频设备');
}完整示例
// 播放项目内的音频文件
if (Audio.play('project://assets/bg_music.mp3')) {
Audio.setLooping(true);
Audio.setVolume(0.5, 0.5);
console.log('开始播放背景音乐');
}
// 暂停和恢复
System.sleep(5000);
Audio.pause();
console.log('已暂停');
System.sleep(2000);
Audio.play();
console.log('已恢复播放');
// 释放资源
Audio.release();// 语音评论:扬声器播放并临时抬音量,结束后恢复
let usePeripheral = false;
if (usePeripheral && !Audio.hasAudioOutput()) {
console.log('请插入音频设备');
} else {
Audio.setPlayToSpeaker(!usePeripheral);
Audio.boostVolume(80);
try {
Audio.load('https://example.com/tts.mp3');
Audio.play();
} finally {
Audio.restoreVolume();
}
}