Add some explanatory comments to the toxav audio code.

By @zoff99.

1 files changed, 51 insertions, 0 deletions

diff --git a/toxav/audio.c b/toxav/audio.c
index b45157c7..f2453e8e 100644
--- a/toxav/audio.c
+++ b/toxav/audio.c
@@ -180,6 +180,15 @@ void ac_iterate(ACSession *ac)
                 continue;
             }
 
+            /*
+             * frame_size = opus_decode(dec, packet, len, decoded, max_size, 0);
+             *   where
+             * packet is the byte array containing the compressed data
+             * len is the exact number of bytes contained in the packet
+             * decoded is the decoded audio data in opus_int16 (or float for opus_decode_float())
+             * max_size is the max duration of the frame in samples (per channel) that can fit
+             * into the decoded_frame array
+             */
             rc = opus_decode(ac->decoder, msg->data + 4, msg->len - 4, temp_audio_buffer, 5760, 0);
             free(msg);
         }
@@ -356,6 +365,11 @@ static struct RTPMessage *jbuf_read(struct JitterBuffer *q, int32_t *success)
 OpusEncoder *create_audio_encoder(Logger *log, int32_t bit_rate, int32_t sampling_rate, int32_t channel_count)
 {
     int status = OPUS_OK;
+    /*
+     * OPUS_APPLICATION_VOIP Process signal for improved speech intelligibility
+     * OPUS_APPLICATION_AUDIO Favor faithfulness to the original input
+     * OPUS_APPLICATION_RESTRICTED_LOWDELAY Configure the minimum possible coding delay
+     */
     OpusEncoder *rc = opus_encoder_create(sampling_rate, channel_count, OPUS_APPLICATION_VOIP, &status);
 
     if (status != OPUS_OK) {
@@ -363,6 +377,16 @@ OpusEncoder *create_audio_encoder(Logger *log, int32_t bit_rate, int32_t samplin
         return NULL;
     }
 
+
+    /*
+     * Rates from 500 to 512000 bits per second are meaningful as well as the special
+     * values OPUS_BITRATE_AUTO and OPUS_BITRATE_MAX. The value OPUS_BITRATE_MAX can
+     * be used to cause the codec to use as much rate as it can, which is useful for
+     * controlling the rate by adjusting the output buffer size.
+     *
+     * Parameters:
+     *   [in]    x   opus_int32: bitrate in bits per second.
+     */
     status = opus_encoder_ctl(rc, OPUS_SET_BITRATE(bit_rate));
 
     if (status != OPUS_OK) {
@@ -370,6 +394,14 @@ OpusEncoder *create_audio_encoder(Logger *log, int32_t bit_rate, int32_t samplin
         goto FAILURE;
     }
 
+
+    /*
+     * Configures the encoder's use of inband forward error correction.
+     * Note:
+     *   This is only applicable to the LPC layer
+     * Parameters:
+     *   [in]    x   int: FEC flag, 0 (disabled) is default
+     */
     /* Enable in-band forward error correction in codec */
     status = opus_encoder_ctl(rc, OPUS_SET_INBAND_FEC(1));
 
@@ -378,6 +410,15 @@ OpusEncoder *create_audio_encoder(Logger *log, int32_t bit_rate, int32_t samplin
         goto FAILURE;
     }
 
+
+    /*
+     * Configures the encoder's expected packet loss percentage.
+     * Higher values with trigger progressively more loss resistant behavior in
+     * the encoder at the expense of quality at a given bitrate in the lossless case,
+     * but greater quality under loss.
+     * Parameters:
+     *     [in]    x   int: Loss percentage in the range 0-100, inclusive.
+     */
     /* Make codec resistant to up to 10% packet loss
      * NOTE This could also be adjusted on the fly, rather than hard-coded,
      *      with feedback from the receiving client.
@@ -389,6 +430,16 @@ OpusEncoder *create_audio_encoder(Logger *log, int32_t bit_rate, int32_t samplin
         goto FAILURE;
     }
 
+
+    /*
+     * Configures the encoder's computational complexity.
+     *
+     * The supported range is 0-10 inclusive with 10 representing the highest complexity.
+     * The default value is 10.
+     *
+     * Parameters:
+     *   [in]    x   int: 0-10, inclusive
+     */
     /* Set algorithm to the highest complexity, maximizing compression */
     status = opus_encoder_ctl(rc, OPUS_SET_COMPLEXITY(AUDIO_OPUS_COMPLEXITY));