Adds pass-through support for codec CELT.
[asterisk/asterisk.git] / include / asterisk / format.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2010, Digium, Inc.
5  *
6  * David Vossel <dvossel@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20  * \file
21  * \brief Format API
22  *
23  * \author David Vossel <dvossel@digium.com>
24  */
25
26 #ifndef _AST_FORMAT_H_
27 #define _AST_FORMAT_H_
28
29 #include "asterisk/astobj2.h"
30 #include "asterisk/silk.h"
31 #include "asterisk/celt.h"
32 #define AST_FORMAT_ATTR_SIZE 128
33 #define AST_FORMAT_INC 100000
34
35 /*! This is the value that ends a var list of format attribute
36  * key value pairs. */
37 #define AST_FORMAT_ATTR_END -1
38
39 /* \brief Format Categories*/
40 enum ast_format_type {
41         AST_FORMAT_TYPE_AUDIO = 1 * AST_FORMAT_INC,
42         AST_FORMAT_TYPE_VIDEO = 2 * AST_FORMAT_INC,
43         AST_FORMAT_TYPE_IMAGE = 3 * AST_FORMAT_INC,
44         AST_FORMAT_TYPE_TEXT  = 4 * AST_FORMAT_INC,
45 };
46
47 enum ast_format_id {
48         /*! G.723.1 compression */
49         AST_FORMAT_G723_1           = 1 + AST_FORMAT_TYPE_AUDIO,
50         /*! GSM compression */
51         AST_FORMAT_GSM              = 2 + AST_FORMAT_TYPE_AUDIO,
52         /*! Raw mu-law data (G.711) */
53         AST_FORMAT_ULAW             = 3 + AST_FORMAT_TYPE_AUDIO,
54         /*! Raw A-law data (G.711) */
55         AST_FORMAT_ALAW             = 4 + AST_FORMAT_TYPE_AUDIO,
56         /*! ADPCM (G.726, 32kbps, AAL2 codeword packing) */
57         AST_FORMAT_G726_AAL2        = 5 + AST_FORMAT_TYPE_AUDIO,
58         /*! ADPCM (IMA) */
59         AST_FORMAT_ADPCM            = 6 + AST_FORMAT_TYPE_AUDIO,
60         /*! LPC10, 180 samples/frame */
61         AST_FORMAT_LPC10            = 7 + AST_FORMAT_TYPE_AUDIO,
62         /*! G.729A audio */
63         AST_FORMAT_G729A            = 8 + AST_FORMAT_TYPE_AUDIO,
64         /*! SpeeX Free Compression */
65         AST_FORMAT_SPEEX            = 9 + AST_FORMAT_TYPE_AUDIO,
66         /*! iLBC Free Compression */
67         AST_FORMAT_ILBC             = 10 + AST_FORMAT_TYPE_AUDIO,
68         /*! ADPCM (G.726, 32kbps, RFC3551 codeword packing) */
69         AST_FORMAT_G726             = 11 + AST_FORMAT_TYPE_AUDIO,
70         /*! G.722 */
71         AST_FORMAT_G722             = 12 + AST_FORMAT_TYPE_AUDIO,
72         /*! G.722.1 (also known as Siren7, 32kbps assumed) */
73         AST_FORMAT_SIREN7           = 13 + AST_FORMAT_TYPE_AUDIO,
74         /*! G.722.1 Annex C (also known as Siren14, 48kbps assumed) */
75         AST_FORMAT_SIREN14          = 14 + AST_FORMAT_TYPE_AUDIO,
76         /*! G.719 (64 kbps assumed) */
77         AST_FORMAT_G719             = 15 + AST_FORMAT_TYPE_AUDIO,
78         /*! SpeeX Wideband (16kHz) Free Compression */
79         AST_FORMAT_SPEEX16          = 16 + AST_FORMAT_TYPE_AUDIO,
80         /*! Raw mu-law data (G.711) */
81         AST_FORMAT_TESTLAW          = 17 + AST_FORMAT_TYPE_AUDIO,
82         /*! SILK format */
83         AST_FORMAT_SILK             = 18 + AST_FORMAT_TYPE_AUDIO,
84         /*! Raw 16-bit Signed Linear (8000 Hz) PCM */
85         AST_FORMAT_SLINEAR          = 19 + AST_FORMAT_TYPE_AUDIO,
86         /*! Raw 16-bit Signed Linear (12000 Hz) PCM */
87         AST_FORMAT_SLINEAR12        = 20 + AST_FORMAT_TYPE_AUDIO,
88         /*! Raw 16-bit Signed Linear (16000 Hz) PCM */
89         AST_FORMAT_SLINEAR16        = 21 + AST_FORMAT_TYPE_AUDIO,
90         /*! Raw 16-bit Signed Linear (24000 Hz) PCM */
91         AST_FORMAT_SLINEAR24        = 22 + AST_FORMAT_TYPE_AUDIO,
92         /*! Raw 16-bit Signed Linear (32000 Hz) PCM */
93         AST_FORMAT_SLINEAR32        = 23 + AST_FORMAT_TYPE_AUDIO,
94         /*! Raw 16-bit Signed Linear (44100 Hz) PCM just because we can. */
95         AST_FORMAT_SLINEAR44        = 24 + AST_FORMAT_TYPE_AUDIO,
96         /*! Raw 16-bit Signed Linear (48000 Hz) PCM */
97         AST_FORMAT_SLINEAR48        = 25 + AST_FORMAT_TYPE_AUDIO,
98         /*! Raw 16-bit Signed Linear (96000 Hz) PCM */
99         AST_FORMAT_SLINEAR96        = 26 + AST_FORMAT_TYPE_AUDIO,
100         /*! Raw 16-bit Signed Linear (192000 Hz) PCM.  maybe we're taking this too far. */
101         AST_FORMAT_SLINEAR192       = 27 + AST_FORMAT_TYPE_AUDIO,
102         AST_FORMAT_SPEEX32          = 28 + AST_FORMAT_TYPE_AUDIO,
103         AST_FORMAT_CELT             = 29 + AST_FORMAT_TYPE_AUDIO,
104
105         /*! H.261 Video */
106         AST_FORMAT_H261             = 1 + AST_FORMAT_TYPE_VIDEO,
107         /*! H.263 Video */
108         AST_FORMAT_H263             = 2 + AST_FORMAT_TYPE_VIDEO,
109         /*! H.263+ Video */
110         AST_FORMAT_H263_PLUS        = 3 + AST_FORMAT_TYPE_VIDEO,
111         /*! H.264 Video */
112         AST_FORMAT_H264             = 4 + AST_FORMAT_TYPE_VIDEO,
113         /*! MPEG4 Video */
114         AST_FORMAT_MP4_VIDEO        = 5 + AST_FORMAT_TYPE_VIDEO,
115
116         /*! JPEG Images */
117         AST_FORMAT_JPEG             = 1 + AST_FORMAT_TYPE_IMAGE,
118         /*! PNG Images */
119         AST_FORMAT_PNG              = 2 + AST_FORMAT_TYPE_IMAGE,
120
121         /*! T.140 RED Text format RFC 4103 */
122         AST_FORMAT_T140RED          = 1 + AST_FORMAT_TYPE_TEXT,
123         /*! T.140 Text format - ITU T.140, RFC 4103 */
124         AST_FORMAT_T140             = 2 + AST_FORMAT_TYPE_TEXT,
125 };
126
127 /*! Determine what type of media a ast_format_id is. */
128 #define AST_FORMAT_GET_TYPE(id) (((int) (id / AST_FORMAT_INC)) * AST_FORMAT_INC)
129
130
131 /*! \brief This structure contains the buffer used for format attributes */
132 struct ast_format_attr {
133         /*! The buffer formats can use to represent attributes */
134         uint8_t format_attr[AST_FORMAT_ATTR_SIZE];
135         /*! If a format's payload needs to pass through that a new marker is required
136          * for RTP, this variable will be set. */
137         uint8_t rtp_marker_bit;
138 };
139
140 /*! \brief Represents a media format within Asterisk. */
141 struct ast_format {
142         /*! The unique id representing this format from all the other formats. */
143         enum ast_format_id id;
144         /*!  Attribute structure used to associate attributes with a format. */
145         struct ast_format_attr fattr;
146 };
147
148 enum ast_format_cmp_res {
149         /*! structure 1 is identical to structure 2. */
150         AST_FORMAT_CMP_EQUAL = 0,
151         /*! structure 1 contains elements not in structure 2. */
152         AST_FORMAT_CMP_NOT_EQUAL,
153         /*! structure 1 is a proper subset of the elements in structure 2.*/
154         AST_FORMAT_CMP_SUBSET,
155 };
156
157 /*! \brief Definition of supported media formats (codecs) */
158 struct ast_format_list {
159         struct ast_format format; /*!< The unique format. */
160         char name[64];  /*!< short name */
161         unsigned int samplespersecond; /*!< Number of samples per second (8000/16000) */
162         char desc[128]; /*!< Description */
163         int fr_len;     /*!< Single frame length in bytes */
164         int min_ms;     /*!< Min value */
165         int max_ms;     /*!< Max value */
166         int inc_ms;     /*!< Increment */
167         int def_ms;     /*!< Default value */
168         unsigned int flags;     /*!< Smoother flags */
169         int cur_ms;     /*!< Current value */
170         int custom_entry;
171 };
172
173 /*! \brief A format must register an attribute interface if it requires the use of the format attributes void pointer */
174 struct ast_format_attr_interface {
175         /*! format type */
176         enum ast_format_id id;
177
178         /*! \brief Determine if format_attr 1 is a subset of format_attr 2.
179          *
180          * \retval ast_format_cmp_res representing the result of comparing fattr1 and fattr2.
181          */
182         enum ast_format_cmp_res (* const format_attr_cmp)(const struct ast_format_attr *fattr1, const struct ast_format_attr *fattr2);
183
184         /*! \brief Get joint attributes of same format type if they exist.
185          *
186          * \retval 0 if joint attributes exist
187          * \retval -1 if no joint attributes are present
188          */
189         int (* const format_attr_get_joint)(const struct ast_format_attr *fattr1, const struct ast_format_attr *fattr2, struct ast_format_attr *result);
190
191         /*! \brief Set format capabilities from a list of key value pairs ending with AST_FORMAT_ATTR_END.
192          * \note This function does not need to call va_end of the va_list. */
193         void (* const format_attr_set)(struct ast_format_attr *format_attr, va_list ap);
194
195         /*!
196          * \brief Find out if format capabilities in va_list are in format.
197          * \note This function does not need to call va_end of the va_list.
198          *
199          * \note This function is optional.  In many cases the format_attr_cmp
200          * function can be used to derive these results.  If it is possible
201          * that some format attributes have no bearing on the equality of two formats, this
202          * function must exist.
203          *
204          * \retval 0 if all attributes exist
205          * \retval -1 if any of the attributes not present
206          */
207         int (* const format_attr_isset)(const struct ast_format_attr *format_attr, va_list ap);
208
209         /*
210          * \brief Return a value for a specific format key.   Return that value in the void pointer.
211          *
212          * \note It is not expected that all key value pairs can be returned, but those that can should
213          * be documented as such.
214          *
215          * \note This function is optional if key value pairs are not allowed to be accessed.  This
216          * will result in -1 always being returned.
217          *
218          * \retval 0 Success, value was found and copied into void pointer.
219          * \retval -1 failure, Value was either not found, or not allowed to be accessed.
220          */
221         int (* const format_attr_get_val)(const struct ast_format_attr *format_attr, int key, void *val);
222 };
223
224 /*!
225  * \brief This function is used to set an ast_format object to represent a media format
226  * with optional format attributes represented by format specific key value pairs.
227  *
228  * \param format to set
229  * \param id, format id to set on format
230  * \param set_attributes, are there attributes to set on this format. 0 == false, 1 == True.
231  * \param var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
232  *
233  * \details Example usage.
234  * ast_format_set(format, AST_FORMAT_ULAW, 0); // no capability attributes are needed for ULAW
235  *
236  * ast_format_set(format, AST_FORMAT_SILK, 1, // SILK has capability attributes.
237  *        AST_FORMAT_SILK_ATTR_RATE, 24000,
238  *        AST_FORMAT_SILK_ATTR_RATE, 16000,
239  *        AST_FORMAT_SILK_ATTR_RATE, 12000,
240  *        AST_FORMAT_SILK_ATTR_RATE, 8000,
241  *        AST_FORMAT_ATTR_END);
242  *
243  * \note This function will initialize the ast_format structure.
244  *
245  * \return Pointer to ast_format object, same pointer that is passed in
246  * by the first argument.
247  */
248 struct ast_format *ast_format_set(struct ast_format *format, enum ast_format_id id, int set_attributes, ... );
249
250 /*!
251  * \brief After ast_format_set has been used on a function, this function can be used to
252  * set additional format attributes to the structure.
253  *
254  * \param format to set
255  * \param var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
256  *
257  * \details Example usage.
258  * ast_format_set(format, AST_FORMAT_SILK, 0);
259  * ast_format_append(format, // SILK has capability attributes.
260  *        AST_FORMAT_SILK_ATTR_RATE, 24000,
261  *        AST_FORMAT_SILK_ATTR_RATE, 16000,
262  *        AST_FORMAT_SILK_ATTR_RATE, 12000,
263  *        AST_FORMAT_SILK_ATTR_RATE, 8000,
264  *        AST_FORMAT_ATTR_END);
265  *
266  * \return Pointer to ast_format object, same pointer that is passed in
267  * by the first argument.
268  */
269 struct ast_format *ast_format_append(struct ast_format *format, ... );
270
271 /*!
272  * \brief Clears the format stucture.
273  */
274 void ast_format_clear(struct ast_format *format);
275
276 /*!
277  * \brief This function is used to set an ast_format object to represent a media format
278  * with optional capability attributes represented by format specific key value pairs.
279  *
280  * \details Example usage. Is this SILK format capable of 8khz
281  * is_8khz = ast_format_isset(format, AST_FORMAT_SILK_CAP_RATE, 8000);
282  *
283  * \return 0, The format key value pairs are within the capabilities defined in this structure.
284  * \return -1, The format key value pairs are _NOT_ within the capabilities of this structure.
285  */
286 int ast_format_isset(const struct ast_format *format, ... );
287
288 /*!
289  * \brief Get a value from a format containing attributes.
290  * \note The key represents the format attribute to be retrieved, and the void pointer
291  * is to the structure that value will be stored in.  It must be known what structure a
292  * key represents.
293  *
294  * \retval 0, success
295  * \retval -1, failure
296  */
297 int ast_format_get_value(const struct ast_format *format, int key, void *value);
298
299 /*!
300  * \brief Compare ast_formats structures
301  *
302  * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
303  */
304 enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2);
305
306 /*!
307  * \brief Find joint format attributes of two ast_format
308  * structures containing the same uid and return the intersection in the
309  * result structure.
310  *
311  * retval 0, joint attribute capabilities exist.
312  * retval -1, no joint attribute capabilities exist.
313  */
314 int ast_format_joint(const struct ast_format *format1, const struct ast_format *format2, struct ast_format *result);
315
316 /*!
317  * \brief copy format src into format dst.
318  */
319 void ast_format_copy(struct ast_format *dst, const struct ast_format *src);
320
321 /*!
322  * \brief Set the rtp mark value on the format to indicate to the interface
323  * writing this format's payload that a new RTP marker is necessary.
324  */
325 void ast_format_set_video_mark(struct ast_format *format);
326
327 /*!
328  * \brief Determine of the marker bit is set or not on this format.
329  *
330  * \retval 1, true
331  * \retval 0, false
332  */
333 int ast_format_get_video_mark(const struct ast_format *format);
334
335 /*!
336  * \brief ast_format to old bitfield format represenatation
337  *
338  * \note This is only to be used for IAX2 compatibility 
339  *
340  * \retval iax2 representation of ast_format
341  * \retval 0, if no representation existis for iax2
342  */
343 uint64_t ast_format_to_old_bitfield(const struct ast_format *format);
344
345 /*!
346  * \brief ast_format_id to old bitfield format represenatation
347  *
348  */
349 uint64_t ast_format_id_to_old_bitfield(enum ast_format_id id);
350
351 /*!
352  * \brief convert old bitfield format to ast_format represenatation
353  * \note This is only to be used for IAX2 compatibility 
354  *
355  * \retval on success, pointer to the dst format in the input parameters
356  * \retval on failure, NULL
357  */
358 struct ast_format *ast_format_from_old_bitfield(struct ast_format *dst, uint64_t src);
359
360 /*!
361  * \brief convert old bitfield format to ast_format_id value
362  */
363 enum ast_format_id ast_format_id_from_old_bitfield(uint64_t src);
364
365 /*!
366  * \brief Retrieve the global format list in a read only array.
367  * \note ast_format_list_destroy must be called on every format
368  * list retrieved from this function.
369  */
370 const struct ast_format_list *ast_format_list_get(size_t *size);
371
372 /*!
373  * \brief Destroy an ast_format_list gotten from ast_format_list_get()
374  */
375 const struct ast_format_list *ast_format_list_destroy(const struct ast_format_list *list);
376
377 /*! \brief Get the name of a format
378  * \param format id of format
379  * \return A static string containing the name of the format or "unknown" if unknown.
380  */
381 const char* ast_getformatname(const struct ast_format *format);
382
383 /*! \brief Returns a string containing all formats pertaining to an format id.
384  * \param buf a buffer for the output string
385  * \param size size of buf (bytes)
386  * \param format id.
387  * \return The return value is buf.
388  */
389 char* ast_getformatname_multiple_byid(char *buf, size_t size, enum ast_format_id id);
390
391 /*!
392  * \brief Gets a format from a name.
393  * \param name string of format
394  * \param format structure to return the format in.
395  * \return This returns the format pointer given to it on success and NULL on failure
396  */
397 struct ast_format *ast_getformatbyname(const char *name, struct ast_format *format);
398
399 /*!
400  * \brief Get a name from a format 
401  * \param format to get name of
402  * \return This returns a static string identifying the format on success, 0 on error.
403  */
404 const char *ast_codec2str(struct ast_format *format);
405
406 /*!
407  * \brief Get the sample rate for a given format.
408  */
409 int ast_format_rate(const struct ast_format *format);
410
411 /*!
412  * \brief register ast_format_attr_interface with core.
413  *
414  * \retval 0 success
415  * \retval -1 failure
416  */
417 int ast_format_attr_reg_interface(const struct ast_format_attr_interface *interface);
418
419 /*!
420  * \brief unregister format_attr interface with core.
421  *
422  * \retval 0 success
423  * \retval -1 failure
424  */
425 int ast_format_attr_unreg_interface(const struct ast_format_attr_interface *interface);
426
427 /*!
428  * \brief Determine if a format is 16bit signed linear of any sample rate. 
429  */
430 int ast_format_is_slinear(const struct ast_format *format);
431
432 /*!
433  * \brief Get the best slinear format id for a given sample rate
434  */
435 enum ast_format_id ast_format_slin_by_rate(unsigned int rate);
436 #endif /* _AST_FORMAT_H */