webrtc/modules/video_coding/jitter_estimator.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.
 */

#ifndef WEBRTC_MODULES_VIDEO_CODING_JITTER_ESTIMATOR_H_
#define WEBRTC_MODULES_VIDEO_CODING_JITTER_ESTIMATOR_H_

#include "webrtc/base/rollingaccumulator.h"
#include "webrtc/modules/video_coding/rtt_filter.h"
#include "webrtc/typedefs.h"

namespace webrtc
{

class Clock;

class VCMJitterEstimator
{
public:
    VCMJitterEstimator(const Clock* clock,
                       int32_t vcmId = 0,
                       int32_t receiverId = 0);
    virtual ~VCMJitterEstimator();
    VCMJitterEstimator& operator=(const VCMJitterEstimator& rhs);

    // Resets the estimate to the initial state
    void Reset();
    void ResetNackCount();

    // Updates the jitter estimate with the new data.
    //
    // Input:
    //          - frameDelay      : Delay-delta calculated by UTILDelayEstimate in milliseconds
    //          - frameSize       : Frame size of the current frame.
    //          - incompleteFrame : Flags if the frame is used to update the estimate before it
    //                              was complete. Default is false.
    void UpdateEstimate(int64_t frameDelayMS,
                        uint32_t frameSizeBytes,
                        bool incompleteFrame = false);

    // Returns the current jitter estimate in milliseconds and adds
    // also adds an RTT dependent term in cases of retransmission.
    //  Input:
    //          - rttMultiplier  : RTT param multiplier (when applicable).
    //
    // Return value                   : Jitter estimate in milliseconds
    int GetJitterEstimate(double rttMultiplier);

    // Updates the nack counter.
    void FrameNacked();

    // Updates the RTT filter.
    //
    // Input:
    //          - rttMs               : RTT in ms
    void UpdateRtt(int64_t rttMs);

    void UpdateMaxFrameSize(uint32_t frameSizeBytes);

    // A constant describing the delay from the jitter buffer
    // to the delay on the receiving side which is not accounted
    // for by the jitter buffer nor the decoding delay estimate.
    static const uint32_t OPERATING_SYSTEM_JITTER = 10;

protected:
    // These are protected for better testing possibilities
    double              _theta[2]; // Estimated line parameters (slope, offset)
    double              _varNoise; // Variance of the time-deviation from the line

    virtual bool LowRateExperimentEnabled();

private:
    // Updates the Kalman filter for the line describing
    // the frame size dependent jitter.
    //
    // Input:
    //          - frameDelayMS    : Delay-delta calculated by UTILDelayEstimate in milliseconds
    //          - deltaFSBytes    : Frame size delta, i.e.
    //                            : frame size at time T minus frame size at time T-1
    void KalmanEstimateChannel(int64_t frameDelayMS, int32_t deltaFSBytes);

    // Updates the random jitter estimate, i.e. the variance
    // of the time deviations from the line given by the Kalman filter.
    //
    // Input:
    //          - d_dT              : The deviation from the kalman estimate
    //          - incompleteFrame   : True if the frame used to update the estimate
    //                                with was incomplete
    void EstimateRandomJitter(double d_dT, bool incompleteFrame);

    double NoiseThreshold() const;

    // Calculates the current jitter estimate.
    //
    // Return value                 : The current jitter estimate in milliseconds
    double CalculateEstimate();

    // Post process the calculated estimate
    void PostProcessEstimate();

    // Calculates the difference in delay between a sample and the
    // expected delay estimated by the Kalman filter.
    //
    // Input:
    //          - frameDelayMS    : Delay-delta calculated by UTILDelayEstimate in milliseconds
    //          - deltaFS         : Frame size delta, i.e. frame size at time
    //                              T minus frame size at time T-1
    //
    // Return value                 : The difference in milliseconds
    double DeviationFromExpectedDelay(int64_t frameDelayMS,
                                      int32_t deltaFSBytes) const;

    double GetFrameRate() const;

    // Constants, filter parameters
    int32_t         _vcmId;
    int32_t         _receiverId;
    const double          _phi;
    const double          _psi;
    const uint32_t  _alphaCountMax;
    const double          _thetaLow;
    const uint32_t  _nackLimit;
    const int32_t   _numStdDevDelayOutlier;
    const int32_t   _numStdDevFrameSizeOutlier;
    const double          _noiseStdDevs;
    const double          _noiseStdDevOffset;

    double                _thetaCov[2][2]; // Estimate covariance
    double                _Qcov[2][2];     // Process noise covariance
    double                _avgFrameSize;   // Average frame size
    double                _varFrameSize;   // Frame size variance
    double                _maxFrameSize;   // Largest frame size received (descending
                                           // with a factor _psi)
    uint32_t        _fsSum;
    uint32_t        _fsCount;

    int64_t         _lastUpdateT;
    double                _prevEstimate;         // The previously returned jitter estimate
    uint32_t        _prevFrameSize;        // Frame size of the previous frame
    double                _avgNoise;             // Average of the random jitter
    uint32_t        _alphaCount;
    double                _filterJitterEstimate; // The filtered sum of jitter estimates

    uint32_t        _startupCount;

    int64_t         _latestNackTimestamp;  // Timestamp in ms when the latest nack was seen
    uint32_t        _nackCount;            // Keeps track of the number of nacks received,
                                                 // but never goes above _nackLimit
    VCMRttFilter          _rttFilter;

    rtc::RollingAccumulator<uint64_t> fps_counter_;
    enum ExperimentFlag { kInit, kEnabled, kDisabled };
    ExperimentFlag low_rate_experiment_;
    const Clock* clock_;
};

}  // namespace webrtc

#endif // WEBRTC_MODULES_VIDEO_CODING_JITTER_ESTIMATOR_H_