Skip to main content

SourceElement

media_pp::element

Trait SourceElement 

Source 
pub trait SourceElement: Source {
    // Required methods
    fn is_live(&self) -> bool;
    fn is_seekable(&self) -> bool;
    fn run(&mut self, control: &ControlReceiver, bus: &Bus) -> Result<()>;
    fn seek(&mut self, target: Duration) -> Result<Duration>;

    // Provided method
    fn on_control(&mut self, _msg: &ControlMsg) { ... }
}
Expand description

A pure source: has output but no input. Its run method drives the production loop and pushes buffers into its own src pad(s) until EOS or an error. crate::pipeline::Pipeline::run normally invokes that loop on the pipeline’s background source thread; a caller may also invoke a concrete implementation directly. Sources typically wrap blocking I/O reads (demuxer, file/network source).

Required Methods§

Source

fn is_live(&self) -> bool

Whether this source produces data from a live, externally advancing input rather than from a finite or application-controlled timeline.

A live source cannot normally produce a first buffer while a pipeline is paused, so pipeline state handling may use this distinction to report that preroll is unavailable. Every implementation must classify itself explicitly so a new live source cannot silently opt into file- style preroll behavior.

Source

fn is_seekable(&self) -> bool

Whether this source can reposition its own input timeline through Self::seek.

This only describes the source’s capability. A seekable source does not imply that every downstream branch can accept a pipeline seek; that must be validated across the complete graph before mutation.

Source

fn run(&mut self, control: &ControlReceiver, bus: &Bus) -> Result<()>

Drives this source until Eos (normal completion), crate::pipeline::Pipeline::finish, or Stop (see ControlMsg::Stop) — call crate::control::drain_control once per loop iteration to make control responsive between blocking reads.

bus is this source’s own way to report a failure pushing into one of its pads without treating it as fatal — post a crate::bus::BusEvent::Error and keep going (drop that one buffer), the same way a crate::queue::Queue handles a failing downstream Sink — rather than returning Err and ending this source’s thread over one bad buffer. A returned Err is still how genuinely fatal failures (this source can’t continue at all) reach crate::pipeline::Pipeline::run, which posts it to bus itself.

Source

fn seek(&mut self, target: Duration) -> Result<Duration>

Repositions this source to target, an absolute position from the start of the media (e.g. av_seek_frame for crate::elements::FileDemuxer). Called by crate::control::drain_control as part of handling ControlMsg::Seek, before that message is forwarded to the source’s own pads — so whatever’s read next comes from the new position by the time downstream elements receive the new timeline announcement. Buffered and stateful old-timeline data is discarded by the preceding ControlMsg::Flush.

Returns where this actually landed, which is allowed to differ from target — a container seek can only ever reposition to a keyframe at or before it (landing mid-GOP would leave downstream decoders/muxers with no reference frame to start from), so target is a request, not a guarantee. drain_control reports the gap between the two via crate::bus::BusEvent::Seeked; callers that need to know where playback actually resumed should watch that instead of assuming target took effect verbatim.

Provided Methods§

Source

fn on_control(&mut self, _msg: &ControlMsg)

Reacts to one control message before it is forwarded to this source’s own pads — the same ordering Self::seek gets, and for the same reason: whatever this source holds must already reflect the message by the time downstream elements see it.

This is the source-side counterpart of Sink::control, and exists for a source that holds state of its own. crate::elements::FileDemuxer uses it for both messages that touch its read-ahead: Flush discards packets belonging to the timeline being left, and Preroll is what makes it hold a blocked pad’s packets instead of waiting on that pad.

The default is a no-op. A source that hands every packet straight to a pad has nothing of its own to keep in step.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§