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