Asterisk - The Open Source Telephony Project  18.5.0
translate.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <[email protected]>
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  */
62 
63  /* Lossless Source Translation Costs */
64 
65  /*! [lossless -> lossless] original sampling */
67  /*! [lossless -> lossy] original sampling */
69 
70  /*! [lossless -> lossless] up sample */
72  /*! [lossless -> lossy] up sample */
74 
75  /*! [lossless -> lossless] down sample */
77  /*! [lossless -> lossy] down sample */
79 
80  /*! [lossless -> unknown] unknown.
81  * This value is for a lossless source translation
82  * with an unknown destination and or sample rate conversion. */
84 
85  /* Lossy Source Translation Costs */
86 
87  /*! [lossy -> lossless] original sampling */
89  /*! [lossy -> lossy] original sampling */
91 
92  /*! [lossy -> lossless] up sample */
94  /*! [lossy -> lossy] up sample */
96 
97  /*! [lossy -> lossless] down sample */
99  /*! [lossy -> lossy] down sample */
101 
102  /*! [lossy -> unknown] unknown.
103  * This value is for a lossy source translation
104  * with an unknown destination and or sample rate conversion. */
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  */
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  */
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 */
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). */
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  * \return 0 on success, -1 on failure
253  */
255 
256 /*! \brief See \ref __ast_register_translator() */
257 #define ast_register_translator(t) __ast_register_translator(t, AST_MODULE_SELF)
258 
259 /*!
260  * \brief Unregister a translator
261  * Unregisters the given tranlator
262  * \param t translator to unregister
263  * \return 0 on success, -1 on failure
264  */
266 
267 /*!
268  * \brief Activate a previously deactivated translator
269  * \param t translator to activate
270  * \return nothing
271  *
272  * Enables the specified translator for use.
273  */
275 
276 /*!
277  * \brief Deactivate a translator
278  * \param t translator to deactivate
279  * \return nothing
280  *
281  * Disables the specified translator from being used.
282  */
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  * \return Returns 0 on success, -1 if no path could be found.
296  *
297  * \note dst_cap and src_cap are not mondified.
298  */
299 int ast_translator_best_choice(struct ast_format_cap *dst_cap,
300  struct ast_format_cap *src_cap,
301  struct ast_format **dst_fmt_out,
302  struct ast_format **src_fmt_out);
303 
304 /*!
305  * \brief Builds a translator path
306  * Build a path (possibly NULL) from source to dest
307  * \param dst dest destination format
308  * \param src source source format
309  * \return ast_trans_pvt on success, NULL on failure
310  * */
311 struct ast_trans_pvt *ast_translator_build_path(struct ast_format *dest, struct ast_format *source);
312 
313 /*!
314  * \brief Frees a translator path
315  * Frees the given translator path structure
316  * \param tr translator path to get rid of
317  */
318 void ast_translator_free_path(struct ast_trans_pvt *tr);
319 
320 /*!
321  * \brief translates one or more frames
322  * Apply an input frame into the translator and receive zero or one output frames. Consume
323  * determines whether the original frame should be freed. In case the frame type is
324  * AST_FRAME_RTCP, the frame is not translated but passed to the translator codecs
325  * via the feedback callback, and a pointer to ast_null_frame is returned after that.
326  * \param path tr translator structure to use for translation
327  * \param f frame to translate
328  * \param consume Whether or not to free the original frame
329  * \return an ast_frame of the new translation format on success, NULL on failure
330  */
331 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
332 
333 /*!
334  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
335  * \param dest destination format
336  * \param src source format
337  * \return the number of translation steps required, or -1 if no path is available
338  */
339 unsigned int ast_translate_path_steps(struct ast_format *dest, struct ast_format *src);
340 
341 /*!
342  * \brief Find available formats
343  * \param dest possible destination formats
344  * \param src source formats
345  * \param result capabilities structure to store available formats in
346  *
347  * \return the destination formats that are available in the source or translatable
348  *
349  * The result will include all formats from 'dest' that are either present
350  * in 'src' or translatable from a format present in 'src'.
351  *
352  * \note Only a single audio format and a single video format can be
353  * present in 'src', or the function will produce unexpected results.
354  */
356 
357 /*!
358  * \brief Puts a string representation of the translation path into outbuf
359  * \param t translator structure containing the translation path
360  * \param str ast_str output buffer
361  * \retval on success pointer to beginning of outbuf. on failure "".
362  */
363 const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str);
364 
365 /*!
366  * \brief Initialize the translation matrix and index to format conversion table.
367  * \retval 0 on success
368  * \retval -1 on failure
369  */
370 int ast_translate_init(void);
371 
372 #if defined(__cplusplus) || defined(c_plusplus)
373 }
374 #endif
375 
376 #endif /* _ASTERISK_TRANSLATE_H */
struct ast_frame * ast_trans_frameout(struct ast_trans_pvt *pvt, int datalen, int samples)
generic frameout function
Definition: translate.c:438
int datalen
actual space used in outbuf
Definition: translate.h:218
const char * format
Definition: translate.h:143
int(* newpvt)(struct ast_trans_pvt *)
Definition: translate.h:151
int ast_translate_init(void)
Initialize the translation matrix and index to format conversion table.
Definition: translate.c:1630
Descriptor of a translator.
Definition: translate.h:137
short int16_t
Definition: db.h:59
void ast_translator_activate(struct ast_translator *t)
Activate a previously deactivated translator.
Definition: translate.c:1361
unsigned char * uc
Definition: translate.h:222
Definition of a media format.
Definition: format.c:43
plc_state_t * plc
Definition: translate.h:226
struct ast_frame * ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume)
translates one or more frames Apply an input frame into the translator and receive zero or one output...
Definition: translate.c:565
struct ast_trans_pvt * next
Definition: translate.h:227
const char * str
Definition: app_jack.c:147
void * pvt
Definition: translate.h:219
int ast_translator_best_choice(struct ast_format_cap *dst_cap, struct ast_format_cap *src_cap, struct ast_format **dst_fmt_out, struct ast_format **src_fmt_out)
Chooses the best translation path.
Definition: translate.c:1385
struct ast_codec * core_src_codec
Definition: translate.h:141
int16_t * i16
Definition: translate.h:223
void ast_translate_available_formats(struct ast_format_cap *dest, struct ast_format_cap *src, struct ast_format_cap *result)
Find available formats.
Definition: translate.c:1571
int __ast_register_translator(struct ast_translator *t, struct ast_module *module)
Register a translator This registers a codec translator with asterisk.
Definition: translate.c:1220
struct ast_module * module
Definition: translate.h:187
struct ast_trans_pvt * ast_translator_build_path(struct ast_format *dest, struct ast_format *source)
Builds a translator path Build a path (possibly NULL) from source to dest.
Definition: translate.c:485
FILE * in
Definition: utils/frame.c:33
const char * src
Asterisk internal frame definitions.
int ast_unregister_translator(struct ast_translator *t)
Unregister a translator Unregisters the given tranlator.
Definition: translate.c:1333
A set of macros to manage forward-linked lists.
uint8_t * ui8
Definition: translate.h:224
int buf_size
size of outbuf, in bytes. Mandatory. The wrapper code will also allocate an AST_FRIENDLY_OFFSET space...
Definition: translate.h:182
Format Capabilities API.
void(* destroy)(struct ast_trans_pvt *pvt)
Definition: translate.h:166
int interleaved_stereo
Definition: translate.h:238
struct ast_codec dst_codec
Definition: translate.h:140
void(* feedback)(struct ast_trans_pvt *pvt, struct ast_frame *feedback)
Definition: translate.h:162
struct ast_translator::@326 list
struct ast_format * explicit_dst
Definition: translate.h:237
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
Default structure for translators, with the basic fields and buffers, all allocated as part of the sa...
Definition: translate.h:213
struct ast_codec src_codec
Definition: translate.h:139
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
void ast_translator_deactivate(struct ast_translator *t)
Deactivate a translator.
Definition: translate.c:1369
ast_trans_cost_table
Translator Cost Table definition.
Definition: translate.h:61
const char * ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str)
Puts a string representation of the translation path into outbuf.
Definition: translate.c:928
SpanDSP - a series of DSP components for telephony.
static PGresult * result
Definition: cel_pgsql.c:88
Data structure associated with a single frame of data.
struct ast_translator * t
Definition: translate.h:214
struct ast_codec * core_dst_codec
Definition: translate.h:142
unsigned int ast_translate_path_steps(struct ast_format *dest, struct ast_format *src)
Returns the number of steps required to convert from &#39;src&#39; to &#39;dest&#39;.
Definition: translate.c:1491
Represents a media codec within Asterisk.
Definition: codec.h:42
void ast_translator_free_path(struct ast_trans_pvt *tr)
Frees a translator path Frees the given translator path structure.
Definition: translate.c:475
char name[80]
Definition: translate.h:138
int(* framein)(struct ast_trans_pvt *pvt, struct ast_frame *in)
Definition: translate.h:154
Media Format Cache API.
int buffer_samples
size of outbuf, in samples. Leave it 0 if you want the framein callback deal with the frame...
Definition: translate.h:177