Simple User API

[lu-zero]

Status

API:

• Config struct with all the configuration items
  • FromStr to parse a x264-like string
  • Display to produce a x264-like string
  • parse_option(o: &str) to update the configuration using a x264-like key:value string
  • new_context() -> Context
• Context: opaque struct embedding the existing FrameInvariants, Sequence
  • new_frame() -> Arc<Frame>
  • receive_obu_header() -> Vec<u8>
  • send_frame(frame: Arc<Frame>)/receive_packet() -> Packet
  • flush support
• Packet
  • data buffer
  • user private data
  • timestamp

Usage:

• Used in the cli tools
• Used in the decode_tests

Main ideas

Single Context

• Hide from the user the number of contexts we use, per-frame, per-sequence, etc.

In the future

• Shuffle the fields so FrameInvariants isn't so big
• Consider making the Config follow the builder pattern.

Frame allocator

• Give the user a simple way to have the Frame

In the future

• Consider using a pool of frames
• Add mean to have a custom allocation option

Send/Receive/Flush model

• Split the encoding process from taking in/taking out the frames
• Have a clear way to signal we want to complete the current sequence with an explicit function
• Multithread-friendly

In the future

• Consider adding an optional Future-based API on top of this.

// TODO: use the num crate?
#[derive(Clone, Copy, Debug)]
struct Ratio {
    pub num: usize,
    pub den: usize,
}

/// Here we store all the information we might receive from the cli
#[derive(Clone, Copy, Debug)]
struct Config {
    pub width: usize,
    pub height: usize,
    pub timebase: Ratio
    pub enc: EncoderConfig,
}

#[derive(Clone, Copy, Debug)]
struct Context {
    fi: FrameInvariants,
    seq: Sequence,
    timebase: Ratio,
    frame_q: VecDeque<Frame>,
    packet_q: VecDeque<Packet>
}

#[derive(Clone, Copy, Debug)]
enum EncoderStatus {
    /// The encoder needs more Frames to produce an output Packet
    NeedMoreData,
    /// There are enough Frames queue
    EnoughData,
    /// 
    Failure,
}

impl Context {
    pub fn from_config(cfg: Config) -> Self {
        let Config { width, height, timebase, enc } = cfg;
        let fi = FrameInvariants::new(width, height, enc);
        let seq = Sequence::new(width, height);

        Context { fi, seq, timebase }
    }

    pub fn get_config(&self) -> Config {
    
    }

    pub fn new_frame(&self) -> Frame {
        Frame::new(self.fi.padded_w, self.fi.padded_h)
    }

    pub fn send_frame(&mut self, frame: Arc<Frame>) -> Result<(), EncoderStatus> {
        
    }

    pub fn receive_frame(&mut self) -> Result<Packet, EncoderStatus> {
    
    }

    pub fn flush(&mut self) {
    
    }
}

[lu-zero]

Since @atomnuker has a strong opinion regarding having a separate flush() function, here how it looks the other way:

pub fn send_frame(&mut self, frame: F) 
  where F: Into<Option<Arc<Frame>>>) -> Result<(), EncoderStatus> {
  // ... 
  self.q.push_back(frame.into());
  // ...
}

You can pass either None or Arc<Frame>.

Usage example in the playground

[lu-zero]

Watercooler feedback: do not make the libaom mistakes, muxing information should be available

• Keyframe Dependent Recovery Point
• Switch frame signaling
• Multiframe TU
• OBU Header support

TODO:

• Make sure the most common information is in Packet structure
• Add a function to craft the OBU Header

[lu-zero]

Additional Request: Provide a mean to configure the encoder through a string (possibly having the same structure of x264 and x265).

• Add a Default for Config
• Add a Display for Config that serializes that way.
• Add a FromStr for Config that assembles a Config from a string
• Add a set_param()/set_params() function to update a Config with specific values.

[lu-zero]

@robUx4 would you expand what you'd like to have from the encoder here regarding this issue ?

[robUx4]

An encoder should provide the structure in the CodecPrivate https://github.com/Matroska-Org/matroska-specification/blob/master/codec/av1.md#codecprivate-1
And to do so it would also need to provide the initial_presentation_delay_minus_one if initial_presentation_delay_present is set. But that seems tricky.

[lu-zero]

The api landed last August, this issues can be closed (and we can discuss later if we want to extend the API)