mediadecode_ffmpeg/
lib.rs

1#![doc = include_str!("../README.md")]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3#![cfg_attr(docsrs, allow(unused_attributes))]
4#![deny(missing_docs)]
5// The core crate carries this same allow, for this same reason, and 0.9
6// is where this crate joined it: a signature here reads
7// `VideoPacket<VideoPacketExtra, FfmpegBytes>` because every one of those
8// three names is load-bearing — the household, the backend's extras,
9// and the owned carrier the D-seat amputation contract requires.
10// `clippy::type_complexity` counts nesting, and the fix it asks for is
11// an alias that hides exactly the word this release exists to make
12// visible. 0.8 had that alias; it was called `FfmpegBuffer`.
13#![allow(clippy::type_complexity)]
14
15mod adapter;
16mod audio;
17mod backend;
18pub mod boundary;
19mod buffer;
20mod carrier;
21pub mod channel_layout;
22mod codec_id;
23mod container;
24pub mod convert;
25mod decoder;
26mod demuxer;
27mod error;
28pub mod extras;
29#[cfg(test)]
30mod fault_subprocess;
31mod ffi;
32mod footprint;
33mod frame;
34mod image;
35pub mod limits;
36mod pixdesc;
37mod reader_guard;
38#[cfg(feature = "resample")]
39mod resampler;
40mod sample_format;
41mod subtitle;
42pub mod ticket;
43mod video;
44mod view;
45mod vtscale;
46
47pub use adapter::Ffmpeg;
48pub use audio::{AudioDecodeError, CarrierAudioStreamDecoder};
49pub use backend::Backend;
50pub use boundary::{
51  MediaKind, PacketBuildError, SendPayloadTooLarge, SendSideDataTooLarge,
52  attachment_packet_from_ffmpeg, audio_packet_from_ffmpeg, audio_packet_from_ffmpeg_in,
53  data_packet_from_ffmpeg_in, empty_audio_frame, empty_owned_audio_frame,
54  empty_owned_subtitle_frame, empty_owned_video_frame, empty_subtitle_frame, empty_video_frame,
55  ffmpeg_packet_from_audio_packet, ffmpeg_packet_from_owned_audio_packet,
56  ffmpeg_packet_from_owned_subtitle_packet, ffmpeg_packet_from_owned_video_packet,
57  ffmpeg_packet_from_subtitle_packet, ffmpeg_packet_from_video_packet, from_av_pixel_format,
58  is_hardware_pix_fmt, owned_attachment_packet_from_ffmpeg, owned_audio_packet_from_ffmpeg_in,
59  owned_data_packet_from_ffmpeg_in, owned_subtitle_packet_from_ffmpeg_in,
60  owned_video_packet_from_ffmpeg_in, subtitle_packet_from_ffmpeg, subtitle_packet_from_ffmpeg_in,
61  video_packet_from_ffmpeg, video_packet_from_ffmpeg_in,
62};
63
64pub use buffer::{FfmpegBytes, PacketBufferError, TrustedPayload};
65pub(crate) use carrier::CarrierOps;
66pub use carrier::{FfmpegCarrier, Owned, View};
67pub use view::FfmpegBuffer;
68
69/// The demuxer, on the **view** lane — the ordinary road.
70///
71/// Packets carry [`FfmpegBuffer`] views onto libavformat's own
72/// allocations: nothing is copied, and a consumer that reads a packet
73/// and drops it never pays for bytes it did not keep. This is what a
74/// direct consumer wants, which is why it is what the bare name means.
75///
76/// Reach for [`FfmpegOwnedDemuxer`] when a packet has to **travel** —
77/// across a graph, between threads that both read it, into a cache
78/// that outlives the decoder. See [the carrier lanes][lanes] for the
79/// tradeoff table.
80///
81/// [lanes]: mediadecode::adapter#the-two-carrier-lanes
82pub type FfmpegDemuxer = demuxer::CarrierDemuxer<View>;
83
84/// The demuxer on the **owned** lane: every byte copied once at the
85/// boundary into memory Rust owns.
86///
87/// The same type as [`FfmpegDemuxer`] on the other carrier, with the
88/// same constructors — `FfmpegOwnedDemuxer::open(&path)`. Packets are
89/// `Send + Sync + 'static` and owe nothing to the session that produced
90/// them, which is what a graph needs and what a view cannot give.
91pub type FfmpegOwnedDemuxer = demuxer::CarrierDemuxer<Owned>;
92
93/// The audio decoder on the **view** lane.
94pub type FfmpegAudioStreamDecoder = audio::CarrierAudioStreamDecoder<View>;
95/// The audio decoder on the **owned** lane.
96pub type FfmpegOwnedAudioStreamDecoder = audio::CarrierAudioStreamDecoder<Owned>;
97
98/// The subtitle decoder on the **view** lane.
99pub type FfmpegSubtitleStreamDecoder = subtitle::CarrierSubtitleStreamDecoder<View>;
100/// The subtitle decoder on the **owned** lane.
101pub type FfmpegOwnedSubtitleStreamDecoder = subtitle::CarrierSubtitleStreamDecoder<Owned>;
102
103/// The still-image decoder on the **view** lane.
104pub type FfmpegImageDecoder = image::CarrierImageDecoder<View>;
105/// The still-image decoder on the **owned** lane.
106pub type FfmpegOwnedImageDecoder = image::CarrierImageDecoder<Owned>;
107
108/// The video stream decoder on the **view** lane.
109pub type FfmpegVideoStreamDecoder = video::CarrierVideoStreamDecoder<View>;
110/// The video stream decoder on the **owned** lane.
111pub type FfmpegOwnedVideoStreamDecoder = video::CarrierVideoStreamDecoder<Owned>;
112pub use channel_layout::{
113  ChannelLayoutFault, channel_layout_description_from_ffmpeg, channel_layout_from_ffmpeg,
114  channel_order_from_ffmpeg,
115};
116pub use codec_id::CodecId;
117pub use container::ContainerFormat;
118pub use decoder::VideoDecoder;
119pub use demuxer::{
120  CarrierDemuxer, ChapterAlloc, ChapterTimebaseInvalid, ChapterTitleAlloc,
121  ChapterTitleBudgetExhausted, ChapterTitleTooLong, DemuxError, ParametersChannelMap,
122  ParametersLayoutShape, ProbeBudgetExhausted, TooManyChapters, TrackMetadataAlloc,
123  TrackMetadataBudgetExhausted, TrackMetadataTooLong, TrackTableAlloc, TrackTimebaseInvalid,
124};
125pub use error::{
126  Error, FrameBudgetExceeded, FrameMedium, HwSurfaceTooLarge, HwTransferTooLarge, Result,
127};
128pub use frame::Frame;
129pub use image::{CarrierImageDecoder, Corrupt, CorruptSource, ImageDecodeError, InputTooLarge};
130pub use limits::{
131  DEFAULT_MAX_ATTACHMENT_BYTES, DEFAULT_MAX_CHAPTERS, DEFAULT_MAX_CODEC_PARAMETER_BYTES,
132  DEFAULT_MAX_FRAME_BYTES, DEFAULT_MAX_IMAGE_INPUT_BYTES, DEFAULT_MAX_IMAGE_SIDE_DATA_BYTES,
133  DEFAULT_MAX_PACKET_BYTES, DEFAULT_MAX_PIXELS, DEFAULT_MAX_PROBE_BYTES, DEFAULT_MAX_STREAMS,
134  DEFAULT_MAX_TOTAL_ATTACHMENT_BYTES, DEFAULT_MAX_TOTAL_CHAPTER_TITLE_BYTES,
135  DEFAULT_MAX_TOTAL_CODEC_PARAMETER_BYTES, DEFAULT_MAX_TOTAL_STREAM_METADATA_BYTES, DecoderLimits,
136  DemuxLimits, FrameLimits, PacketLimits,
137};
138#[cfg(feature = "resample")]
139#[cfg_attr(docsrs, doc(cfg(feature = "resample")))]
140pub use resampler::{
141  CarrierResampler, OutputTooLarge, ResampleError, ResampleSpec, SpecEnd,
142  UnsupportedChannelCount as UnsupportedSpecChannelCount,
143};
144/// The resampler, on the **view** lane — planes shared out of its own
145/// output frame.
146///
147/// Its output frames are the resampler's, not a decoder's: it allocates
148/// one per conversion and never writes into a buffer it has handed out,
149/// so the pool-hostage warning that applies to decoder frames does not
150/// apply here. What does apply is `!Sync` and the amputation contract —
151/// use [`FfmpegOwnedResampler`] for a frame that has to travel.
152#[cfg(feature = "resample")]
153#[cfg_attr(docsrs, doc(cfg(feature = "resample")))]
154pub type FfmpegResampler = resampler::CarrierResampler<View>;
155
156/// The resampler, on the **owned** lane — every produced plane copied
157/// out of the output frame.
158#[cfg(feature = "resample")]
159#[cfg_attr(docsrs, doc(cfg(feature = "resample")))]
160pub type FfmpegOwnedResampler = resampler::CarrierResampler<Owned>;
161
162pub use sample_format::SampleFormat;
163pub use subtitle::{CarrierSubtitleStreamDecoder, SubtitleDecodeError};
164pub use ticket::{ChannelLayoutTicket, CodecTicket, CustomChannel, DolbyVisionConfig, Ratio};
165pub use video::{CarrierVideoStreamDecoder, DecodePath, VideoDecodeError};
166
167// Every bare alias below binds [`FfmpegBuffer`] in the `D` seat — the
168// view lane, the ordinary road: a decoder's output read where it lands
169// and dropped. The `Owned*` family binds [`FfmpegBytes`] and is what a
170// payload takes when it has to **travel** — outlive the decoder, cross
171// into a graph, be shared across threads.
172//
173// Each spells its carrier out rather than hiding it behind a neutral
174// name. That is deliberate, and it is the one lesson 0.8's version of
175// this block failed to teach: 0.8 also called this type `FfmpegBuffer`,
176// but the D seat was *only* ever that type, so a consumer reading
177// `VideoFrame` could not tell that holding one held libavcodec's memory
178// open. It did. Naming both carriers in both families is what makes the
179// question answerable at the use site — and [`FfmpegBytes`] answers it
180// by being nothing of ours: owned, `Send + Sync`, no FFmpeg lifetime
181// attached, the core's D-seat amputation contract satisfied by a type
182// out of `alloc`.
183
184/// Compressed video packet pre-parameterized with this crate's extras
185/// and view carrier — the type [`FfmpegVideoStreamDecoder`] consumes
186/// via [`mediadecode::decoder::VideoStreamDecoder::send_packet`].
187pub type VideoPacket = mediadecode::packet::VideoPacket<extras::VideoPacketExtra, FfmpegBuffer>;
188
189/// Compressed audio packet pre-parameterized with this crate's extras
190/// and view carrier.
191pub type AudioPacket = mediadecode::packet::AudioPacket<extras::AudioPacketExtra, FfmpegBuffer>;
192
193/// Compressed subtitle packet pre-parameterized with this crate's
194/// extras and view carrier.
195pub type SubtitlePacket =
196  mediadecode::packet::SubtitlePacket<extras::SubtitlePacketExtra, FfmpegBuffer>;
197
198/// Decoded video frame pre-parameterized with this crate's pixel
199/// format / extras / view carrier.
200///
201/// Its planes are windows into the decoder's own frame buffer wherever
202/// the geometry proves they may be — see the frame row of the lane
203/// table in [`mediadecode::adapter`]. **A frame held is a pool slot
204/// held**: on a hardware or fixed-pool decoder, retaining these past
205/// the next `receive_frame` starves the decoder. Use [`OwnedVideoFrame`]
206/// when a frame has to outlive the decode loop.
207pub type VideoFrame =
208  mediadecode::frame::VideoFrame<mediadecode::PixelFormat, extras::VideoFrameExtra, FfmpegBuffer>;
209
210/// Decoded audio frame pre-parameterized with this crate's sample
211/// format / channel layout / extras / view carrier.
212///
213/// Each plane is a window over exactly the samples the decoder wrote —
214/// never the allocator's alignment padding past them.
215pub type AudioFrame = mediadecode::frame::AudioFrame<
216  SampleFormat,
217  mediaframe::audio::ChannelLayoutDescription,
218  extras::AudioFrameExtra,
219  FfmpegBuffer,
220>;
221
222/// Decoded subtitle frame pre-parameterized with this crate's
223/// extras / view carrier.
224pub type SubtitleFrame =
225  mediadecode::frame::SubtitleFrame<extras::SubtitleFrameExtra, FfmpegBuffer>;
226
227/// Decoded still image pre-parameterized with this crate's pixel
228/// format / extras / view carrier — what [`FfmpegImageDecoder`]
229/// produces.
230pub type ImageFrame =
231  mediadecode::frame::ImageFrame<mediadecode::PixelFormat, extras::ImageFrameExtra, FfmpegBuffer>;
232
233/// Timed opaque-data packet pre-parameterized with this crate's extras
234/// and view carrier.
235pub type DataPacket = mediadecode::demuxer::DataPacket<extras::DataPacketExtra, FfmpegBuffer>;
236
237/// Attachment payload pre-parameterized with this crate's extras and
238/// view carrier — a font, or the cover art [`FfmpegImageDecoder`]
239/// decodes.
240pub type AttachmentPacket =
241  mediadecode::demuxer::AttachmentPacket<extras::AttachmentPacketExtra, FfmpegBuffer>;
242
243/// The five-arm demux envelope [`FfmpegDemuxer`] delivers.
244pub type DemuxedPacket = mediadecode::demuxer::DemuxedPacket<Ffmpeg, FfmpegBuffer>;
245
246// --- The owned lane's alias family -----------------------------------
247//
248// The same shapes on the copying carrier, named explicitly because the
249// bare names mean the view lane — the ordinary road for a direct
250// consumer. Reach for these when a packet has to travel.
251//
252// Note what is **not** doubled: the `*Extra` types and `SideDataEntry`
253// stay monomorphic on both lanes. Side data has no `AVBufferRef` to
254// share — `AVPacketSideData` and `AVFrameSideData` payloads are plain
255// allocations — so both lanes copy it, and a second family of extras
256// would have been two names for one representation. The carrier
257// parameter reaches the **payload**, not the annotations.
258
259/// [`VideoPacket`] on the owned lane.
260pub type OwnedVideoPacket = mediadecode::packet::VideoPacket<extras::VideoPacketExtra, FfmpegBytes>;
261
262/// [`AudioPacket`] on the owned lane.
263pub type OwnedAudioPacket = mediadecode::packet::AudioPacket<extras::AudioPacketExtra, FfmpegBytes>;
264
265/// [`SubtitlePacket`] on the owned lane.
266pub type OwnedSubtitlePacket =
267  mediadecode::packet::SubtitlePacket<extras::SubtitlePacketExtra, FfmpegBytes>;
268
269/// [`DataPacket`] on the owned lane.
270pub type OwnedDataPacket = mediadecode::demuxer::DataPacket<extras::DataPacketExtra, FfmpegBytes>;
271
272/// [`AttachmentPacket`] on the owned lane.
273pub type OwnedAttachmentPacket =
274  mediadecode::demuxer::AttachmentPacket<extras::AttachmentPacketExtra, FfmpegBytes>;
275
276/// [`DemuxedPacket`] on the owned lane.
277pub type OwnedDemuxedPacket = mediadecode::demuxer::DemuxedPacket<Ffmpeg, FfmpegBytes>;
278
279/// [`VideoFrame`] on the owned lane — planes copied out of the
280/// decoder's buffer, so the frame outlives it and the pool slot goes
281/// straight back.
282pub type OwnedVideoFrame =
283  mediadecode::frame::VideoFrame<mediadecode::PixelFormat, extras::VideoFrameExtra, FfmpegBytes>;
284
285/// [`AudioFrame`] on the owned lane.
286pub type OwnedAudioFrame = mediadecode::frame::AudioFrame<
287  SampleFormat,
288  mediaframe::audio::ChannelLayoutDescription,
289  extras::AudioFrameExtra,
290  FfmpegBytes,
291>;
292
293/// [`SubtitleFrame`] on the owned lane.
294pub type OwnedSubtitleFrame =
295  mediadecode::frame::SubtitleFrame<extras::SubtitleFrameExtra, FfmpegBytes>;
296
297/// [`ImageFrame`] on the owned lane — what [`FfmpegOwnedImageDecoder`]
298/// produces.
299pub type OwnedImageFrame =
300  mediadecode::frame::ImageFrame<mediadecode::PixelFormat, extras::ImageFrameExtra, FfmpegBytes>;
301
302/// One row of the track table [`FfmpegDemuxer::tracks`] returns.
303///
304/// [`FfmpegDemuxer::tracks`]: mediadecode::demuxer::Demuxer::tracks
305pub type TrackInfo = mediadecode::demuxer::TrackInfo<Ffmpeg>;
306
307/// A track's per-kind codec parameters, as [`TrackInfo`] carries them.
308pub type TrackParams = mediadecode::demuxer::TrackParams<Ffmpeg>;
309
310/// One row of the chapter table [`FfmpegDemuxer::chapters`] returns.
311///
312/// [`FfmpegDemuxer::chapters`]: mediadecode::demuxer::Demuxer::chapters
313pub type Chapter = mediadecode::demuxer::Chapter<Ffmpeg>;
314
315/// Asserts a submission was taken, and answers nothing.
316///
317/// The `#[must_use]` on [`mediadecode::Sent`] is deliberate teeth: a
318/// test that submits and ignores the answer is a test that would not
319/// notice a decoder quietly asking to be drained. Most of this crate's
320/// tests submit into a session they have just emptied, where
321/// [`Sent::MustDrain`](mediadecode::Sent::MustDrain) is a real
322/// surprise — so they say so here rather than dropping it.
323#[cfg(test)]
324#[track_caller]
325pub(crate) fn accepted<E: core::fmt::Debug>(
326  status: core::result::Result<mediadecode::Sent, E>,
327  what: &str,
328) {
329  assert_eq!(
330    status.unwrap_or_else(|e| panic!("{what}: {e:?}")),
331    mediadecode::Sent::Accepted,
332    "{what}: the session asked to be drained where the test expected room",
333  );
334}
mediadecode_ffmpeg/lib.rs

mediadecode_ffmpeg/
lib.rs
