spandsp  3.0.0
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 playout_frame_t;
60 
61 /*!
62  Playout (jitter buffer) descriptor. This defines the working state
63  for a single instance of playout buffering.
64 */
65 typedef struct playout_state_s playout_state_t;
66 
67 #if defined(__cplusplus)
68 extern "C"
69 {
70 #endif
71 
72 /*! Queue a frame
73  \param s The play-out context.
74  \param data The frame data.
75  \param sender_len Length of frame (for voice) in timestamp units.
76  \param sender_stamp Sending end's time stamp.
77  \param receiver_stamp Local time at which packet was received, in timestamp units.
78  \return One of
79  PLAYOUT_OK: Frame queued OK.
80  PLAYOUT_ERROR: Some problem occured - e.g. out of memory. */
81 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);
82 
83 /*! Get the next frame.
84  \param s The play-out context.
85  \param frame The frame.
86  \param sender_stamp The sender's timestamp.
87  \return One of
88  PLAYOUT_OK: Suitable frame found.
89  PLAYOUT_DROP: A frame which should be dropped was found (e.g. it arrived too late).
90  The caller should request the same time again when this occurs.
91  PLAYOUT_NOFRAME: There's no frame scheduled for this time.
92  PLAYOUT_FILLIN: Synthetic signal must be generated, as no real data is available for
93  this time (either we need to grow, or there was a lost frame).
94  PLAYOUT_EMPTY: The buffer is empty.
95  */
96 SPAN_DECLARE(int) playout_get(playout_state_t *s, playout_frame_t *frame, timestamp_t sender_stamp);
97 
98 /*! Unconditionally get the first buffered frame. This may be used to clear out the queue, and free
99  all its contents, before the context is freed.
100  \param s The play-out context.
101  \return The frame, or NULL is the queue is empty. */
102 SPAN_DECLARE(playout_frame_t *) playout_get_unconditional(playout_state_t *s);
103 
104 /*! Find the current length of the buffer.
105  \param s The play-out context.
106  \return The length of the buffer. */
107 SPAN_DECLARE(timestamp_t) playout_current_length(playout_state_t *s);
108 
109 /*! Find the time at which the next queued frame is due to play.
110  Note: This value may change backwards as freshly received out of order frames are
111  added to the buffer.
112  \param s The play-out context.
113  \return The next timestamp. */
114 SPAN_DECLARE(timestamp_t) playout_next_due(playout_state_t *s);
115 
116 /*! Reset an instance of play-out buffering.
117  NOTE: The buffer should be empty before you call this function, otherwise
118  you will leak queued frames, and some internal structures
119  \param s The play-out context.
120  \param min_length Minimum length of the buffer, in samples.
121  \param max_length Maximum length of the buffer, in samples. If this equals min_length, static
122  length buffering is used. */
123 SPAN_DECLARE(void) playout_restart(playout_state_t *s, int min_length, int max_length);
124 
125 /*! Create a new instance of play-out buffering.
126  \param min_length Minimum length of the buffer, in samples.
127  \param max_length Maximum length of the buffer, in samples. If this equals min_length, static
128  length buffering is used.
129  \return The new context */
130 SPAN_DECLARE(playout_state_t *) playout_init(int min_length, int max_length);
131 
132 /*! Release an instance of play-out buffering.
133  \param s The play-out context to be releaased
134  \return 0 if OK, else -1 */
135 SPAN_DECLARE(int) playout_release(playout_state_t *s);
136 
137 /*! Free an instance of play-out buffering.
138  \param s The play-out context to be destroyed
139  \return 0 if OK, else -1 */
140 SPAN_DECLARE(int) playout_free(playout_state_t *s);
141 
142 #if defined(__cplusplus)
143 }
144 #endif
145 
146 #endif
147 /*- End of file ------------------------------------------------------------*/
Definition: private/playout.h:29
Definition: private/playout.h:51
int min_length
Definition: private/playout.h:56
int max_length
Definition: private/playout.h:58