jitter.h

Go to the documentation of this file.

/*
 * jitter.h
 *
 * Jitter buffer support
 *
 * Open H323 Library
 *
 * Copyright (c) 1999-2001 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open H323 Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions of this code were written with the assisance of funding from
 * Vovida Networks, Inc. http://www.vovida.com.
 *
 * Contributor(s): ______________________________________.
 *
 */

#ifndef OPAL_RTP_JITTER_H
#define OPAL_RTP_JITTER_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal_config.h>

#include <opal/mediatype.h>
#include <rtp/rtp.h>


class OpalManager;



class OpalJitterBuffer : public PObject
{
    PCLASSINFO(OpalJitterBuffer, PObject);
  public:
    struct Params
    {
      unsigned m_minJitterDelay;      
      unsigned m_maxJitterDelay;      
      unsigned m_currentJitterDelay;  
      unsigned m_jitterGrowTime;      
      unsigned m_jitterShrinkPeriod;  
      unsigned m_jitterShrinkTime;    
      unsigned m_silenceShrinkPeriod; 
      unsigned m_silenceShrinkTime;   
      unsigned m_jitterDriftPeriod;   
      unsigned m_overrunFactor;       

      Params(
        unsigned minJitterDelay = 40,
        unsigned maxJitterDelay = 250
      )
        : m_minJitterDelay(minJitterDelay)
        , m_maxJitterDelay(maxJitterDelay)
        , m_currentJitterDelay(m_minJitterDelay)
        , m_jitterGrowTime(10)
        , m_jitterShrinkPeriod(1000)
        , m_jitterShrinkTime(5)
        , m_silenceShrinkPeriod(5000)
        , m_silenceShrinkTime(20)
        , m_jitterDriftPeriod(500)
        , m_overrunFactor(2)
      { }
    };

    struct Init : Params
    {
      Init(
        const OpalManager & manager,
        unsigned timeUnits
      );
      Init(
        const OpalMediaType & mediaType,
        unsigned minJitterDelay,
        unsigned maxJitterDelay,
        unsigned timeUnits = 8,
        PINDEX packetSize = 2048
        ) : Params(minJitterDelay, maxJitterDelay)
          , m_mediaType(mediaType)
          , m_timeUnits(timeUnits)
          , m_packetSize(packetSize)
      { }

      OpalMediaType m_mediaType;
      unsigned      m_timeUnits;           
      PINDEX        m_packetSize;          
    };

    OpalJitterBuffer(
      const Init & init  
    );

    virtual ~OpalJitterBuffer();

    // Create an appropriate jitter buffer for the media type
    static OpalJitterBuffer * Create(
      const OpalMediaType & mediaType,
      const Init & init  
    );

    virtual void SetDelay(
      const Init & init  
    );

    virtual void Close() = 0;

    virtual void Restart() = 0;

    virtual bool WriteData(
      const RTP_DataFrame & frame,        
      const PTimeInterval & tick = PTimer::Tick() 
    ) = 0;

    virtual bool ReadData(
      RTP_DataFrame & frame,              
      const PTimeInterval & timeout = PMaxTimeInterval  
      PTRACE_PARAM(, const PTimeInterval & tick = PMaxTimeInterval)
    ) = 0;

    virtual RTP_Timestamp GetCurrentJitterDelay() const { return 0; }

    virtual RTP_Timestamp GetPacketTime() const { return 0; }

    unsigned GetTimeUnits() const { return m_timeUnits; }
    
    RTP_Timestamp GetMinJitterDelay() const;
    
    RTP_Timestamp GetMaxJitterDelay() const;

    unsigned GetPacketsTooLate() const;

    unsigned GetBufferOverruns() const;

  protected:
    const unsigned  m_timeUnits;
    PINDEX          m_packetSize;
    RTP_Timestamp   m_minJitterDelay;      
    RTP_Timestamp   m_maxJitterDelay;      
    unsigned        m_packetsTooLate;
    unsigned        m_bufferOverruns;

    class Analyser;
    Analyser * m_analyser;

    PDECLARE_MUTEX(m_bufferMutex);
};


typedef PParamFactory<OpalJitterBuffer, OpalJitterBuffer::Init, OpalMediaType> OpalJitterBufferFactory;


