membrane_av1_format

defmodule Membrane.AV1 do
  @moduledoc """
  AV1 video stream format for Membrane Framework.

  This module defines the stream format struct used for capability negotiation
  between Membrane elements processing AV1 video streams.
  """

  @typedoc """
  Determines how buffers of a stream with AV1 stream format are aligned:
    * `:tu` - each buffer contains a single TU (Temporal Unit), beginning with an
      OBU (Open Bistream Unit) of type OBU_TEMPORAL_DELIMITER
    * `:obu` - each buffer contains a number of complete OBUs, but there is
      no guarantee that they constitute a single TU.
  """
  @type alignment() :: :obu | :tu

  @typedoc """
  Determines the bit depth and subsampling constraints of a bitstream, with which a decoder
  must be compliant. The constraints are defined in
  [Annex A, chapter A.2. of AV1 specification](https://aomediacodec.github.io/av1-spec/#profiles).
  """
  @type profile :: :main | :high | :professional

  @typedoc """
  Determines the resolution and performance constraints of a bitstream, with which a decoder
  must be compliant. The bitrate constraint for levels 4.0 and higher is also determined
  by `t:tier/0`. The constraints are defined in
  [Annex A, chapter A.3. of AV1 specification](https://aomediacodec.github.io/av1-spec/#levels).
  """
  @type level ::
          :"2.0"
          | :"2.1"
          | :"2.2"
          | :"2.3"
          | :"3.0"
          | :"3.1"
          | :"3.2"
          | :"3.3"
          | :"4.0"
          | :"4.1"
          | :"4.2"
          | :"4.3"
          | :"5.0"
          | :"5.1"
          | :"5.2"
          | :"5.3"
          | :"6.0"
          | :"6.1"
          | :"6.2"
          | :"6.3"
          | :"7.0"
          | :"7.1"
          | :"7.2"
          | :"7.3"

  @typedoc """
  Determines the bitrate and compression rate constraint of a bitstream for a given `t:level/0`.
  In the table defining the constraints of levels
  ([Annex A, chapter A.3. of AV1 specification](https://aomediacodec.github.io/av1-spec/#levels)),
  tier determines whether values from MainMbps and MainCR (`:main` tier), or HighMbps and HighCR
  for (`:high` tier) are assumed. `:main` is the only valid tier for levels lower than 4.0.
  """
  @type tier :: :main | :high

  @type framerate :: {non_neg_integer(), pos_integer()}

  @typedoc """
  AV1 stream format.
  """
  @type t :: %__MODULE__{
          alignment: alignment(),
          profile: profile() | nil,
          level: level() | nil,
          tier: tier() | nil,
          width: pos_integer() | nil,
          height: pos_integer() | nil,
          framerate: framerate() | nil
        }

  defstruct alignment: :tu,
            profile: nil,
            level: nil,
            tier: nil,
            width: nil,
            height: nil,
            framerate: nil

  @level_map BiMap.new(%{
               0 => :"2.0",
               1 => :"2.1",
               2 => :"2.2",
               3 => :"2.3",
               4 => :"3.0",
               5 => :"3.1",
               6 => :"3.2",
               7 => :"3.3",
               8 => :"4.0",
               9 => :"4.1",
               10 => :"4.2",
               11 => :"4.3",
               12 => :"5.0",
               13 => :"5.1",
               14 => :"5.2",
               15 => :"5.3",
               16 => :"6.0",
               17 => :"6.1",
               18 => :"6.2",
               19 => :"6.3",
               20 => :"7.0",
               21 => :"7.1",
               22 => :"7.2",
               23 => :"7.3"
             })

  @spec seq_level_idx_to_level(0..31) :: level() | nil
  def seq_level_idx_to_level(seq_level_idx) do
    BiMap.get(@level_map, seq_level_idx)
  end

  @spec level_to_seq_level_idx(level()) :: 0..31
  def level_to_seq_level_idx(level) do
    BiMap.fetch_key!(@level_map, level)
  end

  @profile_map BiMap.new(%{
                 0 => :main,
                 1 => :high,
                 2 => :professional
               })

  @spec seq_profile_to_profile(0..2) :: profile()
  def seq_profile_to_profile(seq_profile) do
    BiMap.fetch!(@profile_map, seq_profile)
  end

  @spec profile_to_seq_profile(profile()) :: 0..2
  def profile_to_seq_profile(profile) do
    BiMap.fetch_key!(@profile_map, profile)
  end

  @tier_map BiMap.new(%{
              0 => :main,
              1 => :high
            })

  @spec seq_tier_to_tier(0..1) :: tier()
  def seq_tier_to_tier(seq_tier) do
    BiMap.fetch!(@tier_map, seq_tier)
  end

  @spec tier_to_seq_tier(tier()) :: 0..1
  def tier_to_seq_tier(tier) do
    BiMap.fetch_key!(@tier_map, tier)
  end
end