moq-boy: refactor Rust publisher into Session struct (#1225)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kixelated

rs/moq-boy/src/audio.rs

@@ -1,3 +1,13 @@
+//! Audio encoding pipeline: PCM samples -> resample -> Opus -> MoQ.
+//!
+//! The Game Boy APU outputs unsigned 8-bit stereo PCM at ~44.1kHz.
+//! This module resamples to 48kHz and encodes to Opus (20ms frames)
+//! using ffmpeg-next, then publishes via `moq_mux::import::Opus`.
+//!
+//! Audio timestamps are anchored to the same wall clock as video,
+//! ensuring A/V sync. The epoch is set on the first `push_samples()`
+//! call and reset on pause/resume.
+
 use anyhow::{Context, Result};
 
 /// Audio encoding pipeline: PCM samples -> Opus -> MoQ.
@@ -9,27 +19,40 @@ pub struct AudioEncoder {
 
 	resampler: Option<ffmpeg_next::software::resampling::Context>,
 
-	// Input samples at input_sample_rate, waiting to be resampled.
+	/// Input samples at input_sample_rate, waiting to be resampled.
 	input_buffer: Vec<i16>,
-	// Resampled samples at OPUS_SAMPLE_RATE, waiting to be encoded.
+	/// Resampled samples at OPUS_SAMPLE_RATE, waiting to be encoded.
 	encode_buffer: Vec<i16>,
 
 	frame_size: usize,
 	frame_count: u64,
 	input_sample_rate: u32,
 
-	// Set once on the first push_samples call.
-	// Audio timestamps are: epoch + frame_count * frame_duration.
-	// This ensures exactly contiguous frames with no gaps.
+	/// Set once on the first `push_samples()` call.
+	///
+	/// Audio timestamps are computed as: `epoch + frame_count * frame_duration`.
+	/// This produces exactly contiguous frames with no gaps, regardless of when
+	/// `push_samples()` is called. The epoch accounts for samples already
+	/// buffered (not yet encoded) at the time of initialization:
+	///
+	/// ```text
+	/// epoch = wall_clock_elapsed - (buffered_samples / sample_rate)
+	/// ```
+	///
+	/// This ensures the first encoded frame's PTS matches where it would have
+	/// been if encoding had started from the very beginning.
 	epoch: Option<u64>,
 }
 
-/// Target Opus sample rate.
+/// Target Opus sample rate (standard for Opus).
 const OPUS_SAMPLE_RATE: u32 = 48000;
 /// Opus frame duration: 20ms at 48kHz = 960 samples per channel.
 const OPUS_FRAME_SAMPLES: usize = 960;
-/// GB APU outputs stereo.
+/// Game Boy APU outputs stereo audio.
 const CHANNELS: u32 = 2;
+/// Opus encoding bitrate. 64kbps is reasonable for stereo Game Boy
+/// audio (simple waveforms, limited frequency range).
+const OPUS_BITRATE: usize = 64000;
 
 impl AudioEncoder {
 	pub fn new(
@@ -57,7 +80,7 @@ impl AudioEncoder {
 		));
 		enc.set_channel_layout(ffmpeg_next::ChannelLayout::STEREO);
 		enc.set_time_base(ffmpeg_next::Rational::new(1, OPUS_SAMPLE_RATE as i32));
-		enc.set_bit_rate(64000);
+		enc.set_bit_rate(OPUS_BITRATE);
 
 		let ffmpeg_encoder = enc.open()?;
 		let frame_size = ffmpeg_encoder.frame_size() as usize;
@@ -121,7 +144,6 @@ impl AudioEncoder {
 		// Convert u8 (unsigned, center=128) to i16 (signed, center=0).
 		let i16_samples: Vec<i16> = samples.iter().map(|&s| ((s as i16) - 128) * 256).collect();
 
-		// Count stereo samples from emulator (i16 values / 2 channels).
 		self.input_buffer.extend_from_slice(&i16_samples);
 
 		// Resample input to OPUS_SAMPLE_RATE first, then encode in frame_size chunks.
@@ -131,6 +153,8 @@ impl AudioEncoder {
 		let frame_duration_us = self.frame_size as u64 * 1_000_000 / OPUS_SAMPLE_RATE as u64;
 
 		// Initialize epoch on first call so audio timestamps align with video.
+		// Subtract buffered time so the first frame's PTS accounts for samples
+		// that were accumulated before encoding begins.
 		if self.epoch.is_none() && self.encode_buffer.len() >= samples_per_frame {
 			let buffered_us = self.encode_buffer.len() as u64 * 1_000_000 / (OPUS_SAMPLE_RATE as u64 * CHANNELS as u64);
 			self.epoch = Some((elapsed.as_micros() as u64).saturating_sub(buffered_us));
@@ -165,6 +189,10 @@ impl AudioEncoder {
 		);
 		frame.set_rate(self.input_sample_rate);
 
+		// Copy i16 samples into the frame's byte buffer.
+		// SAFETY: i16 is always 2 bytes, little-endian on all supported platforms.
+		// The source and destination buffers are properly aligned (Vec<i16> guarantees
+		// alignment, and we're reading as bytes which has no alignment requirement).
 		let data = frame.data_mut(0);
 		let bytes: &[u8] =
 			unsafe { std::slice::from_raw_parts(self.input_buffer.as_ptr() as *const u8, self.input_buffer.len() * 2) };
@@ -185,7 +213,10 @@ impl AudioEncoder {
 		);
 		resampler.run(&frame, &mut resampled)?;
 
-		// Extract resampled i16 samples.
+		// Extract resampled i16 samples from the frame's byte buffer.
+		// SAFETY: Same as above — reinterpreting the frame's u8 data as i16.
+		// ffmpeg guarantees the audio data is in s16 packed format (set above),
+		// so the byte layout is valid i16 values.
 		let out_samples = resampled.samples() * CHANNELS as usize;
 		let out_data = resampled.data(0);
 		let out_i16: &[i16] = unsafe { std::slice::from_raw_parts(out_data.as_ptr() as *const i16, out_samples) };
@@ -204,7 +235,7 @@ impl AudioEncoder {
 		frame.set_rate(OPUS_SAMPLE_RATE);
 		frame.set_pts(Some(self.frame_count as i64 * self.frame_size as i64));
 
-		// Copy sample data into the frame.
+		// SAFETY: Same as resample() — copying i16 data as bytes into the frame.
 		let data = frame.data_mut(0);
 		let bytes: &[u8] = unsafe { std::slice::from_raw_parts(samples.as_ptr() as *const u8, samples.len() * 2) };
 		data[..bytes.len()].copy_from_slice(bytes);

rs/moq-boy/src/emulator.rs

@@ -1,11 +1,19 @@
+//! Game Boy Color emulator wrapper.
+//!
+//! Wraps the `boytacean` emulator library, adding per-viewer button tracking
+//! for crowd-control input. A button is pressed on the emulator as long as
+//! at least one viewer is holding it (union semantics — "anarchy mode").
+
 use anyhow::{Context, Result};
 use std::collections::{HashMap, HashSet};
 use std::path::Path;
 
 use boytacean::gb::{AudioProvider, GameBoy, GameBoyMode};
 use boytacean::pad::PadKey;
 
+/// Game Boy native screen width.
 pub const WIDTH: u32 = 160;
+/// Game Boy native screen height.
 pub const HEIGHT: u32 = 144;
 
 /// Game Boy button inputs.
@@ -70,6 +78,8 @@ impl Emulator {
 		gb.load_rom(&rom, None)
 			.map_err(|e| anyhow::anyhow!("failed to load ROM: {e}"))?;
 		gb.load_boot_state();
+		// A=0x11 signals CGB (Color Game Boy) mode to the ROM.
+		// The boot ROM normally sets this, but we skip boot.
 		gb.cpu().a = 0x11;
 
 		Ok(Self {

rs/moq-boy/src/input.rs

@@ -1,3 +1,10 @@
+//! Viewer discovery and command handling.
+//!
+//! Viewers are MoQ publishers: each creates a broadcast under the viewer prefix
+//! with a "command" track containing JSON button states and reset requests.
+//! This module discovers viewer broadcasts and relays their commands to the
+//! emulator thread via an mpsc channel.
+
 use anyhow::Context;
 
 use crate::emulator::Button;