class OpalAudioJitterBuffer : public OpalJitterBuffer
{
  PCLASSINFO(OpalAudioJitterBuffer, OpalJitterBuffer);

  public:
    OpalAudioJitterBuffer(
      const Init & init  
    );
    
    virtual ~OpalAudioJitterBuffer();

    void PrintOn(
      ostream & strm
    ) const;

    virtual void SetDelay(
      const Init & init  
    );

    virtual void Close();

    virtual void Restart();

    virtual bool WriteData(
      const RTP_DataFrame & frame,        
      const PTimeInterval & tick = PTimer::Tick() 
    );

    virtual bool ReadData(
      RTP_DataFrame & frame,              
      const PTimeInterval & timeout = PMaxTimeInterval  
      PTRACE_PARAM(, const PTimeInterval & tick = PMaxTimeInterval)
    );

    virtual RTP_Timestamp GetCurrentJitterDelay() const;

    virtual RTP_Timestamp GetPacketTime() const;

    unsigned GetMaxConsecutiveMarkerBits() const { return m_maxConsecutiveMarkerBits; }

    void SetMaxConsecutiveMarkerBits(unsigned max) { m_maxConsecutiveMarkerBits = max; }

  protected:
    void InternalReset();
    RTP_Timestamp CalculateRequiredTimestamp(RTP_Timestamp playOutTimestamp) const;
    enum AdjustResult {
      e_Unchanged,
      e_Decreased,
      e_Increased,
      e_ReachedMinimum,
      e_ReachedMaximum
    };
    friend ostream & operator<<(ostream & strm, const AdjustResult adjusted);
    AdjustResult AdjustCurrentJitterDelay(int delta);

    int           m_jitterGrowTime;      
    RTP_Timestamp m_jitterShrinkPeriod;  
    int           m_jitterShrinkTime;    
    RTP_Timestamp m_silenceShrinkPeriod; 
    int           m_silenceShrinkTime;   
    RTP_Timestamp m_jitterDriftPeriod;
    unsigned      m_overrunFactor;

    bool     m_closed;
    int      m_currentJitterDelay;
    unsigned m_consecutiveMarkerBits;
    unsigned m_maxConsecutiveMarkerBits;
    unsigned m_consecutiveLatePackets;
    unsigned m_consecutiveOverflows;
    unsigned m_consecutiveEmpty;

    unsigned           m_frameTimeCount;
    uint64_t           m_frameTimeSum;
    RTP_Timestamp      m_packetTime;
    RTP_SequenceNumber m_lastSequenceNum;
    RTP_Timestamp      m_lastTimestamp;
    RTP_SyncSourceId   m_lastSyncSource;
    int                m_lastBufferSize;
    RTP_Timestamp      m_bufferStaticTime;
    RTP_Timestamp      m_bufferLowTime;
    RTP_Timestamp      m_bufferEmptiedTime;
    int                m_timestampDelta;

    enum {
      e_SynchronisationStart,
      e_SynchronisationFill,
      e_SynchronisationShrink,
      e_SynchronisationDone
    } m_synchronisationState;

    typedef std::map<RTP_Timestamp, RTP_DataFrame> FrameMap;
    FrameMap   m_frames;
    PSemaphore m_frameCount;

    PTimeInterval m_lastInsertTick;
#if PTRACING
    PTimeInterval m_lastRemoveTick;
  public:
    static unsigned sm_EveryPacketLogLevel;
#endif
};


class OpalNonJitterBuffer : public OpalJitterBuffer
{
    PCLASSINFO(OpalNonJitterBuffer, OpalJitterBuffer);
  public:
    OpalNonJitterBuffer(
      const Init & init  
    );

    virtual void Close();

    virtual void Restart();

    virtual bool WriteData(
      const RTP_DataFrame & frame,        
      const PTimeInterval & tick = PTimer::Tick() 
    );

    virtual bool ReadData(
      RTP_DataFrame & frame,              
      const PTimeInterval & timeout = PMaxTimeInterval  
      PTRACE_PARAM(, const PTimeInterval & tick = PMaxTimeInterval)
    );

  protected:
    PSyncQueue<RTP_DataFrame> m_queue;
};


#endif // OPAL_RTP_JITTER_H