Struct optivorbis::VorbisOptimizer

pub struct VorbisOptimizer<'settings> { /* private fields */ }

A raw Vorbis stream optimizer, which tries to reduce the size of an already encoded stream according to the specified settings, without any changes to the decoded audio samples. In addition, some basic repairs may be done.

This struct is fairly low-level and most end-users will not need to use it. Remuxers provide a simpler and powerful API suitable for most cases.

From a detailed software design standpoint, this optimizer is an incarnation of the state pattern: feeding packets to it makes it transition between different optimization states. The concrete analysis and optimization operations depend on the current state. Roughly, the internal states can be classified in analysis states, which only consume packets for analysis, and optimization states, which leverage the data obtained from the analysis states to optimize packets.

Implementations

impl<'settings> VorbisOptimizer<'settings>

pub fn new<B: AsRef<[u8]>>( settings: &'settings VorbisOptimizerSettings, identification_header: B ) -> Result<Self, VorbisOptimizerError>

Creates a new VorbisOptimizer that uses the provided optimization settings, for the Vorbis stream that begins with the specified identification header. An error will be returned if the identification header is not valid for a Vorbis stream.

pub fn analyze_packet<B: AsRef<[u8]>>( &mut self, packet: B ) -> Result<Option<u16>, VorbisOptimizerError>

Consumes the specified Vorbis packet to analyze the Vorbis stream for a future second optimization pass, and returns the size of the block of samples that decoding this packet would yield.

Note that, due to the inter-packet windowing performed by a Vorbis decoder, not every sample in a block would be output for an audio packet: some samples are overlapped with the previous and next packets. Read the Vorbis I specification, § 4.3.8, for more details.

If no error happens, and the specified packet is not an audio packet, or a decoder would discard it from the stream, Ok(None) is returned.

Panics

If optimize_packet was called once for this optimizer, implicitly moving it into the second optimization pass.

pub fn optimize_packet<'packet, B: Into<Cow<'packet, [u8]>>>( &mut self, packet: B ) -> Result<Option<(Cow<'packet, [u8]>, Option<u16>)>, VorbisOptimizerError>

Consumes the specified Vorbis packet, returning its optimized representation and the size of the block of samples that decoding this packet would yield.

The optimizer will implicitly transition to the second optimization pass if it was not already in that pass, meaning that no further packets can be analyzed. When passing a packet in an owned buffer, this method will write to the buffer it already allocated for optimum performance.

Ok(None) is be returned for audio packets that may be entirely dropped from the stream without any side effects (e.g., 0 byte audio packets). Ok(Some(..., None)) is returned on success for non-audio packets. Ok(Some(..., Some(...))) is returned on success for audio packets that a decoder would attempt to decode.

Note that, due to the inter-packet windowing performed by a Vorbis decoder, not every sample in a block would be output for an audio packet: some samples are overlapped with the previous and next packets. Read the Vorbis I specification, § 4.3.8, for more details.

Preconditions

It is assumed that packets are passed to this method in the same sequence they were passed to analyze_packet. Failure to do so may cause panics and corrupt streams to be generated.