音频捕获
本指南介绍如何捕获浏览器音频、配置音频格式、接收音频样本以及管理捕获会话。
从 JxBrowser 9.6.0 开始,您可以将 Browser 产生的所有音频捕获为未压缩的 32 位浮点样本。这些样本可用于音频处理、录音或语音识别。
开始捕获
要开始捕获音频,请使用 Audio.startCapture() 方法:
var session = browser.audio().startCapture();
val session = browser.audio.startCapture()
该方法返回一个处于活动状态的 AudioCaptureSession。默认情况下,它以 48,000 Hz 的采样率捕获立体声音频,每个缓冲区包含 1,024 帧,并且播放声音仍然可听见。每帧包含每个声道的一个样本。
一个浏览器只能有一个活动的捕获会话。在另一个会话处于活动状态时调用 startCapture() 会抛出 IllegalStateException。
要从音频开头接收数据,请在页面开始播放之前注册会话的事件观察者。在注册观察者之前捕获的缓冲区不会发送给该观察者。
配置捕获
要更改音频格式,请将 AudioCaptureOptions 传递给 startCapture()。以下示例以 16,000 Hz 的采样率捕获单声道音频,每个缓冲区包含 160 帧(10 毫秒),并在捕获期间将播放静音:
var options = AudioCaptureOptions.newBuilder()
.channelLayout(AudioChannelLayout.MONO)
.sampleRate(16_000)
.framesPerBuffer(160)
.muteSource()
.build();
var session = browser.audio().startCapture(options);
import com.teamdev.jxbrowser.dsl.media.AudioCaptureOptions
...
val options = AudioCaptureOptions(
channelLayout = AudioChannelLayout.MONO,
sampleRate = 16_000,
framesPerBuffer = 160,
muteSource = true
)
val session = browser.audio.startCapture(options)
使用不同选项启动会话之前,请先停止任何活动的会话。您可以通过 session.options() 获取会话使用的选项。
采样率必须在 3,000 到 768,000 Hz 之间。每个缓冲区的帧数必须为正数,缓冲区时长必须在 10 到 500 毫秒之间。设置或构建选项时,无效的值会导致 IllegalArgumentException。如果选项不受支持,startCapture(options) 也会抛出 IllegalArgumentException。
声道布局定义声道的数量和顺序:
| 布局 | 声道顺序 |
|---|---|
MONO | 前中 |
STEREO | 前左、前右 |
QUAD | 前左、前右、后左、后右 |
SURROUND_5_1 | 前左、前右、前中、低频效果、侧左、侧右 |
SURROUND_7_1 | 前左、前右、前中、低频效果、后左、后右、侧左、侧右 |
接收音频数据
订阅捕获会话上的 AudioDataCaptured 事件以接收音频缓冲区:
session.on(AudioDataCaptured.class, event -> {
var channelCount = event.channelCount();
var frameCount = event.frameCount();
var samples = event.channelData(0);
var timestamp = event.timestamp();
// 处理第一个声道的样本。
});
session.subscribe<AudioDataCaptured> { event ->
val channelCount = event.channelCount()
val frameCount = event.frameCount()
val samples = event.channelData(0)
val timestamp = event.timestamp()
// 处理第一个声道的样本。
}
每个声道的样本分别存储。channelData(index) 返回一个新的 float[] 数组(在 Kotlin 中为 FloatArray),其中包含 frameCount() 个样本。声道索引从零开始,遵循所配置声道布局的顺序。
时间戳是一个 java.time.Duration,表示从会话捕获的第一帧到该缓冲区第一帧的时间。通常,相邻时间戳之差等于缓冲区时长。更大的差值表示两个缓冲区之间的音频已丢失。
当浏览器没有播放音频时,会话仍会持续发送包含静音的缓冲区。
播放静音
muteSource 选项仅在捕获会话处于活动状态时将播放静音。它不会影响捕获的样本,也不会更改 Audio.isMuted() 返回的值。
使用 Audio.mute() 将浏览器静音也不会影响捕获的样本。但是,使用 --mute-audio 开关启动 Chromium 会导致捕获的音频为静音。
停止捕获
当您不再需要音频数据时,请停止会话:
session.stop();
session.stop()
使用 session.isActive() 检查会话是否正在捕获音频。对非活动会话调用 stop() 没有任何效果。关闭浏览器会自动停止其捕获会话。
会话停止或失败后,会丢弃尚未开始发送的缓冲区。在该会话上注册观察者会抛出 ObjectClosedException。要恢复捕获,请启动新会话并注册其观察者。前一个会话的事件不会发送给新会话的观察者。
捕获处于活动状态时,Chromium 将浏览器视为可见,因此页面不会受到节流限制,并且其 document.visibilityState 为 visible。捕获还会阻止显示器进入睡眠状态。请在不再需要时停止会话。
捕获失败
要检测捕获失败,请在活动会话上订阅 AudioCaptureFailed:
session.on(AudioCaptureFailed.class, event -> {
System.out.println(event.errorMessage());
});
session.subscribe<AudioCaptureFailed> { event ->
println(event.errorMessage())
}
该事件提供描述失败原因的消息。失败的会话不再处于活动状态,并且无法重复使用。