opus_repacketizer(3) Opus opus_repacketizer(3)
NAME
opus_repacketizer - Repacketizer
- The repacketizer can be used to merge multiple Opus packets into a
single packet or alternatively to split Opus packets that have
previously been merged.
SYNOPSIS
Typedefs
typedef struct OpusRepacketizer OpusRepacketizer
Functions
int opus_repacketizer_get_size (void)
Gets the size of an OpusRepacketizer structure.
OpusRepacketizer * opus_repacketizer_init (OpusRepacketizer *rp)
(Re)initializes a previously allocated repacketizer state.
OpusRepacketizer * opus_repacketizer_create (void)
Allocates memory and initializes the new repacketizer with
opus_repacketizer_init().
void opus_repacketizer_destroy (OpusRepacketizer *rp)
Frees an OpusRepacketizer allocated by opus_repacketizer_create().
int opus_repacketizer_cat (OpusRepacketizer *rp, const unsigned char
*data, opus_int32 len)
Add a packet to the current repacketizer state.
opus_int32 opus_repacketizer_out_range (OpusRepacketizer *rp, int begin,
int end, unsigned char *data, opus_int32 maxlen)
Construct a new packet from data previously submitted to the
repacketizer state via opus_repacketizer_cat().
int opus_repacketizer_get_nb_frames (OpusRepacketizer *rp)
Return the total number of frames contained in packet data submitted
to the repacketizer state so far via opus_repacketizer_cat() since
the last call to opus_repacketizer_init() or
opus_repacketizer_create().
opus_int32 opus_repacketizer_out (OpusRepacketizer *rp, unsigned char
*data, opus_int32 maxlen)
Construct a new packet from data previously submitted to the
repacketizer state via opus_repacketizer_cat().
int opus_packet_pad (unsigned char *data, opus_int32 len, opus_int32
new_len)
Pads a given Opus packet to a larger size (possibly changing the TOC
sequence).
opus_int32 opus_packet_unpad (unsigned char *data, opus_int32 len)
Remove all padding from a given Opus packet and rewrite the TOC
sequence to minimize space usage.
int opus_multistream_packet_pad (unsigned char *data, opus_int32 len,
opus_int32 new_len, int nb_streams)
Pads a given Opus multi-stream packet to a larger size (possibly
changing the TOC sequence).
opus_int32 opus_multistream_packet_unpad (unsigned char *data,
opus_int32 len, int nb_streams)
Remove all padding from a given Opus multi-stream packet and rewrite
the TOC sequence to minimize space usage.
Detailed Description
The repacketizer can be used to merge multiple Opus packets into a
single packet or alternatively to split Opus packets that have
previously been merged.
Splitting valid Opus packets is always guaranteed to succeed, whereas
merging valid packets only succeeds if all frames have the same mode,
bandwidth, and frame size, and when the total duration of the merged
packet is no more than 120 ms. The 120 ms limit comes from the
specification and limits decoder memory requirements at a point where
framing overhead becomes negligible.
The repacketizer currently only operates on elementary Opus streams. It
will not manipualte multistream packets successfully, except in the
degenerate case where they consist of data from a single stream.
The repacketizing process starts with creating a repacketizer state,
either by calling opus_repacketizer_create() or by allocating the memory
yourself, e.g.,
OpusRepacketizer *rp;
rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size());
if (rp != NULL)
opus_repacketizer_init(rp);
Then the application should submit packets with opus_repacketizer_cat(),
extract new packets with opus_repacketizer_out() or
opus_repacketizer_out_range(), and then reset the state for the next set
of input packets via opus_repacketizer_init().
For example, to split a sequence of packets into individual frames:
unsigned char *data;
int len;
while (get_next_packet(&data, &len))
{
unsigned char out[1276];
opus_int32 out_len;
int nb_frames;
int err;
int i;
err = opus_repacketizer_cat(rp, data, len);
if (err != OPUS_OK)
{
release_packet(data);
return err;
}
nb_frames = opus_repacketizer_get_nb_frames(rp);
for (i = 0; i < nb_frames; i++)
{
out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out));
if (out_len < 0)
{
release_packet(data);
return (int)out_len;
}
output_next_packet(out, out_len);
}
opus_repacketizer_init(rp);
release_packet(data);
}
Alternatively, to combine a sequence of frames into packets that each
contain up to TARGET_DURATION_MS milliseconds of data:
// The maximum number of packets with duration TARGET_DURATION_MS occurs
// when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5)
// packets.
unsigned char *data[(TARGET_DURATION_MS*2/5)+1];
opus_int32 len[(TARGET_DURATION_MS*2/5)+1];
int nb_packets;
unsigned char out[1277*(TARGET_DURATION_MS*2/2)];
opus_int32 out_len;
int prev_toc;
nb_packets = 0;
while (get_next_packet(data+nb_packets, len+nb_packets))
{
int nb_frames;
int err;
nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]);
if (nb_frames < 1)
{
release_packets(data, nb_packets+1);
return nb_frames;
}
nb_frames += opus_repacketizer_get_nb_frames(rp);
// If adding the next packet would exceed our target, or it has an
// incompatible TOC sequence, output the packets we already have before
// submitting it.
// N.B., The nb_packets > 0 check ensures we've submitted at least one
// packet since the last call to opus_repacketizer_init(). Otherwise a
// single packet longer than TARGET_DURATION_MS would cause us to try to
// output an (invalid) empty packet. It also ensures that prev_toc has
// been set to a valid value. Additionally, len[nb_packets] > 0 is
// guaranteed by the call to opus_packet_get_nb_frames() above, so the
// reference to data[nb_packets][0] should be valid.
if (nb_packets > 0 && (
((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) ||
opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames >
TARGET_DURATION_MS*48))
{
out_len = opus_repacketizer_out(rp, out, sizeof(out));
if (out_len < 0)
{
release_packets(data, nb_packets+1);
return (int)out_len;
}
output_next_packet(out, out_len);
opus_repacketizer_init(rp);
release_packets(data, nb_packets);
data[0] = data[nb_packets];
len[0] = len[nb_packets];
nb_packets = 0;
}
err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]);
if (err != OPUS_OK)
{
release_packets(data, nb_packets+1);
return err;
}
prev_toc = data[nb_packets][0];
nb_packets++;
}
// Output the final, partial packet.
if (nb_packets > 0)
{
out_len = opus_repacketizer_out(rp, out, sizeof(out));
release_packets(data, nb_packets);
if (out_len < 0)
return (int)out_len;
output_next_packet(out, out_len);
}
An alternate way of merging packets is to simply call
opus_repacketizer_cat() unconditionally until it fails. At that point,
the merged packet can be obtained with opus_repacketizer_out() and the
input packet for which opus_repacketizer_cat() needs to be re-added to a
newly reinitialized repacketizer state.
Typedef Documentation
typedef struct OpusRepacketizer OpusRepacketizer
Function Documentation
int opus_multistream_packet_pad (unsigned char * data, opus_int32 len,
opus_int32 new_len, int nb_streams)
Pads a given Opus multi-stream packet to a larger size (possibly
changing the TOC sequence).
Parameters
data const unsigned char*: The buffer containing the packet to pad.
len opus_int32: The size of the packet. This must be at least 1.
new_len opus_int32: The desired size of the packet after padding.
This must be at least 1.
nb_streams opus_int32: The number of streams (not channels) in the
packet. This must be at least as large as len.
Returns
an error code
Return values
OPUS_OK on success.
OPUS_BAD_ARG len was less than 1.
OPUS_INVALID_PACKET data did not contain a valid Opus packet.
opus_int32 opus_multistream_packet_unpad (unsigned char * data, opus_int32
len, int nb_streams)
Remove all padding from a given Opus multi-stream packet and rewrite the
TOC sequence to minimize space usage.
Parameters
data const unsigned char*: The buffer containing the packet to
strip.
len opus_int32: The size of the packet. This must be at least 1.
nb_streams opus_int32: The number of streams (not channels) in the
packet. This must be at least 1.
Returns
The new size of the output packet on success, or an error code on
failure.
Return values
OPUS_BAD_ARG len was less than 1 or new_len was less than len.
OPUS_INVALID_PACKET data did not contain a valid Opus packet.
int opus_packet_pad (unsigned char * data, opus_int32 len, opus_int32
new_len)
Pads a given Opus packet to a larger size (possibly changing the TOC
sequence).
Parameters
data const unsigned char*: The buffer containing the packet to pad.
len opus_int32: The size of the packet. This must be at least 1.
new_len opus_int32: The desired size of the packet after padding.
This must be at least as large as len.
Returns
an error code
Return values
OPUS_OK on success.
OPUS_BAD_ARG len was less than 1 or new_len was less than len.
OPUS_INVALID_PACKET data did not contain a valid Opus packet.
opus_int32 opus_packet_unpad (unsigned char * data, opus_int32 len)
Remove all padding from a given Opus packet and rewrite the TOC sequence
to minimize space usage.
Parameters
data const unsigned char*: The buffer containing the packet to
strip.
len opus_int32: The size of the packet. This must be at least 1.
Returns
The new size of the output packet on success, or an error code on
failure.
Return values
OPUS_BAD_ARG len was less than 1.
OPUS_INVALID_PACKET data did not contain a valid Opus packet.
int opus_repacketizer_cat (OpusRepacketizer * rp, const unsigned char *
data, opus_int32 len)
Add a packet to the current repacketizer state. This packet must match
the configuration of any packets already submitted for repacketization
since the last call to opus_repacketizer_init(). This means that it must
have the same coding mode, audio bandwidth, frame size, and channel
count. This can be checked in advance by examining the top 6 bits of the
first byte of the packet, and ensuring they match the top 6 bits of the
first byte of any previously submitted packet. The total duration of
audio in the repacketizer state also must not exceed 120 ms, the maximum
duration of a single packet, after adding this packet.
The contents of the current repacketizer state can be extracted into new
packets using opus_repacketizer_out() or opus_repacketizer_out_range().
In order to add a packet with a different configuration or to add more
audio beyond 120 ms, you must clear the repacketizer state by calling
opus_repacketizer_init(). If a packet is too large to add to the current
repacketizer state, no part of it is added, even if it contains multiple
frames, some of which might fit. If you wish to be able to add parts of
such packets, you should first use another repacketizer to split the
packet into pieces and add them individually.
See also
opus_repacketizer_out_range
opus_repacketizer_out
opus_repacketizer_init
Parameters
rp OpusRepacketizer*: The repacketizer state to which to add the
packet.
data const unsigned char*: The packet data. The application must
ensure this pointer remains valid until the next call to
opus_repacketizer_init() or opus_repacketizer_destroy().
len opus_int32: The number of bytes in the packet data.
Returns
An error code indicating whether or not the operation succeeded.
Return values
OPUS_OK The packet's contents have been added to the repacketizer
state.
OPUS_INVALID_PACKET The packet did not have a valid TOC sequence,
the packet's TOC sequence was not compatible with previously
submitted packets (because the coding mode, audio bandwidth, frame
size, or channel count did not match), or adding this packet would
increase the total amount of audio stored in the repacketizer state
to more than 120 ms.
OpusRepacketizer * opus_repacketizer_create (void)
Allocates memory and initializes the new repacketizer with
opus_repacketizer_init().
void opus_repacketizer_destroy (OpusRepacketizer * rp)
Frees an OpusRepacketizer allocated by opus_repacketizer_create().
Parameters
rp OpusRepacketizer*: State to be freed.
int opus_repacketizer_get_nb_frames (OpusRepacketizer * rp)
Return the total number of frames contained in packet data submitted to
the repacketizer state so far via opus_repacketizer_cat() since the last
call to opus_repacketizer_init() or opus_repacketizer_create(). This
defines the valid range of packets that can be extracted with
opus_repacketizer_out_range() or opus_repacketizer_out().
Parameters
rp OpusRepacketizer*: The repacketizer state containing the frames.
Returns
The total number of frames contained in the packet data submitted to
the repacketizer state.
int opus_repacketizer_get_size (void)
Gets the size of an OpusRepacketizer structure.
Returns
The size in bytes.
OpusRepacketizer * opus_repacketizer_init (OpusRepacketizer * rp)
(Re)initializes a previously allocated repacketizer state. The state
must be at least the size returned by opus_repacketizer_get_size(). This
can be used for applications which use their own allocator instead of
malloc(). It must also be called to reset the queue of packets waiting
to be repacketized, which is necessary if the maximum packet duration of
120 ms is reached or if you wish to submit packets with a different Opus
configuration (coding mode, audio bandwidth, frame size, or channel
count). Failure to do so will prevent a new packet from being added with
opus_repacketizer_cat().
See also
opus_repacketizer_create
opus_repacketizer_get_size
opus_repacketizer_cat
Parameters
rp OpusRepacketizer*: The repacketizer state to (re)initialize.
Returns
A pointer to the same repacketizer state that was passed in.
opus_int32 opus_repacketizer_out (OpusRepacketizer * rp, unsigned char *
data, opus_int32 maxlen)
Construct a new packet from data previously submitted to the
repacketizer state via opus_repacketizer_cat(). This is a convenience
routine that returns all the data submitted so far in a single packet.
It is equivalent to calling
opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp),
data, maxlen)
Parameters
rp OpusRepacketizer*: The repacketizer state from which to construct
the new packet.
data const unsigned char*: The buffer in which to store the output
packet.
maxlen opus_int32: The maximum number of bytes to store in the
output buffer. In order to guarantee success, this should be at
least 1277*opus_repacketizer_get_nb_frames(rp). However,
1*opus_repacketizer_get_nb_frames(rp) plus the size of all packet
data submitted to the repacketizer since the last call to
opus_repacketizer_init() or opus_repacketizer_create() is also
sufficient, and possibly much smaller.
Returns
The total size of the output packet on success, or an error code on
failure.
Return values
OPUS_BUFFER_TOO_SMALL maxlen was insufficient to contain the
complete output packet.
opus_int32 opus_repacketizer_out_range (OpusRepacketizer * rp, int begin,
int end, unsigned char * data, opus_int32 maxlen)
Construct a new packet from data previously submitted to the
repacketizer state via opus_repacketizer_cat().
Parameters
rp OpusRepacketizer*: The repacketizer state from which to construct
the new packet.
begin int: The index of the first frame in the current repacketizer
state to include in the output.
end int: One past the index of the last frame in the current
repacketizer state to include in the output.
data const unsigned char*: The buffer in which to store the output
packet.
maxlen opus_int32: The maximum number of bytes to store in the
output buffer. In order to guarantee success, this should be at
least 1276 for a single frame, or for multiple frames, 1277*(end-
begin). However, 1*(end-begin) plus the size of all packet data
submitted to the repacketizer since the last call to
opus_repacketizer_init() or opus_repacketizer_create() is also
sufficient, and possibly much smaller.
Returns
The total size of the output packet on success, or an error code on
failure.
Return values
OPUS_BAD_ARG [begin,end) was an invalid range of frames (begin < 0,
begin >= end, or end > opus_repacketizer_get_nb_frames()).
OPUS_BUFFER_TOO_SMALL maxlen was insufficient to contain the
complete output packet.
Author
Generated automatically by Doxygen for Opus from the source code.
Version 1.5.2 Wed Jul 3 2024 11:41:33 opus_repacketizer(3)
Generated by dwww version 1.16 on Sat Oct 3 05:59:20 CEST 2026.