目录

音频捕获

本指南介绍如何捕获浏览器音频、配置音频格式、接收音频样本以及管理捕获会话。

从 JxBrowser 9.6.0 开始,您可以将 Browser 产生的所有音频捕获为未压缩的 32 位浮点样本。这些样本可用于音频处理、录音或语音识别。

开始捕获 

要开始捕获音频,请使用 Audio.startCapture() 方法:

Java
Kotlin

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 毫秒),并在捕获期间将播放静音:

Java
Kotlin

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 事件以接收音频缓冲区:

Java
Kotlin

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 会导致捕获的音频为静音。

停止捕获 

当您不再需要音频数据时,请停止会话:

Java
Kotlin

session.stop();

session.stop()

使用 session.isActive() 检查会话是否正在捕获音频。对非活动会话调用 stop() 没有任何效果。关闭浏览器会自动停止其捕获会话。

会话停止或失败后,会丢弃尚未开始发送的缓冲区。在该会话上注册观察者会抛出 ObjectClosedException。要恢复捕获,请启动新会话并注册其观察者。前一个会话的事件不会发送给新会话的观察者。

捕获处于活动状态时,Chromium 将浏览器视为可见,因此页面不会受到节流限制,并且其 document.visibilityState 为 visible。捕获还会阻止显示器进入睡眠状态。请在不再需要时停止会话。

捕获失败 

要检测捕获失败,请在活动会话上订阅 AudioCaptureFailed:

Java
Kotlin

session.on(AudioCaptureFailed.class, event -> {
    System.out.println(event.errorMessage());
});

session.subscribe<AudioCaptureFailed> { event ->
    println(event.errorMessage())
}

该事件提供描述失败原因的消息。失败的会话不再处于活动状态,并且无法重复使用。