PulseAudioJava

纯 Java 实现的 PulseAudio 客户端，零外部依赖。

特性

• 完整的 PulseAudio 原生协议实现（基于官方源码验证）
• Unix Socket 和 TCP 传输支持
• Cookie 认证
• 录制流和播放流管理
• 通过 Java Sound API 本地音频播放
• JDK 16+，纯 Java，无 JNI

构建

# 需要 Java 16 或更高版本
bash build.sh

# 或手动编译
javac -encoding UTF-8 -d build -sourcepath src/main/java src/main/java/com/pulseaudio/**/*.java

使用

录制系统音频并播放（监听）

java -cp build com.pulseaudio.examples.RecordAndPlayExample

这会把系统所有正在播放的音频捕获并通过本地扬声器输出。

指定音源

# 列出可用音源
pactl list sources short

# 使用特定的 monitor 源
java -cp build com.pulseaudio.examples.RecordAndPlayExample <source_name>

编程使用

// 创建客户端
PulseAudioClient client = PulseAudioClient.create();
client.handshake();  // 连接 + 认证

// 创建录制流
SampleSpec spec = SampleSpec.cdQuality();  // S16LE, 44100Hz, 立体声
RecordStream stream = client.createRecordStream(
    "@DEFAULT_MONITOR@", "myApp", spec, ChannelMap.stereo());

// 设置播放器
AudioPlayer player = new AudioPlayer(spec);
player.start();
stream.setReadCallback((data, off, len) -> player.write(data, off, len));

// 开始接收音频
client.uncorkRecordStream(stream);

// ...播放中...

// 清理
stream.close();
player.close();
client.close();

协议验证

所有协议细节均从 PulseAudio 官方源码验证：

• pstream.c — 帧格式
• tagstruct.h — Tag 序列化
• native-common.h — 命令码
• sample.h — 采样格式
• protocol-native.c — 命令处理

限制

• 不支持 SHM（仅使用内嵌 memblock 传输）
• 协议版本 v13+（PulseAudio 0.9.11+, 2009 年发布）
• Unix Socket 需要 Linux/macOS 运行环境（JDK 16+）
• Windows 下需通过 TCP 连接（PulseAudio 需加载 module-native-protocol-tcp）

包结构

com.pulseaudio/
├── PulseAudioClient          # 主客户端
├── PulseAudioException       # 异常
├── transport/
│   ├── Transport             # 传输接口
│   ├── UnixSocketTransport   # Unix Socket
│   └── TcpTransport          # TCP
├── protocol/
│   ├── ProtocolConstants     # 协议常量
│   ├── Frame                 # 帧
│   ├── FrameReader           # 帧读取
│   ├── FrameWriter           # 帧写入
│   ├── TagStructWriter       # Tag 序列化
│   └── TagStructReader       # Tag 反序列化
├── auth/
│   └── CookieReader          # Cookie 读取
├── audio/
│   ├── SampleFormat          # 采样格式
│   ├── SampleSpec            # 采样规格
│   └── ChannelMap            # 声道映射
├── stream/
│   ├── StreamContext         # 流上下文
│   ├── PlaybackStream        # 播放流
│   └── RecordStream          # 录制流
├── playback/
│   ├── AudioPlayer           # 播放器
│   └── RingBuffer            # 环形缓冲
└── examples/
    └── RecordAndPlayExample  # 使用示例

许可证

AGPLv3 — GNU Affero General Public License v3.0