bookclerk_media
Clear-media packaging: remux, metadata fix-up, and MP3 encode.
Host acquire / media-worker code. Store plugins may call helpers that are
re-exported here, but DRM (Adrm / CENC) stays in those plugins. The
ISO-BMFF reading and writing underneath is bookclerk_mp4, which both this
crate and those plugins share; the keys and ciphers stay with the plugin.
Style: docs/contributing/code-documentation.md. Product narrative: docs/server/media.md.
The async entry points in this module do not decode anything themselves.
They build a MediaJob and hand it to a MediaPool, which runs it in a
short-lived child process confined to the paths that job declared. Hosts
install the pool once at startup with init_pool; anything that skips
that gets a default pool, which still isolates as long as the worker binary
is installed alongside the host.
The synchronous functions (remux_trimmed, align_chapter_starts,
package_m4b_from_pcm, and the MP4 parsing helpers) run in-process by
design. They are cheap, take already-parsed input, or are the implementation
the worker itself calls.
| Item | Kind | Summary |
|---|---|---|
RangeSource |
trait | Where a file's bytes come from: a local file, a storage plugin's ranged read, or a buffer in tests. |
PcmFormat |
struct | The PCM layout of a decoded stream. |
ChapterAlignOptions |
struct | Tunables for silence / speech-onset chapter snapping. |
FixupRequest |
struct | Request to fix up audiobook metadata after decrypt / download. |
OpusEncodeOptions |
struct | How an Opus copy is encoded. |
PackageM4bRequest |
struct | Request to package ordered MP3 parts into one M4B. |
PcmStream |
struct | Decoded samples of one file from one start position. |
MediaPool |
struct | Bounded pool of confined media workers. |
MediaPoolConfig |
struct | Pool sizing and isolation settings. |
AudioProbe |
struct | What a probe found in one audio file. |
FileRange |
struct | A file on this machine, read a range at a time. |
MediaOutcome |
struct | Outcome of a successful media operation. |
OutChannels |
enum | How many channels the caller wants decoded PCM in. |
MediaError |
enum | Errors from in-process codecs, MP4 plumbing, and confined media workers. |
MediaJob |
enum | A single codec operation. |
MediaJobOutput |
enum | What a finished job produced. |
MediaJobReply |
enum | Wire form of a finished job. Result is not Serialize, so the worker and the pool exchange this instead. |
Confinement |
enum | How strictly a worker must be confined before it will process a job. |
decode_pcm_bytes |
function | Decodes a whole media file held in memory to PCM, the path the media_decode fuzz target and its replay test drive. |
write_output_within_budget |
function | Appends data only when the result stays within max. |
check_archive_report |
function | Checks a worker's report against the limits and the files on disk. |
extract_archive |
function | Expands input into the empty folder output_dir in a confined media worker, then checks the result. |
align_chapter_starts |
function | Snap chapter starts just before nearby speech onsets (spoken chapter titles). |
scale_chapters_to_duration |
function | Scale rebased chapter starts so they span the probed plain-audio duration. |
bookclerk_tool_tag |
function | bookclerk <version> string embedded in encoder / freeform TOOL tags. |
fixup_audiobook |
function | Apply metadata tags, optional cover embed, and optional chapters. |
package_keeping_codec |
function | Packages parts into one M4B at output keeping their audio, with a chapter at the start of each part titled from titles. |
remux_trimmed |
function | Remux a progressive clear M4B/M4A with an optional media-time trim (chapter split). |
encode_to_opus_native |
function | Encodes the audio in input to an Ogg Opus file at output. |
package_m4b_from_mp3 |
function | Decode/remux ordered parts → progressive M4B. |
package_m4b_from_pcm |
function | Encode interleaved PCM to AAC-LC and mux an M4B (test / internal helper). |
serve_pcm |
function | Serves one PCM decode over input and output (the worker's stdin and stdout): reads Open, then streams Format, Pcm frames and End, or Failed when the file cannot be decoded. |
init_pool |
function | Install the process-wide pool if none is installed yet. |
init_pool_from_config |
function | Build the pool from [media] config and install it, logging what it will do. |
pool |
function | The process-wide pool, creating a default one if startup never installed it. |
replace_pool |
function | Swap in pool, returning the one it replaced. |
encode_to_mp3 |
function | Re-encode audio to MP3 via Symphonia + LAME (classic Libation DecryptToLossy). |
encode_to_opus |
function | Encode audio to Ogg Opus via Symphonia + libopus. |
remux_trimmed_async |
function | Copy/trim a progressive M4B/M4A into a new file (chapter split helper). |
align_chapter_starts_async |
function | Snap chapter starts to spoken-title onsets by local waveform analysis. |
Result |
type alias | Result alias for media packaging and worker operations in this crate. |
MAX_SAMPLE_RATE_HZ |
constant | Highest sample rate a decoded stream may report, in Hz. Anything above is refused as malformed rather than handed to an encoder. |
COVER_THREADS_ENV |
constant | Environment variable carrying the cover worker's decode thread count. |
COVER_WORKER_ARG |
constant | First worker argument that selects the cover server. |
BOOKCLERK_TOOL_NAME |
constant | Product / CLI name written into tool attribution tags. |
MAX_OPUS_KBPS |
constant | Highest bitrate an Opus copy is encoded at, in kbit/s (per stream; the Opus limit for stereo). |
MIN_OPUS_KBPS |
constant | Lowest bitrate an Opus copy is encoded at, in kbit/s. |
JAIL_BIN_ENV |
constant | Environment variable naming the jail launcher (shared with plugin hosts). |
JAIL_BIN_NAME |
constant | File name of the jail launcher when it sits beside the host / worker. |
WORKER_BIN_ENV |
constant | Environment variable naming the worker binary explicitly. |
WORKER_BIN_NAME |
constant | File name of the worker binary when it sits beside the host executable. |
WORKER_ENFORCEMENT_ENV |
constant | Environment variable the pool sets on each worker to select its failure mode. |
TAG_WORKER_ARG |
constant | First worker argument that selects the tag reader. |
bookclerk_cover::CoverSetbookclerk_cover::CoverSizebookclerk_mp4::brand_durations_from_chapter_infobookclerk_mp4::brand_trim_rangebookclerk_mp4::rebase_chapters_after_brand_trimbookclerk_mp4::runtime_length_ms_from_chapter_infobookclerk_mp4::BrandDurationsbookclerk_mp4::extract_mp4a_configbookclerk_mp4::parse_mp4bookclerk_mp4::track_duration_msbookclerk_mp4::Mp4aConfigbookclerk_mp4::SampleEntryKindbookclerk_mp4::TrimRangebookclerk_tags::ByteSpanbookclerk_tags::TagRecordpcm_wire::PcmHeaderpcm_wire::PCM_WORKER_ARG
capabilities: What this build of the media worker can read and write.pcm_wire: Frames the host andbookclerk-media-worker pcmexchange over the worker's stdio.
pub trait RangeSource: Send + Sync {
fn read_range(&self, span: ByteSpan) -> impl Future<Output = Result<Vec<u8>>> + Send;
}
Where a file's bytes come from: a local file, a storage plugin's ranged read, or a buffer in tests.
fn read_range(&self, span: ByteSpan) -> impl Future<Output = Result<Vec<u8>>> + Send
Reads exactly span from the file.
span- Lies inside the file; the host checked it.
Any I/O failure; the read of that file then fails.
Implemented by: FileRange
pub struct PcmFormat {
pub sample_rate: u32,
pub channels: u16,
}
The PCM layout of a decoded stream.
Fields
sample_rate: Samples per second per channel, in Hz; between 1 andMAX_SAMPLE_RATE_HZ.channels: Interleaved channels in every chunk: 1 (mono) or 2 (stereo).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ChapterAlignOptions {
pub window_ms: u64,
pub min_silence_ms: u64,
pub frame_ms: u64,
pub silence_rms_floor: f32,
pub silence_rms_ratio: f32,
pub max_lead_in_ms: u64,
pub vocal_low_hz: f32,
pub vocal_high_hz: f32,
}
Tunables for silence / speech-onset chapter snapping.
Fields
window_ms: Search window on each side of the expected chapter start.min_silence_ms: Minimum contiguous quiet frames before a speech onset counts.frame_ms: RMS frame size used for energy analysis.silence_rms_floor: Absolute speech-band RMS floor (s16) treated as quiet.silence_rms_ratio: Fraction of window median speech-band RMS used as the quiet threshold.max_lead_in_ms: Maximum ms to place the marker before the spoken-title onset. The marker stops earlier when walking back would hit prior vocal energy.vocal_low_hz: Bandpass low cutoff for vocal detection (Hz).vocal_high_hz: Bandpass high cutoff for vocal detection (Hz).
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Serialize
pub struct FixupRequest {
pub input: PathBuf,
pub output: PathBuf,
pub title: String,
pub author: Option<String>,
pub narrator: Option<String>,
pub cover: Option<PathBuf>,
pub chapters: Vec<(String, u64)>,
pub replace_chapters: bool,
pub subtitle: Option<String>,
pub publisher: Option<String>,
pub year: Option<String>,
pub genre: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub description: Option<String>,
pub language: Option<String>,
pub tool: Option<String>,
}
Request to fix up audiobook metadata after decrypt / download.
Fields
input: Absolute path of the clear media file to tag (copied/written to output).output: Absolute path where the tagged file should be written.title: Primary title embedded in the container tags.author: Author / artist tag when known.narrator: Narrator tag when known (ABS / iTunes freeform).cover: Optional cover image path to embed (JPEG/PNG).chapters: Chapter titles + start offsets in milliseconds, embedded as a QuickTime chapter track in an M4B and as ID3CHAP/CTOCframes in an MP3.replace_chapters: When true, replace any chapters the file already has (an M4B chapter list/track, or MP3CHAP/CTOCframes) withSelf::chapters(used when overlaying Audible chapter trees onto Libro packaged M4Bs). When false, preserve existing chapters if the file already has them.subtitle: Subtitle / album subtitle when known.publisher: Publisher imprint for the publisher tag.year: Publish year as a string (e.g."2011").genre: Genre string; multiple genres should use;separators for ABS.series: Series name written to Tone / ABS freeform atoms when set.series_index: Series sequence string (e.g."1") for ABS freeform atoms.asin: Amazon ASIN written to freeform metadata when set.isbn: ISBN written to freeform metadata when set.description: Long description / comment body when set.language: Content language tag when set.tool: Tool attribution (bookclerk 0.1.0). Defaults tobookclerk_tool_tagwhenNone.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct OpusEncodeOptions {
pub bitrate_kbps: u16,
pub mono: bool,
}
How an Opus copy is encoded.
Fields
bitrate_kbps: Target bitrate in kbit/s, betweenMIN_OPUS_KBPSandMAX_OPUS_KBPS(others are clamped). Opus encodes in variable bitrate around it.mono: Mix down to one channel.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PackageM4bRequest {
pub parts: Vec<PathBuf>,
pub output: PathBuf,
pub chapter_titles: Vec<String>,
pub keep_codec: bool,
}
Request to package ordered MP3 parts into one M4B.
Fields
parts: Ordered MP3 chapter / part files.output: Destination.m4bpath.chapter_titles: Optional chapter titles (length may matchparts).keep_codec: Keep Opus, FLAC, ALAC, E-AC-3 or AC-4 audio as it is inside the M4B instead of encoding it to AAC (output.keep_codec_in_m4b). Parts that cannot be kept together are encoded to AAC as usual.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct PcmStream {
/* private fields */
}
Decoded samples of one file from one start position.
Dropping it stops the worker.
pub fn header(&self) -> PcmHeader
The sample rate, channels, actual start and stated duration.
pub async fn next_chunk(&mut self) -> Option<Result<Vec<i16>>>
The next chunk of interleaved samples: a whole number of frames in
Self::header's layout.
None once the file decoded to its end.
MediaError::Native when the worker could not decode the rest,
MediaError::Io when the source failed, and
MediaError::Worker when the worker died, stalled or broke the
protocol. The stream ends after an error.
Implements: Debug, Drop
pub struct MediaPool {
/* private fields */
}
Bounded pool of confined media workers.
pub fn new(config: MediaPoolConfig) -> Self
Build a pool from config, resolving the worker binary once.
Resolution failures are recorded rather than returned, so a
misconfigured host still starts and reports the problem through
summary and its logs. The refusal happens per job.
pub fn in_process() -> Self
A pool that runs every job on a blocking thread in this process.
pub fn capacity(&self) -> usize
Maximum jobs this pool will run at once.
pub fn is_isolated(&self) -> bool
Whether jobs run in a separate, confined process.
pub fn is_refusing(&self) -> bool
Whether this pool will refuse every job because isolation is required but unavailable.
pub fn worker_bin(&self) -> Option<&PathBuf>
Resolved worker binary, when one was found.
pub fn summary(&self) -> String
One-line summary for startup logs and bookclerk doctor.
pub async fn process_cover(&self, cover: Vec<u8>) -> Result<CoverSet>
Turns one untrusted downloaded cover image into the JPEG sizes the host serves.
Covers do not take a job slot: they run on one long-lived worker (jailed to no path and no network) that decodes on as many threads as this pool has workers, so search results do not queue behind an acquire.
cover- The downloaded bytes, at mostbookclerk_cover::MAX_INPUT_BYTES.
MediaError::Cover when the image is refused or takes longer than
30 s, MediaError::NotIsolated when isolation is required but no
worker was found, and MediaError::Worker when the worker cannot be
started or dies.
pub async fn read_tags<S: RangeSource>(&self, size: u64, source: &S) -> Result<TagRecord>
Reads the metadata embedded in one untrusted media file (tags.read):
text tags, chapters, running time, where the cover lies, and a digest
of the metadata region.
Tag reads do not take a job slot: they run on one long-lived worker,
jailed to no path and no network, that asks for the byte ranges it
needs, which this call fetches from source. Only the metadata region
and a few headers are fetched, never the audio. Read a page of files
by awaiting several calls at once; up to 16 files are read at a time.
size- The file's size in bytes.source- Where its bytes come from (a local file, a storage plugin's ranged read).
MediaError::Tags when the file is not an MP4, MP3 or FLAC file or
is malformed, MediaError::Io when source fails,
MediaError::NotIsolated when isolation is required but no worker
was found, and MediaError::Worker when the worker cannot be
started, dies, stalls for 30 s, or answers outside the reader's
limits (the worker is then restarted).
pub async fn open_pcm<S: RangeSource + 'static>(
&self,
size: u64,
start_ms: u64,
source: S,
) -> Result<PcmStream>
Decodes one audio file to PCM for a player, from start_ms to its
end (bookclerk-media-worker pcm).
Each call starts its own worker, jailed to no path and no network,
which asks for the byte ranges its demuxer reads; this call fetches
them from source. It does not take a job slot. The stream holds
at most a few chunks ahead of the player, so a paused player keeps
the worker waiting rather than decoding the whole book. Seeking is a
new call; dropping the stream stops its worker. With isolation off,
playback is refused, never decoded in this process.
size- The file's size in bytes.start_ms- Where to start, in milliseconds into the file.source- Where its bytes come from.
MediaError::NotIsolated when isolation is off or no worker was
found, MediaError::Native when the file cannot be decoded,
MediaError::Io when source fails, and MediaError::Worker
when the worker cannot be started, stalls for 30 s before its
format, or breaks the protocol.
pub async fn run(&self, job: MediaJob) -> Result<MediaJobOutput>
Run job, waiting for a free slot first.
Returns MediaError::NotIsolated when confinement is required but no
worker binary was found, MediaError::Worker when the worker cannot
be started, exits without a reply, or returns something unparseable,
and propagates the job's own error otherwise.
pub async fn probe_file(&self, path: &Path) -> Result<AudioProbe>
Probes the audio file at path on this machine.
crate::MediaError::Io when the file cannot be read, and every
error of [Self::read_tags]: the file is not MP4, MP3 or FLAC, or
isolation is required and no worker was found.
Implements: Debug, Default, Drop
pub struct MediaPoolConfig {
pub workers: usize,
pub confinement: Confinement,
pub worker_bin: Option<PathBuf>,
}
Pool sizing and isolation settings.
Fields
workers: Maximum jobs running at once. Zero means "derive from available parallelism".confinement: How strictly workers must be confined.worker_bin: Explicit worker binary path. When absent the pool looks atWORKER_BIN_ENVand then beside the current executable.
Implements: Clone, Debug, Default, Eq, From<&MediaConfig>, PartialEq
pub struct AudioProbe {
pub content_type: &'static str,
pub bitrate_kbps: Option<u32>,
pub lossless: bool,
pub codec: Option<AudioCodec>,
pub format: AudioFormat,
pub duration_ms: Option<u64>,
}
What a probe found in one audio file.
Fields
content_type: Media type of the container (audio/mp4,audio/mpeg,audio/flac).bitrate_kbps: Average bitrate in kilobits per second: the file's size over its running time, cover and tags included.Nonewhen the file states no running time.lossless: True when the audio encoding is lossless (FLAC, ALAC). An MP4 file whose encoding the reader does not know counts as lossy.codec: The audio encoding, when the tag reader knows it.format: Channels, sample rate and AAC profile, as far as the headers state them.duration_ms: The running time a player sees, in milliseconds, as the container states it (an MP4's movie duration, which edit lists shape; an Opus stream's samples past its pre-skip).Nonewhen the file states none, never zero.
pub fn from_record(size: u64, record: &TagRecord) -> Self
The probe of a file of size bytes whose tags read as record.
Implements: Clone, Debug, Eq, PartialEq
pub struct FileRange {
/* private fields */
}
A file on this machine, read a range at a time.
pub fn new(path: &Path) -> Self
A source over the file at path. Nothing is opened until a range is
read.
Implements: Clone, Debug, RangeSource
pub struct MediaOutcome {
pub output: PathBuf,
}
Outcome of a successful media operation.
Fields
output: Absolute path of the written media file.
Implements: Clone, Debug, From<MediaJobOutput>
pub enum OutChannels {
SourceUpToStereo,
Mono,
}
How many channels the caller wants decoded PCM in.
Variants
SourceUpToStereo: The source's own count, folded to stereo when it has more than two.Mono: One channel: the average of the source's first two.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum MediaError {
InputMissing(PathBuf),
OutputMissing(PathBuf),
Mp4(String),
Native(String),
Worker { job: &'static str, detail: String },
NotIsolated { job: &'static str, detail: String },
Cover(String),
Tags(String),
Archive(String),
Io(Error),
Other(Error),
}
Errors from in-process codecs, MP4 plumbing, and confined media workers.
Variants
InputMissing: A declared input path does not exist or is unreachable.OutputMissing: The job reported success but the expected output path was not written.Mp4: ISO-BMFF / MP4 container parse or remux failure.Native: Native encode / remux / metadata failure (non-container detail).Worker: A media worker process could not be started, died, or returned a reply that could not be parsed. Distinct fromMediaError::Nativeso a crashed codec is not mistaken for a malformed file.job: Which operation was running.detail: What went wrong.
NotIsolated: Isolation is required but unavailable, so the job was refused rather than run unconfined. Separate fromMediaError::Workerbecause nothing went wrong at runtime — the host is misconfigured.job: Which operation was refused.detail: Why isolation is unavailable.
Cover: A cover image was refused: not a supported image, too large, or undecodable. The message comes from the cover pipeline.Tags: A file's embedded tags could not be read: not an MP4, MP3 or FLAC file, or a malformed one. The message comes from the tag reader.Archive: An uploaded archive could not be expanded, or the worker's report of the expansion did not hold up when the host checked it.Io: Local filesystem I/O failure.Other: Catch-all for wrapped media failures.
Implements: Debug, Display, Error, From<Error>, From<Mp4Error>
pub enum MediaJob {
EncodeMp3 { input: PathBuf, output: PathBuf, lame: Box<LameConfig>, max_sample_rate: Option<u32>, max_output_bytes: Option<u64> },
EncodeOpus { input: PathBuf, output: PathBuf, options: OpusEncodeOptions, max_output_bytes: Option<u64> },
RemuxTrimmed { input: PathBuf, output: PathBuf, trim: TrimRange },
Fixup { request: Box<FixupRequest> },
PackageM4b { request: Box<PackageM4bRequest> },
AlignChapters { path: PathBuf, chapters: Vec<(String, u64)>, options: ChapterAlignOptions },
ExtractArchive { input: PathBuf, output_dir: PathBuf, limits: Limits },
}
A single codec operation.
These are the CPU-bound paths that decode or encode attacker-influenced audio through LAME, FDK-AAC and libopus, all of which are C libraries.
Variants
EncodeMp3: Re-encode audio to MP3 via Symphonia and LAME.input: Absolute path of the source audio to re-encode.output: Absolute path where the MP3 should be written.lame: LAME encoder knobs for this encode.max_sample_rate: Optional ceiling for output sample rate in Hz (None= leave source).max_output_bytes: Hard cap on bytes written tooutput.Nonedoes not cap the file.
EncodeOpus: Encode audio to Ogg Opus via Symphonia and libopus.input: Absolute path of the source audio to encode.output: Absolute path where the.opusfile should be written.options: Bitrate and channel choice.max_output_bytes: Hard cap on bytes written tooutput.Nonedoes not cap the file.
RemuxTrimmed: Copy or trim a progressive M4B/M4A into a new file.input: Absolute path of the source M4B/M4A.output: Absolute path where the remuxed file should be written.trim: Inclusive start / exclusive end window in milliseconds.
Fixup: Write metadata tags, cover art, and chapters.request: Fix-up request payload (boxed for enum size).
PackageM4b: Package ordered audio parts into one M4B.request: Packaging request payload (boxed for enum size).
AlignChapters: Snap chapter starts to spoken-title onsets by local waveform analysis.path: Absolute path of the audio file to analyse.chapters: Chapter titles paired with start offsets in milliseconds.options: Waveform-alignment tuning (window sizes, thresholds).
ExtractArchive: Expand an uploaded ZIP or tar archive into an empty folder under caps (bookclerk_archive::extract).input: Absolute path of the archive.output_dir: Absolute path of the empty folder the files go into.limits: The caps for this archive.
pub fn read_paths(&self) -> Vec<PathBuf>
Paths the job reads but must not modify.
These become the worker's read allowlist verbatim. Symbolic links are granted at their resolved target, because that is the inode the kernel checks — declaring a link inside the cache directory therefore grants whatever it points at. The host builds these paths from its own cache and output roots, so nothing untrusted chooses them.
pub fn write_dirs(&self) -> Vec<PathBuf>
Directories the job writes into.
Directories rather than files, because the codecs stage output through temporary files alongside the destination and Landlock rules apply to a path and everything beneath it.
pub fn label(&self) -> &'static str
Short label for logs and error messages.
pub fn prepare_output_dirs(&self) -> Result<()>
Create the output directories this job needs.
Both Landlock and Seatbelt reject a rule naming a path that does not exist, so the destination has to be created before the jail is built.
Propagates directory-creation failures.
pub fn run(self) -> Result<MediaJobOutput>
Execute the job on the calling thread.
This is the entry point the worker binary calls after confining itself. It is also used directly when process isolation is turned off.
Returns crate::MediaError::InputMissing when a declared input cannot
be reached, and propagates codec and I/O failures otherwise.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub enum MediaJobOutput {
File { output: PathBuf },
FileWithChapters { output: PathBuf, chapters: Vec<(String, u64)> },
Chapters { chapters: Vec<(String, u64)> },
Extracted { report: Box<ExtractReport> },
}
What a finished job produced.
Variants
File: A single written file.output: Path to the written media file.
FileWithChapters: A written file plus the chapter list that was muxed into it.output: Path to the written media file.chapters: Chapter titles paired with start offsets in milliseconds.
Chapters: Adjusted chapter starts; writes nothing.chapters: Chapter titles paired with start offsets in milliseconds.
Extracted: What an archive expansion wrote and refused.report: The walk's report; the host re-checks it before trusting it.
pub fn output(&self) -> Option<&Path>
The written file, when this job produced one.
pub fn chapters(&self) -> Option<&[(String, u64)]>
The chapter list, when this job produced one.
Implements: Clone, Debug, Deserialize<'de>, Eq, From<MediaJobOutput>, PartialEq, Serialize
pub enum MediaJobReply {
Ok(MediaJobOutput),
Err { message: String },
}
Wire form of a finished job. Result is not Serialize, so the worker and
the pool exchange this instead.
Variants
Ok: The job succeeded.Err: The job failed. Carries the rendered error, sincecrate::MediaErroris not reconstructible across a process boundary.message: Human-readable failure message from the worker.
Implements: Clone, Debug, Deserialize<'de>, From<Result<MediaJobOutput, MediaError>>, Serialize
pub enum Confinement {
Required,
BestEffort,
Off,
}
How strictly a worker must be confined before it will process a job.
Variants
Required: Refuse to run the job unless the worker confined itself. Production default: a host that cannot sandbox must not silently decode untrusted media next to the encryption key.BestEffort: Confine where the platform allows and log what did not engage.Off: Run jobs on a blocking thread in this process. Intended for development and for the crate's own algorithm tests.
pub fn from_env_value(value: &str) -> Option<Self>
Parse the value carried in WORKER_ENFORCEMENT_ENV.
pub fn as_env_value(self) -> &'static str
The value to pass through WORKER_ENFORCEMENT_ENV.
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub fn decode_pcm_bytes<F>(
bytes: Vec<u8>,
out: OutChannels,
on_pcm: F,
) -> Result<PcmFormat>
where
F: FnMut(PcmFormat, &[i16]) -> Result<()>,
Decodes a whole media file held in memory to PCM, the path the
media_decode fuzz target and its replay test drive.
bytes- The file.out- The channel layout wanted.on_pcm- Called once per decoded packet with the stream's layout and that packet's interleaved samples (a whole number of frames).
MediaError::Native when no known container or audio track is found,
no decoder handles the codec, the demuxer fails, or the file decodes to
no PCM at all; or what on_pcm returns.
pub fn write_output_within_budget(
file: &mut impl Write,
data: &[u8],
written: &mut u64,
max: Option<u64>,
) -> Result<()>
Appends data only when the result stays within max.
The failing call writes nothing, so the file length never passes the budget.
max == None does not impose a byte ceiling.
Returns MediaError::Native when written + data.len() would exceed
max. Returns MediaError::Io when the accepted bytes cannot be written.
pub fn check_archive_report(
report: &ExtractReport,
output_dir: &Path,
limits: &Limits,
) -> Result<()>
Checks a worker's report against the limits and the files on disk.
MediaError::Archive naming what does not hold.
pub async fn extract_archive(
input: &Path,
output_dir: &Path,
limits: Limits,
) -> Result<ExtractReport>
Expands input into the empty folder output_dir in a confined media
worker, then checks the result.
The report is validated against limits (ExtractReport::validate),
and every file it lists must be a regular file (not a link) at its path
under output_dir, with the size the report states. A stopped walk is
returned as is: the caller discards the folder.
input- The archive.output_dir- An empty folder; created if missing.limits- The caps for this archive.
MediaError::Archive when output_dir is not empty, the input is not
a recognised archive, or the report does not hold up;
MediaError::NotIsolated when isolation is required and no worker is
available; worker and I/O failures otherwise.
pub fn align_chapter_starts(
path: &Path,
chapters: &[(String, u64)],
opts: ChapterAlignOptions,
) -> Vec<(String, u64)>
Snap chapter starts just before nearby speech onsets (spoken chapter titles).
Detects the speech-band onset of the spoken title, then walks backward
through quiet frames up to max_lead_in_ms so the marker precedes the title
without landing on a prior vocal waveform. Chapters at 0 are left
unchanged. Failures keep the original timestamp. Results stay monotonic.
Opens the media once and reuses a seek index across chapter windows so a long book stays cheap (~tens of seconds of decode total, not a full pass).
pub fn scale_chapters_to_duration(
chapters: &[(String, u64)],
content_duration_ms: Option<u64>,
plain_duration_ms: Option<u64>,
) -> Vec<(String, u64)>
Scale rebased chapter starts so they span the probed plain-audio duration.
When Audible content duration (runtime - intro - outro) differs from the
plain file, apply a uniform scale. No-ops when either duration is missing or
the relative delta is tiny.
pub fn bookclerk_tool_tag() -> String
bookclerk <version> string embedded in encoder / freeform TOOL tags.
pub async fn fixup_audiobook(req: FixupRequest) -> Result<MediaOutcome>
Apply metadata tags, optional cover embed, and optional chapters.
Runs in a confined media worker; see the crate documentation.
Returns MediaError::InputMissing when the input does not exist,
MediaError::OutputMissing when the worker reported success but wrote
nothing, and propagates tag-writing and worker failures otherwise.
pub fn package_keeping_codec(
parts: &[PathBuf],
output: &Path,
titles: &[String],
) -> Result<Option<Vec<(String, u64)>>>
Packages parts into one M4B at output keeping their audio, with a
chapter at the start of each part titled from titles.
The chapters (title, start ms), or None when the parts cannot be
kept together and should be transcoded instead.
A read or write error once packaging has started.
pub fn remux_trimmed(input: &Path, output: &Path, trim: TrimRange) -> Result<MediaOutcome>
Remux a progressive clear M4B/M4A with an optional media-time trim (chapter split).
Returns an error when the operation fails.
pub fn encode_to_opus_native(
input: &Path,
output: &Path,
options: OpusEncodeOptions,
max_output_bytes: Option<u64>,
) -> Result<MediaOutcome>
Encodes the audio in input to an Ogg Opus file at output.
input- Any file the decode front opens.output- Where the.opusfile is written (replaced if present).options- Bitrate and channel choice.max_output_bytes- Fail rather than write past this many bytes.
MediaError::InputMissing when the input does not exist; what the
decode front returns for audio it cannot open or decode;
MediaError::Native when libopus refuses a setting or a frame, the
input decodes to nothing, or the byte budget would be passed; an I/O
error when the output cannot be written.
pub async fn package_m4b_from_mp3(
req: PackageM4bRequest,
) -> Result<(MediaOutcome, Vec<(String, u64)>)>
Decode/remux ordered parts → progressive M4B.
Clear AAC MP4/M4A/M4B parts are remuxed without re-encoding. MP3 parts are decoded and encoded to AAC-LC via a streaming path.
Returns the output path plus chapter list (title, start_ms).
Runs in a confined media worker; see the crate documentation.
Returns MediaError::InputMissing when a part is missing, and propagates
packaging and worker failures otherwise.
pub fn package_m4b_from_pcm(
pcm: &[i16],
sample_rate: u32,
channels: u16,
output: &Path,
chapter_boundaries_ms: &[(String, u64)],
) -> Result<(MediaOutcome, Vec<(String, u64)>)>
Encode interleaved PCM to AAC-LC and mux an M4B (test / internal helper).
Feeds PCM in bounded chunks so callers with large buffers still do not duplicate the full stream as AAC access units in memory.
Returns an error when the operation fails.
pub fn serve_pcm<R, W>(input: R, output: W) -> Result<(), String>
where
R: Read + Send + Sync + 'static,
W: Write + Send + Sync + 'static,
Serves one PCM decode over input and output (the worker's stdin and
stdout): reads Open, then streams Format, Pcm frames and End, or
Failed when the file cannot be decoded.
input- Request frames from the host.output- Reply frames to the host.
Why the stream broke: the host sent no Open, or a pipe failed. A file
that cannot be decoded is not an error here: the host is told with
Failed.
pub fn init_pool(pool: MediaPool) -> Result<(), MediaPool>
Install the process-wide pool if none is installed yet.
Returns the rejected pool when one was already installed. Use
replace_pool to swap a pool that is already running.
pub fn init_pool_from_config(config: &MediaConfig)
Build the pool from [media] config and install it, logging what it will do.
Safe to call more than once, which is what a config reload does. An
unchanged [media] leaves the running pool alone; a changed one swaps in a
new pool for subsequent jobs and lets the old one drain. See
replace_pool.
pub fn pool() -> Arc<MediaPool>
The process-wide pool, creating a default one if startup never installed it.
Returns an owned handle on purpose. Holding it for the length of a job is what lets a reload swap the pool without disturbing work already running.
pub fn replace_pool(pool: MediaPool) -> Option<Arc<MediaPool>>
Swap in pool, returning the one it replaced.
Safe to call with jobs in flight, because pool hands out an Arc and a
job holds it for its whole duration. The moment this returns, the outgoing
pool is unreachable, so it can only drain: its permits are released as its
jobs finish and it is dropped after the last one. Nothing is interrupted and
nothing waits.
In-flight jobs keep the isolation they started with, which is the only possible answer — a worker's confinement is applied inside the child process at spawn and cannot be changed afterwards.
While the outgoing pool drains, total codec concurrency can briefly reach the old pool's in-flight count plus the new pool's limit. That overshoot only shrinks, since the old pool never admits another job.
pub async fn encode_to_mp3(
input: &Path,
output: &Path,
lame: &LameConfig,
max_sample_rate: Option<u32>,
max_output_bytes: Option<u64>,
) -> Result<MediaOutcome>
Re-encode audio to MP3 via Symphonia + LAME (classic Libation DecryptToLossy).
Runs in a confined media worker; see the module documentation.
Returns MediaError::InputMissing when input does not exist, and
propagates encode and worker failures otherwise.
pub async fn encode_to_opus(
input: &Path,
output: &Path,
options: OpusEncodeOptions,
max_output_bytes: Option<u64>,
) -> Result<MediaOutcome>
Encode audio to Ogg Opus via Symphonia + libopus.
Runs in a confined media worker; see the module documentation.
Returns MediaError::InputMissing when input does not exist, and
propagates encode and worker failures otherwise.
pub async fn remux_trimmed_async(
input: &Path,
output: &Path,
trim: TrimRange,
) -> Result<MediaOutcome>
Copy/trim a progressive M4B/M4A into a new file (chapter split helper).
Runs in a confined media worker; see the module documentation.
Returns MediaError::InputMissing when input does not exist, and
propagates remux and worker failures otherwise.
pub async fn align_chapter_starts_async(
path: &Path,
chapters: &[(String, u64)],
options: ChapterAlignOptions,
) -> Vec<(String, u64)>
Snap chapter starts to spoken-title onsets by local waveform analysis.
The synchronous align_chapter_starts decodes audio on the calling
thread, which on an async runtime blocks a worker for the length of the
analysis. Prefer this from async code.
Analysis never fails the acquire: a decode problem leaves the original chapter starts in place, matching the synchronous behaviour.
pub type Result<T> = Result<T, MediaError>;
Result alias for media packaging and worker operations in this crate.
pub const MAX_SAMPLE_RATE_HZ: u32 = 768_000;
Highest sample rate a decoded stream may report, in Hz. Anything above is refused as malformed rather than handed to an encoder.
pub const COVER_THREADS_ENV: &str = "BOOKCLERK_COVER_THREADS";
Environment variable carrying the cover worker's decode thread count.
pub const COVER_WORKER_ARG: &str = "covers";
First worker argument that selects the cover server.
pub const BOOKCLERK_TOOL_NAME: &str = "bookclerk";
Product / CLI name written into tool attribution tags.
pub const MAX_OPUS_KBPS: u16 = 510;
Highest bitrate an Opus copy is encoded at, in kbit/s (per stream; the Opus limit for stereo).
pub const MIN_OPUS_KBPS: u16 = 6;
Lowest bitrate an Opus copy is encoded at, in kbit/s.
pub const JAIL_BIN_ENV: &str = "BOOKCLERK_PLUGIN_JAIL";
Environment variable naming the jail launcher (shared with plugin hosts).
pub const JAIL_BIN_NAME: &str = "bookclerk-jail";
File name of the jail launcher when it sits beside the host / worker.
pub const WORKER_BIN_ENV: &str = "BOOKCLERK_MEDIA_WORKER";
Environment variable naming the worker binary explicitly.
pub const WORKER_BIN_NAME: &str = "bookclerk-media-worker";
File name of the worker binary when it sits beside the host executable.
pub const WORKER_ENFORCEMENT_ENV: &str = "BOOKCLERK_MEDIA_WORKER_ENFORCEMENT";
Environment variable the pool sets on each worker to select its failure mode.
pub const TAG_WORKER_ARG: &str = "tags";
First worker argument that selects the tag reader.
Generated from crates/bookclerk-media at main · View as Markdown