Asterisk - The Open Source Telephony Project GIT-master-f3e88d3
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 <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)
28extern "C" {
29#endif
30
31#if 1 /* need lots of stuff... */
32#include "asterisk/frame.h"
33#include "asterisk/plc.h"
35#include "asterisk/format_cap.h"
37#endif
38
39struct 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 */
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 */
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 */
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;
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 */
242struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
243 int datalen, int samples);
244
245struct 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 */
255int __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 */
268
269/*!
270 * \brief Activate a previously deactivated translator
271 * \param t translator to activate
272 *
273 * Enables the specified translator for use.
274 */
276
277/*!
278 * \brief Deactivate a translator
279 * \param t translator to deactivate
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 * \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 */
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 * */
313struct 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 */
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 */
334struct 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 */
343unsigned 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 */
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 */
367const 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 */
374int ast_translate_init(void);
375
376#if defined(__cplusplus) || defined(c_plusplus)
377}
378#endif
379
380#endif /* _ASTERISK_TRANSLATE_H */
const char * str
Definition: app_jack.c:147
static PGresult * result
Definition: cel_pgsql.c:84
short int16_t
Definition: db.h:59
Media Format Cache API.
Format Capabilities API.
Asterisk internal frame definitions.
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
SpanDSP - a series of DSP components for telephony.
Represents a media codec within Asterisk.
Definition: codec.h:42
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
Definition of a media format.
Definition: format.c:43
Data structure associated with a single frame of data.
const char * src
Support for dynamic strings.
Definition: strings.h:623
Default structure for translators, with the basic fields and buffers, all allocated as part of the sa...
Definition: translate.h:213
struct timeval nextout
Definition: translate.h:229
struct ast_frame f
Definition: translate.h:215
void * pvt
Definition: translate.h:219
uint8_t * ui8
Definition: translate.h:224
int interleaved_stereo
Definition: translate.h:238
struct timeval nextin
Definition: translate.h:228
struct ast_trans_pvt * next
Definition: translate.h:227
struct ast_translator * t
Definition: translate.h:214
struct ast_format * explicit_dst
Definition: translate.h:237
unsigned char * uc
Definition: translate.h:222
plc_state_t * plc
Definition: translate.h:226
int datalen
actual space used in outbuf
Definition: translate.h:218
union ast_trans_pvt::@287 outbuf
int16_t * i16
Definition: translate.h:223
Descriptor of a translator.
Definition: translate.h:137
struct ast_codec * core_src_codec
Definition: translate.h:141
void(* destroy)(struct ast_trans_pvt *pvt)
Definition: translate.h:166
char name[80]
Definition: translate.h:138
void(* feedback)(struct ast_trans_pvt *pvt, struct ast_frame *feedback)
Definition: translate.h:162
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
int buf_size
size of outbuf, in bytes. Mandatory. The wrapper code will also allocate an AST_FRIENDLY_OFFSET space...
Definition: translate.h:182
struct ast_translator::@286 list
const char * format
Definition: translate.h:143
int(* framein)(struct ast_trans_pvt *pvt, struct ast_frame *in)
Definition: translate.h:154
struct ast_codec src_codec
Definition: translate.h:139
struct ast_module * module
Definition: translate.h:187
struct ast_codec * core_dst_codec
Definition: translate.h:142
int(* newpvt)(struct ast_trans_pvt *)
Definition: translate.h:151
struct ast_codec dst_codec
Definition: translate.h:140
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:1237
void ast_translator_activate(struct ast_translator *t)
Activate a previously deactivated translator.
Definition: translate.c:1378
int ast_unregister_translator(struct ast_translator *t)
Unregister a translator Unregisters the given translator.
Definition: translate.c:1350
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:566
struct ast_frame * ast_trans_frameout(struct ast_trans_pvt *pvt, int datalen, int samples)
generic frameout function
Definition: translate.c:439
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:1616
void ast_translator_deactivate(struct ast_translator *t)
Deactivate a translator.
Definition: translate.c:1386
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:1402
ast_trans_cost_table
Translator Cost Table definition.
Definition: translate.h:61
@ AST_TRANS_COST_LY_LY_DOWNSAMP
Definition: translate.h:100
@ AST_TRANS_COST_LL_LL_DOWNSAMP
Definition: translate.h:76
@ AST_TRANS_COST_LY_LY_ORIGSAMP
Definition: translate.h:90
@ AST_TRANS_COST_LL_LL_UPSAMP
Definition: translate.h:71
@ AST_TRANS_COST_LY_LL_ORIGSAMP
Definition: translate.h:88
@ AST_TRANS_COST_LL_UNKNOWN
Definition: translate.h:83
@ AST_TRANS_COST_LY_LL_DOWNSAMP
Definition: translate.h:98
@ AST_TRANS_COST_LL_LY_DOWNSAMP
Definition: translate.h:78
@ AST_TRANS_COST_LL_LY_ORIGSAMP
Definition: translate.h:68
@ AST_TRANS_COST_LY_UNKNOWN
Definition: translate.h:105
@ AST_TRANS_COST_LL_LY_UPSAMP
Definition: translate.h:73
@ AST_TRANS_COST_LY_LY_UPSAMP
Definition: translate.h:95
@ AST_TRANS_COST_LY_LL_UPSAMP
Definition: translate.h:93
@ AST_TRANS_COST_LL_LL_ORIGSAMP
Definition: translate.h:66
void ast_translator_free_path(struct ast_trans_pvt *tr)
Frees a translator path Frees the given translator path structure.
Definition: translate.c:476
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:930
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:486
unsigned int ast_translate_path_steps(struct ast_format *dest, struct ast_format *src)
Returns the number of steps required to convert from 'src' to 'dest'.
Definition: translate.c:1536
int ast_translate_init(void)
Initialize the translation matrix and index to format conversion table.
Definition: translate.c:1675
FILE * in
Definition: utils/frame.c:33