app_queue.c: Queue don't play "thank-you" when here is no hold time announcements
[asterisk/asterisk.git] / include / asterisk / translate.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@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 /*! \file
20  * \brief Support for translation of data formats.
21  * \ref translate.c
22  */
23
24 #ifndef _ASTERISK_TRANSLATE_H
25 #define _ASTERISK_TRANSLATE_H
26
27 #if defined(__cplusplus) || defined(c_plusplus)
28 extern "C" {
29 #endif
30
31 #if 1   /* need lots of stuff... */
32 #include "asterisk/frame.h"
33 #include "asterisk/plc.h"
34 #include "asterisk/linkedlists.h"
35 #include "asterisk/format_cap.h"
36 #include "asterisk/format_cache.h"
37 #endif
38
39 struct ast_trans_pvt;   /* declared below */
40
41 /*!
42  * \brief Translator Cost Table definition.
43  *
44  * \note The defined values in this table must be used to set
45  * the translator's table_cost value.
46  *
47  * \note The cost value of the first two values must always add
48  * up to be greater than the largest value defined in this table.
49  * This is done to guarantee a direct translation will always
50  * have precedence over a multi step translation.
51  *
52  * \details This table is built in a way that allows translation
53  * paths to be built that guarantee the best possible balance
54  * between performance and quality.  With this table direct
55  * translation paths between two formats will always take precedence
56  * over multi step paths, lossless intermediate steps will always
57  * be chosen over lossy intermediate steps, and preservation of
58  * sample rate across the translation will always have precedence
59  * over a path that involves any re-sampling.
60  */
61 enum ast_trans_cost_table {
62
63         /* Lossless Source Translation Costs */
64
65         /*! [lossless -> lossless] original sampling */
66         AST_TRANS_COST_LL_LL_ORIGSAMP = 400000,
67         /*! [lossless -> lossy]    original sampling */
68         AST_TRANS_COST_LL_LY_ORIGSAMP = 600000,
69
70         /*! [lossless -> lossless] up sample */
71         AST_TRANS_COST_LL_LL_UPSAMP   = 800000,
72         /*! [lossless -> lossy]    up sample */
73         AST_TRANS_COST_LL_LY_UPSAMP   = 825000,
74
75         /*! [lossless -> lossless] down sample */
76         AST_TRANS_COST_LL_LL_DOWNSAMP = 850000,
77         /*! [lossless -> lossy]    down sample */
78         AST_TRANS_COST_LL_LY_DOWNSAMP = 875000,
79
80         /*! [lossless -> unknown]    unknown.
81          * This value is for a lossless source translation
82          * with an unknown destination and or sample rate conversion. */
83         AST_TRANS_COST_LL_UNKNOWN     = 885000,
84
85         /* Lossy Source Translation Costs */
86
87         /*! [lossy -> lossless]    original sampling */
88         AST_TRANS_COST_LY_LL_ORIGSAMP = 900000,
89         /*! [lossy -> lossy]       original sampling */
90         AST_TRANS_COST_LY_LY_ORIGSAMP = 915000,
91
92         /*! [lossy -> lossless]    up sample */
93         AST_TRANS_COST_LY_LL_UPSAMP   = 930000,
94         /*! [lossy -> lossy]       up sample */
95         AST_TRANS_COST_LY_LY_UPSAMP   = 945000,
96
97         /*! [lossy -> lossless]    down sample */
98         AST_TRANS_COST_LY_LL_DOWNSAMP = 960000,
99         /*! [lossy -> lossy]       down sample */
100         AST_TRANS_COST_LY_LY_DOWNSAMP = 975000,
101
102         /*! [lossy -> unknown]    unknown.
103          * This value is for a lossy source translation
104          * with an unknown destination and or sample rate conversion. */
105         AST_TRANS_COST_LY_UNKNOWN     = 985000,
106
107 };
108
109 /*! \brief
110  * Descriptor of a translator.
111  *
112  * Name, callbacks, and various options
113  * related to run-time operation (size of buffers, auxiliary
114  * descriptors, etc).
115  *
116  * A codec registers itself by filling the relevant fields
117  * of a structure and passing it as an argument to
118  * ast_register_translator(). The structure should not be
119  * modified after a successful registration, and its address
120  * must be used as an argument to ast_unregister_translator().
121  *
122  * As a minimum, a translator should supply name, srcfmt and dstfmt,
123  * the required buf_size (in bytes) and buffer_samples (in samples),
124  * and a few callbacks (framein, frameout, feedback, sample).
125  * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
126  * spare bytes so generic routines can place data in there.
127  *
128  * Note, the translator is not supposed to do any memory allocation
129  * or deallocation, nor any locking, because all of this is done in
130  * the generic code.
131  *
132  * Translators using generic plc (packet loss concealment) should
133  * supply a non-zero plc_samples indicating the size (in samples)
134  * of artificially generated frames and incoming data.
135  * Generic plc is only available for dstfmt = SLINEAR
136  */
137 struct ast_translator {
138         char name[80];                         /*!< Name of translator */
139         struct ast_codec src_codec;                    /*!< Source codec */
140         struct ast_codec dst_codec;                        /*!< Destination codec */
141         struct ast_codec *core_src_codec;          /*!< Core registered source codec */
142         struct ast_codec *core_dst_codec;      /*!< Core registered destination codec */
143         const char *format;                                        /*!< Optional name of a cached format this translator produces */
144
145         int table_cost;                        /*!< Cost value associated with this translator based
146                                                 *   on translation cost table. */
147         int comp_cost;                         /*!< Cost value associated with this translator based
148                                                 *   on computation time. This cost value is computed based
149                                                                                         *   on the time required to translate sample data. */
150
151         int (*newpvt)(struct ast_trans_pvt *); /*!< initialize private data
152                                             *   associated with the translator */
153
154         int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
155                                                /*!< Input frame callback. Store
156                                                 *   (and possibly convert) input frame. */
157
158         struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
159                                                /*!< Output frame callback. Generate a frame
160                                                 *   with outbuf content. */
161
162         void (*feedback)(struct ast_trans_pvt *pvt, struct ast_frame *feedback);
163                                                /*!< Feedback frame callback. Handle
164                                                 *   input frame. */
165
166         void (*destroy)(struct ast_trans_pvt *pvt);
167                                                /*!< cleanup private data, if needed
168                                                 *   (often unnecessary). */
169
170         struct ast_frame * (*sample)(void);    /*!< Generate an example frame */
171
172         /*!\brief size of outbuf, in samples. Leave it 0 if you want the framein
173          * callback deal with the frame. Set it appropriately if you
174          * want the code to checks if the incoming frame fits the
175          * outbuf (this is e.g. required for plc).
176          */
177         int buffer_samples;                    /*< size of outbuf, in samples */
178
179         /*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
180          * allocate an AST_FRIENDLY_OFFSET space before.
181          */
182         int buf_size;
183
184         int desc_size;                         /*!< size of private descriptor in pvt->pvt, if any */
185         int native_plc;                        /*!< true if the translator can do native plc */
186
187         struct ast_module *module;             /*!< opaque reference to the parent module */
188
189         int active;                            /*!< Whether this translator should be used or not */
190         int src_fmt_index;                     /*!< index of the source format in the matrix table */
191         int dst_fmt_index;                     /*!< index of the destination format in the matrix table */
192         AST_LIST_ENTRY(ast_translator) list;   /*!< link field */
193 };
194
195 /*! \brief
196  * Default structure for translators, with the basic fields and buffers,
197  * all allocated as part of the same chunk of memory. The buffer is
198  * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion.
199  * 'buf' points right after this space.
200  *
201  * *_framein() routines operate in two ways:
202  * 1. some convert on the fly and place the data directly in outbuf;
203  *    in this case 'samples' and 'datalen' contain the number of samples
204  *    and number of bytes available in the buffer.
205  *    In this case we can use a generic *_frameout() routine that simply
206  *    takes whatever is there and places it into the output frame.
207  * 2. others simply store the (unconverted) samples into a working
208  *    buffer, and leave the conversion task to *_frameout().
209  *    In this case, the intermediate buffer must be in the private
210  *    descriptor, 'datalen' is left to 0, while 'samples' is still
211  *    updated with the number of samples received.
212  */
213 struct ast_trans_pvt {
214         struct ast_translator *t;
215         struct ast_frame f;         /*!< used in frameout.  This frame holds a f.subclass.format ref. */
216         int samples;                /*!< samples available in outbuf */
217         /*! \brief actual space used in outbuf */
218         int datalen;
219         void *pvt;                  /*!< more private data, if any */
220         union {
221                 char *c;                /*!< the useful portion of the buffer */
222                 unsigned char *uc;      /*!< the useful portion of the buffer */
223                 int16_t *i16;
224                 uint8_t *ui8;
225         } outbuf;
226         plc_state_t *plc;           /*!< optional plc pointer */
227         struct ast_trans_pvt *next; /*!< next in translator chain */
228         struct timeval nextin;
229         struct timeval nextout;
230         /*! If a translation path using a format with attributes requires the output
231          * to be a specific set of attributes, this variable will be set describing
232          * those attributes to the translator. Otherwise, the translator must choose
233          * a set of format attributes for the destination that preserves the quality
234          * of the audio in the best way possible. For example with the Opus Codec,
235          * explicit_dst contains an attribute which describes whether both parties
236          * want to do forward-error correction (FEC). */
237         struct ast_format *explicit_dst;
238         int interleaved_stereo;     /*!< indicates if samples are in interleaved order, for stereo lin */
239 };
240
241 /*! \brief generic frameout function */
242 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
243         int datalen, int samples);
244
245 struct ast_trans_pvt;
246
247 /*!
248  * \brief Register a translator
249  * This registers a codec translator with asterisk
250  * \param t populated ast_translator structure
251  * \param mod module handle to the module that owns this translator
252  * \retval 0 on success
253  * \retval -1 on failure
254  */
255 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
256
257 /*! \brief See \ref __ast_register_translator() */
258 #define ast_register_translator(t) __ast_register_translator(t, AST_MODULE_SELF)
259
260 /*!
261  * \brief Unregister a translator
262  * Unregisters the given translator
263  * \param t translator to unregister
264  * \retval 0 on success
265  * \retval -1 on failure
266  */
267 int ast_unregister_translator(struct ast_translator *t);
268
269 /*!
270  * \brief Activate a previously deactivated translator
271  * \param t translator to activate
272  *
273  * Enables the specified translator for use.
274  */
275 void ast_translator_activate(struct ast_translator *t);
276
277 /*!
278  * \brief Deactivate a translator
279  * \param t translator to deactivate
280  *
281  * Disables the specified translator from being used.
282  */
283 void ast_translator_deactivate(struct ast_translator *t);
284
285 /*!
286  * \brief Chooses the best translation path
287  *
288  * Given a list of sources, and a designed destination format, which should
289  * I choose?
290  *
291  * \param dst_cap destination capabilities
292  * \param src_cap source capabilities
293  * \param dst_fmt_out destination format chosen out of destination capabilities
294  * \param src_fmt_out source format chosen out of source capabilities
295  * \retval 0 on success
296  * \retval -1 if no path could be found.
297  *
298  * \note dst_cap and src_cap are not mondified.
299  */
300 int ast_translator_best_choice(struct ast_format_cap *dst_cap,
301         struct ast_format_cap *src_cap,
302         struct ast_format **dst_fmt_out,
303         struct ast_format **src_fmt_out);
304
305 /*!
306  * \brief Builds a translator path
307  * Build a path (possibly NULL) from source to dest
308  * \param dst dest destination format
309  * \param src source source format
310  * \return ast_trans_pvt on success
311  * \retval NULL on failure
312  * */
313 struct ast_trans_pvt *ast_translator_build_path(struct ast_format *dest, struct ast_format *source);
314
315 /*!
316  * \brief Frees a translator path
317  * Frees the given translator path structure
318  * \param tr translator path to get rid of
319  */
320 void ast_translator_free_path(struct ast_trans_pvt *tr);
321
322 /*!
323  * \brief translates one or more frames
324  * Apply an input frame into the translator and receive zero or one output frames.  Consume
325  * determines whether the original frame should be freed.  In case the frame type is
326  * AST_FRAME_RTCP, the frame is not translated but passed to the translator codecs
327  * via the feedback callback, and a pointer to ast_null_frame is returned after that.
328  * \param path tr translator structure to use for translation
329  * \param f frame to translate
330  * \param consume Whether or not to free the original frame
331  * \return an ast_frame of the new translation format on success
332  * \retval NULL on failure
333  */
334 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
335
336 /*!
337  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
338  * \param dest destination format
339  * \param src source format
340  * \return the number of translation steps required
341  * \retval -1 if no path is available
342  */
343 unsigned int ast_translate_path_steps(struct ast_format *dest, struct ast_format *src);
344
345 /*!
346  * \brief Find available formats
347  * \param dest possible destination formats
348  * \param src source formats
349  * \param[out] result capabilities structure to store available formats in
350  * returns the destination formats that are available in the source or translatable
351  *
352  * The result will include all formats from 'dest' that are either present
353  * in 'src' or translatable from a format present in 'src'.
354  *
355  * \note Only a single audio format and a single video format can be
356  * present in 'src', or the function will produce unexpected results.
357  */
358 void ast_translate_available_formats(struct ast_format_cap *dest, struct ast_format_cap *src, struct ast_format_cap *result);
359
360 /*!
361  * \brief Puts a string representation of the translation path into outbuf
362  * \param t translator structure containing the translation path
363  * \param str ast_str output buffer
364  * \return on success pointer to beginning of outbuf
365  * \retval "" on failure
366  */
367 const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str);
368
369 /*!
370  * \brief Initialize the translation matrix and index to format conversion table.
371  * \retval 0 on success
372  * \retval -1 on failure
373  */
374 int ast_translate_init(void);
375
376 #if defined(__cplusplus) || defined(c_plusplus)
377 }
378 #endif
379
380 #endif /* _ASTERISK_TRANSLATE_H */