spandsp  0.0.6
playout.h
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * playout.h
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2005 Steve Underwood
9  *
10  * All rights reserved.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU Lesser General Public License version 2.1,
14  * as published by the Free Software Foundation.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 #if !defined(_SPANDSP_PLAYOUT_H_)
27 #define _SPANDSP_PLAYOUT_H_
28 
29 /*! \page playout_page Play-out (jitter buffering)
30 \section playout_page_sec_1 What does it do?
31 The play-out module provides a static or dynamic length buffer for received frames of
32 audio or video data. It's goal is to maximise the receiver's tolerance of jitter in the
33 timing of the received frames.
34 
35 Dynamic buffers are generally good for speech, since they adapt to provide the smallest delay
36 consistent with a low rate of packets arriving too late to be used. For things like FoIP and
37 MoIP, a static length of buffer is normally necessary. Any attempt to elastically change the
38 buffer length would wreck a modem's data flow.
39 */
40 
41 /* Return codes */
42 enum
43 {
44  PLAYOUT_OK = 0,
45  PLAYOUT_ERROR,
46  PLAYOUT_EMPTY,
47  PLAYOUT_NOFRAME,
48  PLAYOUT_FILLIN,
49  PLAYOUT_DROP
50 };
51 
52 /* Frame types */
53 #define PLAYOUT_TYPE_CONTROL 0
54 #define PLAYOUT_TYPE_SILENCE 1
55 #define PLAYOUT_TYPE_SPEECH 2
56 
57 typedef int timestamp_t;
58 
59 typedef struct playout_frame_s
60 {
61  /*! The actual frame data */
62  void *data;
63  /*! The type of frame */
64  int type;
65  /*! The timestamp assigned by the sending end */
66  timestamp_t sender_stamp;
67  /*! The timespan covered by the data in this frame */
68  timestamp_t sender_len;
69  /*! The timestamp assigned by the receiving end */
70  timestamp_t receiver_stamp;
71  /*! Pointer to the next earlier frame */
73  /*! Pointer to the next later frame */
76 
77 /*!
78  Playout (jitter buffer) descriptor. This defines the working state
79  for a single instance of playout buffering.
80 */
81 typedef struct
82 {
83  /*! TRUE if the buffer is dynamically sized */
84  int dynamic;
85  /*! The minimum length (dynamic) or fixed length (static) of the buffer */
87  /*! The maximum length (dynamic) or fixed length (static) of the buffer */
89  /*! The target filter threshold for adjusting dynamic buffering. */
91 
92  int start;
93 
94  /*! The queued frame list */
96  playout_frame_t *last_frame;
97  /*! The free frame pool */
99 
100  /*! The total frames input to the buffer, to date. */
102  /*! The total frames output from the buffer, to date. */
104  /*! The number of frames received out of sequence. */
106  /*! The number of frames which were discarded, due to late arrival. */
108  /*! The number of frames which were never received. */
110  /*! The number of frames trimmed from the stream, due to buffer shrinkage. */
112 
113  timestamp_t latest_expected;
114  /*! The present jitter adjustment */
115  timestamp_t current;
116  /*! The sender_stamp of the last speech frame */
118  /*! The duration of the last speech frame */
120 
121  int not_first;
122  /*! The time since the target buffer length was last changed. */
123  timestamp_t since_last_step;
124  /*! Filter state for tracking the packets arriving just in time */
126  /*! Filter state for tracking the packets arriving late */
127  int32_t state_late;
128  /*! The current target length of the buffer */
130  /*! The current actual length of the buffer, which may lag behind the target value */
133 
134 #if defined(__cplusplus)
135 extern "C"
136 {
137 #endif
138 
139 /*! Queue a frame
140  \param s The play-out context.
141  \param data The frame data.
142  \param sender_len Length of frame (for voice) in timestamp units.
143  \param sender_stamp Sending end's time stamp.
144  \param receiver_stamp Local time at which packet was received, in timestamp units.
145  \return One of
146  PLAYOUT_OK: Frame queued OK.
147  PLAYOUT_ERROR: Some problem occured - e.g. out of memory. */
148 SPAN_DECLARE(int) playout_put(playout_state_t *s, void *data, int type, timestamp_t sender_len, timestamp_t sender_stamp, timestamp_t receiver_stamp);
149 
150 /*! Get the next frame.
151  \param s The play-out context.
152  \param frame The frame.
153  \param sender_stamp The sender's timestamp.
154  \return One of
155  PLAYOUT_OK: Suitable frame found.
156  PLAYOUT_DROP: A frame which should be dropped was found (e.g. it arrived too late).
157  The caller should request the same time again when this occurs.
158  PLAYOUT_NOFRAME: There's no frame scheduled for this time.
159  PLAYOUT_FILLIN: Synthetic signal must be generated, as no real data is available for
160  this time (either we need to grow, or there was a lost frame).
161  PLAYOUT_EMPTY: The buffer is empty.
162  */
163 SPAN_DECLARE(int) playout_get(playout_state_t *s, playout_frame_t *frame, timestamp_t sender_stamp);
164 
165 /*! Unconditionally get the first buffered frame. This may be used to clear out the queue, and free
166  all its contents, before the context is freed.
167  \param s The play-out context.
168  \return The frame, or NULL is the queue is empty. */
169 SPAN_DECLARE(playout_frame_t *) playout_get_unconditional(playout_state_t *s);
170 
171 /*! Find the current length of the buffer.
172  \param s The play-out context.
173  \return The length of the buffer. */
174 SPAN_DECLARE(timestamp_t) playout_current_length(playout_state_t *s);
175 
176 /*! Find the time at which the next queued frame is due to play.
177  Note: This value may change backwards as freshly received out of order frames are
178  added to the buffer.
179  \param s The play-out context.
180  \return The next timestamp. */
181 SPAN_DECLARE(timestamp_t) playout_next_due(playout_state_t *s);
182 
183 /*! Reset an instance of play-out buffering.
184  NOTE: The buffer should be empty before you call this function, otherwise
185  you will leak queued frames, and some internal structures
186  \param s The play-out context.
187  \param min_length Minimum length of the buffer, in samples.
188  \param max_length Maximum length of the buffer, in samples. If this equals min_length, static
189  length buffering is used. */
190 SPAN_DECLARE(void) playout_restart(playout_state_t *s, int min_length, int max_length);
191 
192 /*! Create a new instance of play-out buffering.
193  \param min_length Minimum length of the buffer, in samples.
194  \param max_length Maximum length of the buffer, in samples. If this equals min_length, static
195  length buffering is used.
196  \return The new context */
197 SPAN_DECLARE(playout_state_t *) playout_init(int min_length, int max_length);
198 
199 /*! Release an instance of play-out buffering.
200  \param s The play-out context to be releaased
201  \return 0 if OK, else -1 */
202 SPAN_DECLARE(int) playout_release(playout_state_t *s);
203 
204 /*! Free an instance of play-out buffering.
205  \param s The play-out context to be destroyed
206  \return 0 if OK, else -1 */
207 SPAN_DECLARE(int) playout_free(playout_state_t *s);
208 
209 #if defined(__cplusplus)
210 }
211 #endif
212 
213 #endif
214 /*- End of file ------------------------------------------------------------*/
timestamp_t receiver_stamp
Definition: playout.h:70
int32_t state_late
Definition: playout.h:127
Definition: playout.h:81
playout_frame_t * first_frame
Definition: playout.h:95
timestamp_t sender_len
Definition: playout.h:68
Definition: playout.h:59
int dropable_threshold
Definition: playout.h:90
timestamp_t sender_stamp
Definition: playout.h:66
playout_frame_t * free_frames
Definition: playout.h:98
int frames_out
Definition: playout.h:103
int type
Definition: playout.h:64
int32_t state_just_in_time
Definition: playout.h:125
int min_length
Definition: playout.h:86
int frames_in
Definition: playout.h:101
int frames_late
Definition: playout.h:107
int actual_buffer_length
Definition: playout.h:131
int frames_oos
Definition: playout.h:105
int dynamic
Definition: playout.h:84
timestamp_t current
Definition: playout.h:115
int target_buffer_length
Definition: playout.h:129
struct playout_frame_s * earlier
Definition: playout.h:72
void * data
Definition: playout.h:62
struct playout_frame_s * later
Definition: playout.h:74
int max_length
Definition: playout.h:88
timestamp_t last_speech_sender_stamp
Definition: playout.h:117
timestamp_t since_last_step
Definition: playout.h:123
int frames_missing
Definition: playout.h:109
timestamp_t last_speech_sender_len
Definition: playout.h:119
int frames_trimmed
Definition: playout.h:111