RustyOpus.Encoder (rusty_opus v0.3.3)

Opus encoder backed by the opus-rs codec through Rustler.

Encodes PCM audio (the little-endian f32 binary contract, interleaved for stereo) into raw Opus packets with full control over bitrate and quality.

Example

{:ok, encoder} = RustyOpus.Encoder.new(16_000, 1, :voip, bitrate: 24_000)
pcm = RustyOpus.TestHelpers.PCM.sine(16_000, 1, 1)
{:ok, packet} = RustyOpus.Encoder.encode(encoder, pcm, 320)
:ok = RustyOpus.Encoder.close(encoder)

frame_size is the number of samples per channel in one frame (for example 320 samples at 16 kHz is a 20 ms frame). The PCM binary must contain exactly frame_size * channels f32 samples.

Quality control

Pass :bitrate, :complexity, :cbr, :fec, and :packet_loss to new/4 or update them at runtime with set/2. Higher bitrate produces larger packets with better fidelity; lower bitrate shrinks them. See RustyOpus.Settings.

Summary

Types

t()

Functions

close(encoder)

Closes the encoder idempotently. Further calls return {:error, %Error{reason: :closed}}.

encode(arg1, pcm, frame_size)

Encodes one PCM frame into an Opus packet.

encode_many(encoder, pcm, opts \\ [])

Encodes a whole PCM buffer into a list of Opus packets.

new(rate, channels, application \\ :audio, opts \\ [])

Creates a new encoder.

set(encoder, opts)

Updates quality settings on a live encoder. See RustyOpus.Settings.

Types

t()

@type t() :: %RustyOpus.Encoder{
  channels: 1 | 2,
  rate: 8000 | 12000 | 16000 | 24000 | 48000,
  resource: reference()
}

Functions

close(encoder)

@spec close(t()) :: :ok

Closes the encoder idempotently. Further calls return {:error, %Error{reason: :closed}}.

encode(arg1, pcm, frame_size)

@spec encode(t(), binary(), pos_integer()) ::
  {:ok, binary()} | {:error, RustyOpus.Error.t()}

Encodes one PCM frame into an Opus packet.

frame_size is samples per channel; pcm must hold frame_size * channels samples. Returns {:ok, packet} where packet is a raw Opus binary.

encode_many(encoder, pcm, opts \\ [])

@spec encode_many(t(), binary(), keyword()) ::
  {:ok, [binary()]} | {:error, RustyOpus.Error.t()}

Encodes a whole PCM buffer into a list of Opus packets.

Chunks pcm into frames of frame_size samples per channel. A short last frame is padded with silence (zero samples), never truncated. Defaults frame_size to div(rate, 50) (20 ms). Empty PCM returns an empty list.

new(rate, channels, application \\ :audio, opts \\ [])

@spec new(pos_integer(), 1 | 2, atom(), keyword()) ::
  {:ok, t()} | {:error, RustyOpus.Error.t()}

Creates a new encoder.

Options

See RustyOpus.Settings for :bitrate, :complexity, :cbr, :fec, and :packet_loss. application is one of :voip, :audio, or :restricted_low_delay.

set(encoder, opts)

@spec set(
  t(),
  keyword()
) :: :ok | {:error, RustyOpus.Error.t()}

Updates quality settings on a live encoder. See RustyOpus.Settings.