eden-emu/opus
20
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fixes to the new repacketizer doc

Browse source
This commit is contained in:
Jean-Marc Valin 2012-09-10 16:24:33 -04:00
parent ddd551e06d
commit 1491fa81f4
1 changed files with 20 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

29
include/opus.h
View file

@ -525,7 +525,11 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_nb_samples(const OpusDe
* *
* The repacketizer can be used to merge multiple Opus packets into a single * The repacketizer can be used to merge multiple Opus packets into a single
* packet or alternatively to split Opus packets that have previously been * packet or alternatively to split Opus packets that have previously been
* merged. The repacketizer currently only operates on elementary Opus * 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 repacketizer currently only operates on elementary Opus
* streams. It will not manipualte multistream packets successfully, except in * streams. It will not manipualte multistream packets successfully, except in
* the degenerate case where they consist of data from a single stream. * the degenerate case where they consist of data from a single stream.
* *
@ -581,12 +585,12 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_nb_samples(const OpusDe
* contain up to <code>TARGET_DURATION_MS</code> milliseconds of data: * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data:
* @code * @code
* // The maximum number of packets with duration TARGET_DURATION_MS occurs * // 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*5/2) * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5)
* // packets. * // packets.
* unsigned char *data[(TARGET_DURATION_MS*5/2)+1]; * unsigned char *data[(TARGET_DURATION_MS*2/5)+1];
* opus_int32 len[(TARGET_DURATION_MS*5/2)+1]; * opus_int32 len[(TARGET_DURATION_MS*2/5)+1];
* int nb_packets; * int nb_packets;
* unsigned char out[1277*(TARGET_DURATION_MS*5/2)]; * unsigned char out[1277*(TARGET_DURATION_MS*2/2)];
* opus_int32 out_len; * opus_int32 out_len;
* int prev_toc; * int prev_toc;
* nb_packets = 0; * nb_packets = 0;
@ -613,8 +617,8 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_nb_samples(const OpusDe
* // reference to data[nb_packets][0] should be valid. * // reference to data[nb_packets][0] should be valid.
* if (nb_packets > 0 && ( * if (nb_packets > 0 && (
* ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) || * ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) ||
* opus_packet_get_samples_per_frame(data[nb_packets], 2000)*nb_frames > * opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames >
* TARGET_DURATION_MS*2)) * TARGET_DURATION_MS*48))
* { * {
* out_len = opus_repacketizer_out(rp, out, sizeof(out)); * out_len = opus_repacketizer_out(rp, out, sizeof(out));
* if (out_len < 0) * if (out_len < 0)
@ -648,6 +652,12 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_nb_samples(const OpusDe
* output_next_packet(out, out_len); * output_next_packet(out, out_len);
* } * }
* @endcode * @endcode
*
* 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 struct OpusRepacketizer OpusRepacketizer; typedef struct OpusRepacketizer OpusRepacketizer;
@ -658,7 +668,7 @@ typedef struct OpusRepacketizer OpusRepacketizer;
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void); OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void);
/** (Re)initializes a previously allocated repacketizer state. /** (Re)initializes a previously allocated repacketizer state.
* The state must be the size returned by opus_repacketizer_get_size(). * 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 * This can be used for applications which use their own allocator instead of
* malloc(). * malloc().
* It must also be called to reset the queue of packets waiting to be * It must also be called to reset the queue of packets waiting to be
@ -676,7 +686,8 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void);
*/ */
OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
/** Allocates and initializes a repacketizer state. /** Allocates memory and initializes the new repacketizer with
* opus_repacketizer_init().
*/ */
OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void); OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void);