webrtc/modules/audio_coding/neteq/automode.h

/*
 *  Copyright (c) 2011 The WebRTC project authors. All Rights Reserved.
 *
 *  Use of this source code is governed by a BSD-style license
 *  that can be found in the LICENSE file in the root of the source
 *  tree. An additional intellectual property rights grant can be found
 *  in the file PATENTS.  All contributing project authors may
 *  be found in the AUTHORS file in the root of the source tree.
 */

/*
 * This file contains the functionality for automatic buffer level optimization.
 */

#ifndef AUTOMODE_H
#define AUTOMODE_H

#include "typedefs.h"

/*************/
/* Constants */
/*************/

/* The beta parameter defines the trade-off between delay and underrun probability. */
/* It is defined through its inverse in Q30 */
#define AUTOMODE_BETA_INV_Q30 53687091  /* 1/20 in Q30 */
#define AUTOMODE_STREAMING_BETA_INV_Q30 536871 /* 1/2000 in Q30 */

/* Forgetting factor for the inter-arrival time statistics */
#define IAT_PROB_FACT 32745       /* 0.9993 in Q15 */

/* Maximum inter-arrival time to register (in "packet-times") */
#define MAX_IAT 64
#define PEAK_HEIGHT 20            /* 0.08s in Q8 */

/* The value (1<<5) sets maximum accelerate "speed" to about 100 ms/s */
#define AUTOMODE_TIMESCALE_LIMIT (1<<5)

/* Peak mode related parameters */
/* Number of peaks in peak vector; must be a power of 2 */
#define NUM_PEAKS 8

/* Must be NUM_PEAKS-1 */
#define PEAK_INDEX_MASK 0x0007

/* Longest accepted peak distance */
#define MAX_PEAK_PERIOD 10
#define MAX_STREAMING_PEAK_PERIOD 600 /* 10 minutes */

/* Number of peaks required before peak mode can be engaged */
#define NUM_PEAKS_REQUIRED 3

/* Drift term for cumulative sum */
#define CSUM_IAT_DRIFT 2

/*******************/
/* Automode struct */
/*******************/

/* The automode struct is a sub-struct of the
 bufstats-struct (BufstatsInst_t). */

typedef struct
{

    /* Filtered current buffer level */
    uint16_t levelFiltFact; /* filter forgetting factor in Q8 */
    int buffLevelFilt; /* filtered buffer level in Q8 */

    /* Inter-arrival time (iat) statistics */
    int32_t iatProb[MAX_IAT + 1]; /* iat probabilities in Q30 */
    int16_t iatProbFact; /* iat forgetting factor in Q15 */
    uint32_t packetIatCountSamp; /* time (in timestamps) elapsed since last
     packet arrival, based on RecOut calls */
    int optBufLevel; /* current optimal buffer level in Q8 */

    /* Packet related information */
    int16_t packetSpeechLenSamp; /* speech samples per incoming packet */
    int16_t lastPackCNGorDTMF; /* indicates that the last received packet
     contained special information */
    uint16_t lastSeqNo; /* sequence number for last packet received */
    uint32_t lastTimeStamp; /* timestamp for the last packet received */
    int firstPacketReceived; /* set to zero implicitly when the instance is
     filled with zeros */
    int32_t sampleMemory; /* memory position for keeping track of how many
     samples we cut during expand */
    int16_t prevTimeScale; /* indicates that the last mode was an accelerate
     or pre-emptive expand operation */
    uint32_t timescaleHoldOff; /* counter that is shifted one step right each
     RecOut call; time-scaling allowed when it has
     reached 0 */
    int16_t extraDelayMs; /* extra delay for sync with video */

    int minimum_delay_ms; /* Desired delay, NetEq maintains this amount of
     delay unless jitter statistics suggests a higher value. */
    int maximum_delay_ms; /* Max desired delay, NetEq will not go above this
     amount of delay even if jitter statistics suggests a higher value. */

    int required_delay_q8; /* Smallest delay required. This is computed
     according to inter-arrival time and playout mode. It has the same unit
     as |optBufLevel|. */

    /* Peak-detection */
    /* vector with the latest peak periods (peak spacing in samples) */
    uint32_t peakPeriodSamp[NUM_PEAKS];
    /* vector with the latest peak heights (in packets) */
    int16_t peakHeightPkt[NUM_PEAKS];
    int16_t peakIndex; /* index for the vectors peakPeriodSamp and peakHeightPkt;
     -1 if still waiting for first peak */
    uint16_t peakThresholdPkt; /* definition of peak (in packets);
     calculated from PEAK_HEIGHT */
    uint32_t peakIatCountSamp; /* samples elapsed since last peak was observed */
    uint32_t curPeakPeriod; /* current maximum of peakPeriodSamp vector */
    int16_t curPeakHeight; /* derived from peakHeightPkt vector;
     used as optimal buffer level in peak mode */
    int16_t peakModeDisabled; /* ==0 if peak mode can be engaged; >0 if not */
    uint16_t peakFound; /* 1 if peaks are detected and extra delay is applied;
                        * 0 otherwise. */

    /* Post-call statistics */
    uint32_t countIAT500ms; /* number of times we got small network outage */
    uint32_t countIAT1000ms; /* number of times we got medium network outage */
    uint32_t countIAT2000ms; /* number of times we got large network outage */
    uint32_t longestIATms; /* mSec duration of longest network outage */

    int16_t cSumIatQ8; /* cumulative sum of inter-arrival times */
    int16_t maxCSumIatQ8; /* max cumulative sum IAT */
    uint32_t maxCSumUpdateTimer;/* time elapsed since maximum was observed */
} AutomodeInst_t;

