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 */