bookclerk_player_engine
Native playback for the desktop window.
The window's custom scheme cannot stream audio by Range, so the window
does not play through its webview. The decoding happens in the confined
media worker (bookclerk_media::MediaPool::open_pcm); this crate does
what is left, all of it trusted signal processing on PCM:
- [
Stretcher]: speed change without a pitch change (WSOLA). - [
Resampler]: the book's sample rate to the output device's. - [
Renderer]: both, plus channel mapping, pulled by the device. - [
TrackPlayer]: one track at a time, fed from aTrackOpener, withPlayerEvents for the page that drives it.
Nothing here touches an audio device or the OS: the desktop crate owns the output stream and the system media controls, so this crate builds and tests everywhere.
Style: docs/contributing/code-documentation.md. Design: the playback
ADR, docs/adr/playback.md.
| Item | Kind | Summary |
|---|---|---|
TrackOpener |
trait | Opens tracks. |
TrackStream |
trait | One track's decoded samples from a start position. |
TrackHeader |
struct | The layout and start of a decoded stream. |
TrackPlayer |
struct | A one-track player over a shared Renderer. |
OutputFormat |
struct | The output device's layout. |
Renderer |
struct | The playback pipeline between the decoder and the device. |
Resampler |
struct | A converter for one stream of interleaved samples. |
Stretcher |
struct | A speed changer for one stream of interleaved samples. |
PlayerEvent |
enum | What the player reports, in the order it happens. |
MAX_SPEED |
constant | Fastest speed accepted. |
MIN_SPEED |
constant | Slowest speed accepted. |
pub trait TrackOpener: Send + Sync + 'static {
type Stream: TrackStream;
fn open(
&self,
track: &str,
start_ms: u64,
) -> impl Future<Output = Result<Self::Stream, String>> + Send;
}
Opens tracks.
type Stream: TrackStream
What an opened track streams.
fn open(
&self,
track: &str,
start_ms: u64,
) -> impl Future<Output = Result<Self::Stream, String>> + Send
Opens track from start_ms.
Why the track cannot be played, in words for the listener.
pub trait TrackStream: Send + 'static {
fn header(&self) -> TrackHeader;
fn next_chunk(&mut self) -> impl Future<Output = Option<Result<Vec<i16>, String>>> + Send;
}
One track's decoded samples from a start position.
fn header(&self) -> TrackHeader
The stream's layout and start.
fn next_chunk(&mut self) -> impl Future<Output = Option<Result<Vec<i16>, String>>> + Send
The next chunk of interleaved samples; None at the end.
Why the rest cannot be decoded, in words for a log.
pub struct TrackHeader {
pub sample_rate: u32,
pub channels: u16,
pub start_ms: u64,
pub duration_ms: Option<u64>,
}
The layout and start of a decoded stream.
Fields
sample_rate: Decoded frames per second.channels: Decoded channels: 1 or 2.start_ms: Where the first sample lies on the track, in milliseconds.duration_ms: The track's length in milliseconds, when known.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct TrackPlayer<O: TrackOpener> {
/* private fields */
}
A one-track player over a shared Renderer.
pub fn new(
opener: O,
renderer: Arc<Mutex<Renderer>>,
runtime: &Handle,
) -> (Self, UnboundedReceiver<PlayerEvent>)
A player that opens tracks with opener and feeds renderer.
opener- Opens a track's decoded stream.renderer- The pipeline the device pulls from.runtime- Where the feeder and the clock run.
The player, and the receiving end of its events.
pub fn load(&self, track: &str, start_ms: u64)
Loads track and positions it at start_ms, keeping play or
pause as it was. Replaces any track loaded before.
pub fn seek(&self, position_ms: u64)
Moves to position_ms in the loaded track.
pub fn play(&self)
Plays the loaded track (or, after its end, plays it again from the start).
pub fn pause(&self)
Pauses.
pub fn set_speed(&self, speed: f32)
Sets the speed (0.5 to 3; anything else is clamped).
pub fn stop(&self)
Unloads the track and stops.
pub fn position_ms(&self) -> u64
The position in the loaded track, in milliseconds.
Implements: Debug, Drop
pub struct OutputFormat {
pub sample_rate: u32,
pub channels: u16,
}
The output device's layout.
Fields
sample_rate: Frames per second the device plays.channels: Interleaved channels the device takes; at least 1.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct Renderer {
/* private fields */
}
The playback pipeline between the decoder and the device.
pub fn new(output: OutputFormat) -> Self
A renderer for a device with output's layout, paused, at speed 1.
pub fn output(&self) -> OutputFormat
The device's layout.
pub fn begin(&mut self, sample_rate: u32, channels: u16, start_ms: u64) -> u64
Starts a new stream, dropping any before it.
sample_rate- The decoded rate, at least 1.channels- Decoded channels: 1 or 2.start_ms- Where the first sample lies on the track.
The stream's generation, which Self::push and
Self::finish_input must name.
pub fn clear(&mut self)
Drops the stream: the device hears silence until the next begins. A decoder still pushing to it is ignored.
pub fn push(&mut self, generation: u64, samples: &[i16]) -> bool
Adds decoded samples to the stream of generation.
False when that stream was replaced or cleared.
pub fn finish_input(&mut self, generation: u64)
Marks the end of the stream of generation's input.
pub fn set_speed(&mut self, speed: f32)
Changes the speed, clamped to what the stretcher allows.
pub fn set_playing(&mut self, playing: bool)
Plays or pauses; paused, the device hears silence and the position holds.
pub fn is_ended(&self) -> bool
Whether the stream played out to its end.
pub fn buffered_ms(&self) -> u64
Decoded audio held and not yet played, in milliseconds of the track.
pub fn position_ms(&self) -> Option<u64>
Where the output has got to on the track, in milliseconds; None
with no stream.
pub fn render(&mut self, out: &mut [f32])
Fills one device buffer (interleaved in the device's channels).
Anything not filled from the stream is silence: while paused, with no stream, while the decoder catches up, or after the end.
Implements: Debug
pub struct Resampler {
/* private fields */
}
A converter for one stream of interleaved samples.
pub fn new(from_rate: u32, to_rate: u32, channels: usize) -> Self
A converter from from_rate to to_rate for channels channels.
pub fn push(&mut self, samples: &[f32])
Adds input samples (a whole number of frames).
pub fn pull(&mut self, out: &mut Vec<f32>, max_frames: usize, flush: bool) -> usize
Converts what the held input allows into out, up to max_frames.
out- Where converted samples go.max_frames- Most output frames to make.flush- The input ended: treat what lies past it as silence.
Frames made.
pub fn pending_frames(&self) -> u64
Input frames held that output has not covered yet.
Implements: Debug
pub struct Stretcher {
/* private fields */
}
A speed changer for one stream of interleaved samples.
pub fn new(sample_rate: u32, channels: usize) -> Self
A stretcher for channels interleaved channels at sample_rate,
at speed 1.
sample_rate- Frames per second, at least 1.channels- Interleaved channels, at least 1.
pub fn speed(&self) -> f32
The current speed.
pub fn set_speed(&mut self, speed: f32)
Changes the speed, clamped to MIN_SPEED..=MAX_SPEED. The
change applies from the next segment; samples already made keep the
old speed.
pub fn push(&mut self, samples: &[f32])
Adds decoded samples (a whole number of frames).
pub fn finish(&mut self)
Marks the end of the input: what is left is played out.
pub fn buffered_frames(&self) -> u64
Input frames held and not yet played.
pub fn source_frames(&self) -> f64
Absolute input frames the output pulled so far stands for.
pub fn is_drained(&self) -> bool
Whether the input ended and everything has been pulled.
pub fn pull(&mut self, out: &mut Vec<f32>, max_frames: usize) -> usize
Moves up to max_frames stretched frames into out.
Frames moved; fewer than asked when more input is needed (or it ended).
Implements: Debug
pub enum PlayerEvent {
Loaded { duration_ms: Option<u64>, position_ms: u64 },
Time { position_ms: u64 },
Playing,
Paused,
Ended,
Error { message: String },
}
What the player reports, in the order it happens.
Variants
Loaded: A track's stream opened: its length, when known, and where it starts.duration_ms: The track's length in milliseconds.position_ms: Where playback starts on the track, in milliseconds.
Time: The position while playing, about four times a second, and after each seek.position_ms: Milliseconds into the track.
Playing: Playback started or resumed.Paused: Playback paused.Ended: The track played to its end; the player is paused.Error: The track could not be opened or decoded further; the player is paused.message: What went wrong, for the listener.
Implements: Clone, Debug, PartialEq
pub const MAX_SPEED: f32 = 3.0;
Fastest speed accepted.
pub const MIN_SPEED: f32 = 0.5;
Slowest speed accepted.
Generated from crates/bookclerk-player-engine at main · View as Markdown