bookclerk_media::pcm_wire
Frames the host and bookclerk-media-worker pcm exchange over the
worker's stdio.
One worker process decodes one audio file, from a start position to its end, for a player. The worker opens nothing: it asks the host for the byte ranges its demuxer reads and answers with decoded PCM. Each frame is a four-byte big-endian length, then that many bytes of body, which start with a one-byte tag:
| Direction | Frame | Body after the tag |
|---|---|---|
| host → worker | Open (0) |
size: u64, start_ms: u64 |
| host → worker | Data (1) |
offset: u64, then the span's bytes |
| worker → host | Need (0) |
offset: u64, len: u32 |
| worker → host | Format (1) |
sample_rate: u32, channels: u8, start_ms: u64, duration_ms: u64 |
| worker → host | Pcm (2) |
interleaved signed 16-bit samples, little-endian |
| worker → host | End (3) |
nothing |
| worker → host | Failed (4) |
a UTF-8 message of at most MAX_ERROR_BYTES |
Integers in headers are big-endian; samples are little-endian, the
byte order every platform the worker ships on uses natively. A
duration_ms of UNKNOWN_DURATION means the container states none.
The worker parses untrusted files, so the host treats it as compromised:
ReplyReader checks every length and field of each frame, and
ReplyOrder checks the stream as a whole (one Format before any
Pcm, whole frames of samples, nothing after End or Failed). The
host still checks each Need against the file it is reading.
| Item | Kind | Summary |
|---|---|---|
PcmHeader |
struct | The layout of the PCM that follows, and where it starts. |
ReplyReader |
struct | Splits the worker's output into checked replies, fed bytes as they arrive (sans IO: the host's reader task and the fuzz target drive the same code). |
PcmWireError |
enum | Why a frame, or the stream of frames, could not be read. |
PcmRequest |
enum | A frame the host sends the worker. |
PcmReply |
enum | A frame the worker sends the host. |
ReplyOrder |
enum | Where a reply stream is: the rules ReplyOrder::check enforces on top of each frame's own checks. |
body_len |
function | Reads a frame's length prefix. |
encode_request |
function | Encodes a request as a whole frame, length prefix included. |
decode_request |
function | Decodes a request body (the frame without its length prefix). |
encode_reply |
function | Encodes a reply as a whole frame, length prefix included. |
decode_reply |
function | Decodes a reply body (the frame without its length prefix) and checks each field against its limit. |
PCM_WORKER_ARG |
constant | First worker argument that selects the PCM decoder. |
MAX_ERROR_BYTES |
constant | Longest error message a reply carries, in bytes. |
MAX_NEED_BYTES |
constant | Most bytes one Need asks for (1 MiB). |
MAX_PCM_SAMPLES |
constant | Most samples (not frames) one Pcm frame carries: a FLAC block at its largest (65 535 frames) in stereo fits. |
MAX_REQUEST_BODY |
constant | Largest request body: a tag, an offset and one span's bytes. |
MAX_REPLY_BODY |
constant | Largest reply body: a tag and a Pcm frame at its largest. |
UNKNOWN_DURATION |
constant | The duration_ms a Format frame carries when the container states no duration. |
MAX_POSITION_MS |
constant | Longest position or duration a Format frame may state, in milliseconds: sixty days, the playback core's own limit. |
pub struct PcmHeader {
pub sample_rate: u32,
pub channels: u8,
pub start_ms: u64,
pub duration_ms: Option<u64>,
}
The layout of the PCM that follows, and where it starts.
Fields
sample_rate: Samples per second per channel, in Hz; 1 toMAX_SAMPLE_RATE_HZ.channels: Interleaved channels in everyPcmframe: 1 or 2.start_ms: Where the first sample sits in the file, in milliseconds: the asked-for start, or the packet boundary before it.duration_ms: The file's length in milliseconds, when the container states one.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ReplyReader {
/* private fields */
}
Splits the worker's output into checked replies, fed bytes as they arrive (sans IO: the host's reader task and the fuzz target drive the same code).
pub fn push(&mut self, bytes: &[u8])
Appends bytes read from the worker.
pub fn buffered(&self) -> usize
Bytes held that are not yet a whole frame.
pub fn next_reply(&mut self) -> Result<Option<PcmReply>, PcmWireError>
Takes the next whole reply, if one has arrived.
None until a whole frame is buffered.
PcmWireError::TooLarge as soon as a length prefix is over
MAX_REPLY_BODY, or what decode_reply returns. The reader is
then broken and returns that error from every later call.
Implements: Debug, Default
pub enum PcmWireError {
Truncated,
Trailing,
TooLarge,
UnknownTag(u8),
BadSpan,
BadFormat,
BadSamples,
BadMessage,
OutOfOrder(&'static str),
}
Why a frame, or the stream of frames, could not be read.
Variants
Truncated: The body ended before a field it promised.Trailing: The body has bytes after its last field.TooLarge: The body is over the frame's size cap.UnknownTag: The tag byte is not one this direction uses.BadSpan: ANeedfor no bytes, more thanMAX_NEED_BYTES, or a span that overflows.BadFormat: AFormatwith a rate outside 1 toMAX_SAMPLE_RATE_HZ, a channel count other than 1 or 2, or a position or duration overMAX_POSITION_MS.BadSamples: APcmframe with no samples, more thanMAX_PCM_SAMPLES, or an odd byte count.BadMessage: An error message that is not UTF-8 or is too long.OutOfOrder: A frame out of order:PcmbeforeFormat, a secondFormat, a partial frame of samples, or anything afterEndorFailed.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub enum PcmRequest {
Open { size: u64, start_ms: u64 },
Data { offset: u64, bytes: Vec<u8> },
}
A frame the host sends the worker.
Variants
Open: Start decoding a file ofsizebytes fromstart_ms. The first frame on the worker's stdin, and only once.size: The file's size in bytes.start_ms: Where to start, in milliseconds from the start of the file.
Data: The bytes of the span the worker last asked for.offset: The span's offset.bytes: The span's bytes.
Implements: Clone, Debug, Eq, PartialEq
pub enum PcmReply {
Need { offset: u64, len: u32 },
Format(PcmHeader),
Pcm(Vec<i16>),
End,
Failed { message: String },
}
A frame the worker sends the host.
Variants
Need: Send this span of the file.offset: The span's offset.len: Its length in bytes: 1 toMAX_NEED_BYTES.
Format: The PCM layout; sent once, before the firstPcm.Pcm: Decoded samples, interleaved, a whole number of frames.End: The file decoded to its end; the worker exits.Failed: The file could not be decoded; the worker exits.message: Why, for logs; at mostMAX_ERROR_BYTES.
Implements: Clone, Debug, Eq, PartialEq
pub enum ReplyOrder {
Opening,
Streaming(PcmHeader),
Done,
}
Where a reply stream is: the rules ReplyOrder::check enforces on top
of each frame's own checks.
Variants
Opening: NoFormatyet: onlyNeed,FormatorFailedmay come.Streaming: Streaming samples in the stated layout.Done:EndorFailedcame; nothing more may.
pub fn check(&mut self, reply: &PcmReply) -> Result<(), PcmWireError>
Checks that reply may come next and moves past it.
PcmWireError::OutOfOrder for Pcm or End before Format, a
second Format, samples that are not a whole number of frames, or
any frame after End or Failed. The order is then
ReplyOrder::Done.
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub fn body_len(prefix: [u8; 4]) -> usize
Reads a frame's length prefix.
The body length in bytes.
pub fn encode_request(request: &PcmRequest) -> Result<Vec<u8>, PcmWireError>
Encodes a request as a whole frame, length prefix included.
PcmWireError::TooLarge when a Data span is over
MAX_NEED_BYTES.
pub fn decode_request(body: &[u8]) -> Result<PcmRequest, PcmWireError>
Decodes a request body (the frame without its length prefix).
A PcmWireError for a body that is too large, truncated, has
trailing bytes or an unknown tag.
pub fn encode_reply(reply: &PcmReply) -> Result<Vec<u8>, PcmWireError>
Encodes a reply as a whole frame, length prefix included.
An error message is cut to MAX_ERROR_BYTES at a character boundary.
PcmWireError::BadSamples for a Pcm frame with no samples or more
than MAX_PCM_SAMPLES.
pub fn decode_reply(body: &[u8]) -> Result<PcmReply, PcmWireError>
Decodes a reply body (the frame without its length prefix) and checks each field against its limit.
A PcmWireError for a body that is too large, truncated, has
trailing bytes or an unknown tag, or carries a field out of bounds.
pub const PCM_WORKER_ARG: &str = "pcm";
First worker argument that selects the PCM decoder.
pub const MAX_ERROR_BYTES: usize = 1024;
Longest error message a reply carries, in bytes.
pub const MAX_NEED_BYTES: u32 = _;
Most bytes one Need asks for (1 MiB).
pub const MAX_PCM_SAMPLES: usize = _;
Most samples (not frames) one Pcm frame carries: a FLAC block at its
largest (65 535 frames) in stereo fits.
pub const MAX_REQUEST_BODY: usize = _;
Largest request body: a tag, an offset and one span's bytes.
pub const MAX_REPLY_BODY: usize = _;
Largest reply body: a tag and a Pcm frame at its largest.
pub const UNKNOWN_DURATION: u64 = u64::MAX;
The duration_ms a Format frame carries when the container states
no duration.
pub const MAX_POSITION_MS: u64 = _;
Longest position or duration a Format frame may state, in
milliseconds: sixty days, the playback core's own limit.
Generated from crates/bookclerk-media at main · View as Markdown