Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2003-2007 Benny Prijono <benny@prijono.org> |
| 4 | * |
| 5 | * This program is free software; you can redistribute it and/or modify |
| 6 | * it under the terms of the GNU General Public License as published by |
| 7 | * the Free Software Foundation; either version 2 of the License, or |
| 8 | * (at your option) any later version. |
| 9 | * |
| 10 | * This program is distributed in the hope that it will be useful, |
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | * GNU General Public License for more details. |
| 14 | * |
| 15 | * You should have received a copy of the GNU General Public License |
| 16 | * along with this program; if not, write to the Free Software |
| 17 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 18 | */ |
| 19 | |
| 20 | /* |
| 21 | * Contributed by: |
| 22 | * Toni < buldozer at aufbix dot org > |
| 23 | */ |
| 24 | |
| 25 | #ifndef __PJMEDIA_MP3_PORT_H__ |
| 26 | #define __PJMEDIA_MP3_PORT_H__ |
| 27 | |
| 28 | |
| 29 | /** |
| 30 | * @file mp3_port.h |
| 31 | * @brief MP3 writer |
| 32 | */ |
| 33 | #include <pjmedia/port.h> |
| 34 | |
| 35 | /** |
| 36 | * @defgroup PJMEDIA_MP3_FILE_REC MP3 Audio File Writer (Recorder) |
| 37 | * @ingroup PJMEDIA_PORT |
| 38 | * @brief MP3 Audio File Writer (Recorder) |
| 39 | * @{ |
| 40 | * |
| 41 | * This section describes MP3 file writer. Currently it only works on Windows |
| 42 | * using BladeEncDLL of the LAME MP3 encoder. <b>Note that the LAME_ENC.DLL |
| 43 | * file must exist in the PATH so that the encoder can work properly.</b> |
| 44 | * |
| 45 | * The MP3 file writer is created with #pjmedia_mp3_writer_port_create() which |
| 46 | * among other things specifies the desired file name and audio properties. |
| 47 | * It then takes PCM input when #pjmedia_port_put_frame() is called and encode |
| 48 | * the PCM input into MP3 streams before writing it to the .mp3 file. |
| 49 | */ |
| 50 | |
| 51 | |
| 52 | PJ_BEGIN_DECL |
| 53 | |
| 54 | |
| 55 | /** |
| 56 | * This structure contains encoding options that can be specified during |
| 57 | * MP3 writer port creation. Application should always zero the structure |
| 58 | * before setting some value to make sure that default options will be used. |
| 59 | */ |
| 60 | typedef struct pjmedia_mp3_encoder_option |
| 61 | { |
| 62 | /** Specify whether variable bit rate should be used. Variable bitrate |
| 63 | * would normally produce better quality at the expense of probably |
| 64 | * larger file. |
| 65 | */ |
| 66 | pj_bool_t vbr; |
| 67 | |
| 68 | /** Target bitrate, in bps. If VBR is enabled, this settings specifies |
| 69 | * the average bit-rate requested, and will make the encoder ignore |
| 70 | * the quality setting. For CBR, this specifies the actual bitrate, |
| 71 | * and if this option is zero, it will be set to the sampling rate |
| 72 | * multiplied by number of channels. |
| 73 | */ |
| 74 | unsigned bit_rate; |
| 75 | |
| 76 | /** Encoding quality, 0-9, with 0 is the highest quality. For VBR, the |
| 77 | * quality setting will only take effect when bit_rate setting is zero. |
| 78 | */ |
| 79 | unsigned quality; |
| 80 | |
| 81 | } pjmedia_mp3_encoder_option; |
| 82 | |
| 83 | |
| 84 | /** |
| 85 | * Create a media port to record PCM media to a MP3 file. After the port |
| 86 | * is created, application can call #pjmedia_port_put_frame() to feed the |
| 87 | * port with PCM frames. The port then will encode the PCM frame into MP3 |
| 88 | * stream, and store it to MP3 file specified in the argument. |
| 89 | * |
| 90 | * When application has finished with writing MP3 file, it must destroy the |
| 91 | * media port with #pjmedia_port_destroy() so that the MP3 file can be |
| 92 | * closed properly. |
| 93 | * |
| 94 | * @param pool Pool to create memory buffers for this port. |
| 95 | * @param filename File name. |
| 96 | * @param clock_rate The sampling rate. |
| 97 | * @param channel_count Number of channels. |
| 98 | * @param samples_per_frame Number of samples per frame. |
| 99 | * @param bits_per_sample Number of bits per sample (eg 16). |
| 100 | * @param option Optional option to set encoding parameters. |
| 101 | * @param p_port Pointer to receive the file port instance. |
| 102 | * |
| 103 | * @return PJ_SUCCESS on success. |
| 104 | */ |
| 105 | PJ_DECL(pj_status_t) |
| 106 | pjmedia_mp3_writer_port_create(pj_pool_t *pool, |
| 107 | const char *filename, |
| 108 | unsigned clock_rate, |
| 109 | unsigned channel_count, |
| 110 | unsigned samples_per_frame, |
| 111 | unsigned bits_per_sample, |
| 112 | const pjmedia_mp3_encoder_option *option, |
| 113 | pjmedia_port **p_port ); |
| 114 | |
| 115 | /** |
| 116 | * Register the callback to be called when the file writing has reached |
| 117 | * certain size. Application can use this callback, for example, to limit |
| 118 | * the size of the output file. |
| 119 | * |
| 120 | * @param port The file writer port. |
| 121 | * @param pos The file position on which the callback will be called. |
| 122 | * @param user_data User data to be specified in the callback, and will be |
| 123 | * given on the callback. |
| 124 | * @param cb Callback to be called. If the callback returns non- |
| 125 | * PJ_SUCCESS, the writing will stop. Note that if |
| 126 | * application destroys the port in the callback, it must |
| 127 | * return non-PJ_SUCCESS here. |
| 128 | * |
| 129 | * @return PJ_SUCCESS on success. |
| 130 | */ |
| 131 | PJ_DECL(pj_status_t) |
| 132 | pjmedia_mp3_writer_port_set_cb( pjmedia_port *port, |
| 133 | pj_size_t pos, |
| 134 | void *user_data, |
| 135 | pj_status_t (*cb)(pjmedia_port *port, |
| 136 | void *usr_data)); |
| 137 | |
| 138 | |
| 139 | /** |
| 140 | * @} |
| 141 | */ |
| 142 | |
| 143 | |
| 144 | PJ_END_DECL |
| 145 | |
| 146 | #endif /* __PJMEDIA_MP3_PORT_H__ */ |
| 147 | |