/*************/
/* Functions */
/*************/

/****************************************************************************
 * WebRtcNetEQ_UpdateIatStatistics(...)
 *
 * Update the packet inter-arrival time statistics when a new packet arrives.
 * This function should be called for every arriving packet, with some
 * exceptions when using DTX/VAD and DTMF. A new optimal buffer level is
 * calculated after the update.
 *
 * Input:
 *		- inst	        : Automode instance
 *		- maxBufLen		: Maximum number of packets the buffer can hold
 *		- seqNumber     : RTP sequence number of incoming packet
 *      - timeStamp     : RTP timestamp of incoming packet
 *      - fsHz          : Sample rate in Hz
 *      - mdCodec       : Non-zero if the current codec is a multiple-
 *                        description codec
 *      - streamingMode : A non-zero value will increase jitter robustness (and delay)
 *
 * Output:
 *      - inst          : Updated automode instance
 *
 * Return value			:  0 - Ok
 *                        <0 - Error
 */

int WebRtcNetEQ_UpdateIatStatistics(AutomodeInst_t *inst, int maxBufLen,
                                    uint16_t seqNumber, uint32_t timeStamp,
                                    int32_t fsHz, int mdCodec, int streamingMode);

/****************************************************************************
 * WebRtcNetEQ_CalcOptimalBufLvl(...)
 *
 * Calculate the optimal buffer level based on packet inter-arrival time
 * statistics.
 *
 * Input:
 *		- inst	        : Automode instance
 *      - fsHz          : Sample rate in Hz
 *      - mdCodec       : Non-zero if the current codec is a multiple-
 *                        description codec
 *      - timeIatPkts   : Currently observed inter-arrival time in packets
 *      - streamingMode : A non-zero value will increase jitter robustness (and delay)
 *
 * Output:
 *      - inst          : Updated automode instance
 *
 * Return value			: >0 - Optimal buffer level
 *                        <0 - Error
 */

int16_t WebRtcNetEQ_CalcOptimalBufLvl(AutomodeInst_t *inst, int32_t fsHz,
                                      int mdCodec, uint32_t timeIatPkts,
                                      int streamingMode);

/****************************************************************************
 * WebRtcNetEQ_BufferLevelFilter(...)
 *
 * Update filtered buffer level. The function must be called once for each
 * RecOut call, since the timing of automode hinges on counters that are
 * updated by this function.
 *
 * Input:
 *      - curSizeMs8    : Total length of unused speech data in packet buffer
 *                        and sync buffer, in ms * 8
 *		- inst	        : Automode instance
 *		- sampPerCall	: Number of samples per RecOut call
 *      - fsMult        : Sample rate in Hz divided by 8000
 *
 * Output:
 *      - inst          : Updated automode instance
 *
 * Return value			:  0 - Ok
 *                      : <0 - Error
 */

int WebRtcNetEQ_BufferLevelFilter(int32_t curSizeMs8, AutomodeInst_t *inst,
                                  int sampPerCall, int16_t fsMult);

/****************************************************************************
 * WebRtcNetEQ_SetPacketSpeechLen(...)
 *
 * Provide the number of speech samples extracted from a packet to the
 * automode instance. Several of the calculations within automode depend
 * on knowing the packet size.
 *
 *
 * Input:
 *		- inst	        : Automode instance
 *		- newLenSamp    : Number of samples per RecOut call
 *      - fsHz          : Sample rate in Hz
 *
 * Output:
 *      - inst          : Updated automode instance
 *
 * Return value			:  0 - Ok
 *                        <0 - Error
 */

int WebRtcNetEQ_SetPacketSpeechLen(AutomodeInst_t *inst, int16_t newLenSamp,
                                   int32_t fsHz);

/****************************************************************************
 * WebRtcNetEQ_ResetAutomode(...)
 *
 * Reset the automode instance.
 *
 *
 * Input:
 *		- inst	            : Automode instance
 *		- maxBufLenPackets  : Maximum number of packets that the packet
 *                            buffer can hold (>1)
 *
 * Output:
 *      - inst              : Updated automode instance
 *
 * Return value			    :  0 - Ok
 */

int WebRtcNetEQ_ResetAutomode(AutomodeInst_t *inst, int maxBufLenPackets);

/****************************************************************************
 * WebRtcNetEQ_AverageIAT(...)
 *
 * Calculate the average inter-arrival time based on current statistics.
 * The average is expressed in parts per million relative the nominal. That is,
 * if the average inter-arrival time is equal to the nominal frame time,
 * the return value is zero. A positive value corresponds to packet spacing
 * being too large, while a negative value means that the packets arrive with
 * less spacing than expected.
 *
 *
 * Input:
 *    - inst              : Automode instance.
 *
 * Return value           : Average relative inter-arrival time in samples.
 */

int32_t WebRtcNetEQ_AverageIAT(const AutomodeInst_t *inst);

#endif /* AUTOMODE_H */