198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/* Copyright (C) 2002 Jean-Marc Valin */ 298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** 398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project @file speex_jitter.h 498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project @brief Adaptive jitter buffer for Speex 598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project*/ 698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/* 798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project Redistribution and use in source and binary forms, with or without 898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project modification, are permitted provided that the following conditions 998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project are met: 1098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 1198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project - Redistributions of source code must retain the above copyright 1298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project notice, this list of conditions and the following disclaimer. 1398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 1498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project - Redistributions in binary form must reproduce the above copyright 1598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project notice, this list of conditions and the following disclaimer in the 1698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project documentation and/or other materials provided with the distribution. 1798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 1898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project - Neither the name of the Xiph.org Foundation nor the names of its 1998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project contributors may be used to endorse or promote products derived from 2098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project this software without specific prior written permission. 2198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 2298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 2398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 2498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 2598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR 2698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 2798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 2898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 2998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 3098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 3198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 3298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 3498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project*/ 3598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 3698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#ifndef SPEEX_JITTER_H 3798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define SPEEX_JITTER_H 3898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** @defgroup JitterBuffer JitterBuffer: Adaptive jitter buffer 3998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * This is the jitter buffer that reorders UDP/RTP packets and adjusts the buffer size 4098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * to maintain good quality and low latency. 4198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @{ 4298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project */ 4398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 4498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#include "speex/speex_types.h" 4598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 4698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#ifdef __cplusplus 4798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectextern "C" { 4898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#endif 4998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 5098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Generic adaptive jitter buffer state */ 5198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectstruct JitterBuffer_; 5298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 5398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Generic adaptive jitter buffer state */ 5498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projecttypedef struct JitterBuffer_ JitterBuffer; 5598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 5698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Definition of an incoming packet */ 5798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projecttypedef struct _JitterBufferPacket JitterBufferPacket; 5898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 5998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Definition of an incoming packet */ 6098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectstruct _JitterBufferPacket { 6198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project char *data; /**< Data bytes contained in the packet */ 6298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project spx_uint32_t len; /**< Length of the packet in bytes */ 6398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project spx_uint32_t timestamp; /**< Timestamp for the packet */ 6498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project spx_uint32_t span; /**< Time covered by the packet (same units as timestamp) */ 6598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project spx_uint16_t sequence; /**< RTP Sequence number if available (0 otherwise) */ 6698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project spx_uint32_t user_data; /**< Put whatever data you like here (it's ignored by the jitter buffer) */ 6798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project}; 6898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 6998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Packet has been retrieved */ 7098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_OK 0 7198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Packet is lost or is late */ 7298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_MISSING 1 7398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** A "fake" packet is meant to be inserted here to increase buffering */ 7498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_INSERTION 2 7598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** There was an error in the jitter buffer */ 7698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_INTERNAL_ERROR -1 7798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Invalid argument */ 7898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_BAD_ARGUMENT -2 7998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 8098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 8198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Set minimum amount of extra buffering required (margin) */ 8298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_SET_MARGIN 0 8398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Get minimum amount of extra buffering required (margin) */ 8498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_GET_MARGIN 1 8598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/* JITTER_BUFFER_SET_AVAILABLE_COUNT wouldn't make sense */ 8698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 8798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Get the amount of available packets currently buffered */ 8898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_GET_AVAILABLE_COUNT 3 8998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Included because of an early misspelling (will remove in next release) */ 9098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_GET_AVALIABLE_COUNT 3 9198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 9298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Assign a function to destroy unused packet. When setting that, the jitter 9398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project buffer no longer copies packet data. */ 9498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_SET_DESTROY_CALLBACK 4 9598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** */ 9698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_GET_DESTROY_CALLBACK 5 9798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 9898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Tell the jitter buffer to only adjust the delay in multiples of the step parameter provided */ 9998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_SET_DELAY_STEP 6 10098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** */ 10198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_GET_DELAY_STEP 7 10298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 10398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Tell the jitter buffer to only do concealment in multiples of the size parameter provided */ 10498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_SET_CONCEALMENT_SIZE 8 10598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_GET_CONCEALMENT_SIZE 9 10698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 10798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Absolute max amount of loss that can be tolerated regardless of the delay. Typical loss 10898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project should be half of that or less. */ 10998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_SET_MAX_LATE_RATE 10 11098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_GET_MAX_LATE_RATE 11 11198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 11298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Equivalent cost of one percent late packet in timestamp units */ 11398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_SET_LATE_COST 12 11498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#define JITTER_BUFFER_GET_LATE_COST 13 11598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 11698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 11798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Initialises jitter buffer 11898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 11998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param step_size Starting value for the size of concleanment packets and delay 12098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project adjustment steps. Can be changed at any time using JITTER_BUFFER_SET_DELAY_STEP 12198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project and JITTER_BUFFER_GET_CONCEALMENT_SIZE. 12298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @return Newly created jitter buffer state 12398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project */ 12498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source ProjectJitterBuffer *jitter_buffer_init(int step_size); 12598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 12698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Restores jitter buffer to its original state 12798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 12898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 12998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project */ 13098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectvoid jitter_buffer_reset(JitterBuffer *jitter); 13198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 13298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Destroys jitter buffer 13398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 13498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 13598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project */ 13698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectvoid jitter_buffer_destroy(JitterBuffer *jitter); 13798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 13898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Put one packet into the jitter buffer 13998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 14098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 14198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param packet Incoming packet 14298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project*/ 14398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectvoid jitter_buffer_put(JitterBuffer *jitter, const JitterBufferPacket *packet); 14498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 14598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Get one packet from the jitter buffer 14698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 14798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 14898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param packet Returned packet 14998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param desired_span Number of samples (or units) we wish to get from the buffer (no guarantee) 15098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param current_timestamp Timestamp for the returned packet 15198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project*/ 15298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectint jitter_buffer_get(JitterBuffer *jitter, JitterBufferPacket *packet, spx_int32_t desired_span, spx_int32_t *start_offset); 15398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 15498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Used right after jitter_buffer_get() to obtain another packet that would have the same timestamp. 15598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * This is mainly useful for media where a single "frame" can be split into several packets. 15698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 15798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 15898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param packet Returned packet 15998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project */ 16098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectint jitter_buffer_get_another(JitterBuffer *jitter, JitterBufferPacket *packet); 16198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 16298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Get pointer timestamp of jitter buffer 16398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 16498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 16598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project*/ 16698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectint jitter_buffer_get_pointer_timestamp(JitterBuffer *jitter); 16798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 16898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Advance by one tick 16998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 17098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 17198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project*/ 17298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectvoid jitter_buffer_tick(JitterBuffer *jitter); 17398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 17498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Telling the jitter buffer about the remaining data in the application buffer 17598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 17698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param rem Amount of data buffered by the application (timestamp units) 17798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project */ 17898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectvoid jitter_buffer_remaining_span(JitterBuffer *jitter, spx_uint32_t rem); 17998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 18098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/** Used like the ioctl function to control the jitter buffer parameters 18198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * 18298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param jitter Jitter buffer state 18398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param request ioctl-type request (one of the JITTER_BUFFER_* macros) 18498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @param ptr Data exchanged to-from function 18598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project * @return 0 if no error, -1 if request in unknown 18698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project*/ 18798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectint jitter_buffer_ctl(JitterBuffer *jitter, int request, void *ptr); 18898913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 18998913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Projectint jitter_buffer_update_delay(JitterBuffer *jitter, JitterBufferPacket *packet, spx_int32_t *start_offset); 19098913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 19198913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project/* @} */ 19298913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 19398913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#ifdef __cplusplus 19498913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project} 19598913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#endif 19698913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project 19798913fed6520d8849fb2e246be943e04474aefaThe Android Open Source Project#endif 198