1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 #ifndef __PJMEDIA_WAV_PORT_H__ 21 #define __PJMEDIA_WAV_PORT_H__ 22 23 /** 24 * @file wav_port.h 25 * @brief WAV file player and writer. 26 */ 27 #include <pjmedia/port.h> 28 29 30 31 PJ_BEGIN_DECL 32 33 34 /** 35 * @defgroup PJMEDIA_FILE_PLAY WAV File Player 36 * @ingroup PJMEDIA_PORT 37 * @brief Audio playback from WAV file 38 * @{ 39 */ 40 41 /** 42 * WAV file player options. 43 */ 44 enum pjmedia_file_player_option 45 { 46 /** 47 * Tell the file player to return NULL frame when the whole 48 * file has been played. 49 */ 50 PJMEDIA_FILE_NO_LOOP = 1 51 }; 52 53 54 /** 55 * Additional information about the WAV player. 56 */ 57 typedef struct pjmedia_wav_player_info 58 { 59 /** 60 * Format ID of the payload. 61 */ 62 pjmedia_format_id fmt_id; 63 64 /** 65 * The number of bits per sample of the file payload. For example, 66 * the value is 16 for PCM WAV and 8 for Alaw/Ulas WAV files. 67 */ 68 unsigned payload_bits_per_sample; 69 70 /** 71 * The WAV payload size in bytes. 72 */ 73 pj_uint32_t size_bytes; 74 75 /** 76 * The WAV payload size in samples. 77 */ 78 pj_uint32_t size_samples; 79 80 } pjmedia_wav_player_info; 81 82 83 /** 84 * Create a media port to play streams from a WAV file. WAV player port 85 * supports for reading WAV file with uncompressed 16 bit PCM format or 86 * compressed G.711 A-law/U-law format. 87 * 88 * @param pool Pool to create memory buffers for this port. 89 * @param filename File name to open. 90 * @param ptime The duration (in miliseconds) of each frame read 91 * from this port. If the value is zero, the default 92 * duration (20ms) will be used. 93 * @param flags Port creation flags. 94 * @param buff_size Buffer size to be allocated. If the value is zero or 95 * negative, the port will use default buffer size (which 96 * is about 4KB). 97 * @param p_port Pointer to receive the file port instance. 98 * 99 * @return PJ_SUCCESS on success. 100 */ 101 PJ_DECL(pj_status_t) pjmedia_wav_player_port_create( pj_pool_t *pool, 102 const char *filename, 103 unsigned ptime, 104 unsigned flags, 105 pj_ssize_t buff_size, 106 pjmedia_port **p_port ); 107 108 /** 109 * Get additional info about the file player. 110 * 111 * @param port The file port. 112 * @param i The info. 113 * 114 * @return PJ_SUCCESS on success or the appropriate error code. 115 */ 116 PJ_DECL(pj_status_t) pjmedia_wav_player_get_info(pjmedia_port *port, 117 pjmedia_wav_player_info *i); 118 119 /** 120 * Get the data length, in bytes. 121 * 122 * @param port The file player port. 123 * 124 * @return The length of the data, in bytes. On error, the 125 * error code is given as negative value. 126 */ 127 PJ_DECL(pj_ssize_t) pjmedia_wav_player_get_len(pjmedia_port *port); 128 129 130 /** 131 * Set the file play position of WAV player. 132 * 133 * @param port The file player port. 134 * @param offset Playback position in bytes, relative to the start of 135 * the payload. 136 * 137 * @return PJ_SUCCESS on success. 138 */ 139 PJ_DECL(pj_status_t) pjmedia_wav_player_port_set_pos( pjmedia_port *port, 140 pj_uint32_t offset ); 141 142 143 /** 144 * Get the file play position of WAV player, in bytes. 145 * 146 * @param port The file player port. 147 * 148 * @return The current play position, in bytes. On error, the 149 * error code is given as negative value. 150 */ 151 PJ_DECL(pj_ssize_t) pjmedia_wav_player_port_get_pos( pjmedia_port *port ); 152 153 154 #if !DEPRECATED_FOR_TICKET_2251 155 /** 156 * Register a callback to be called when the file reading has reached the 157 * end of file. If the file is set to play repeatedly, then the callback 158 * will be called multiple times. Note that only one callback can be 159 * registered for each file port. 160 * 161 * @param port The file player port. 162 * @param user_data User data to be specified in the callback 163 * @param cb Callback to be called. If the callback returns non- 164 * PJ_SUCCESS, the playback will stop. Note that if 165 * application destroys the file port in the callback, 166 * it must return non-PJ_SUCCESS here. 167 * 168 * @return PJ_SUCCESS on success. 169 */ 170 PJ_DECL(pj_status_t) 171 pjmedia_wav_player_set_eof_cb( pjmedia_port *port, 172 void *user_data, 173 pj_status_t (*cb)(pjmedia_port *port, 174 void *usr_data)); 175 #endif 176 177 178 /** 179 * Register a callback to be called when the file reading has reached the 180 * end of file. If the file is set to play repeatedly, then the callback 181 * will be called multiple times. Note that only one callback can be 182 * registered for each file port. 183 * 184 * @param port The file player port. 185 * @param user_data User data to be specified in the callback 186 * @param cb Callback to be called. Note that if 187 * application wishes to stop the playback, it 188 * can disconnect the port in the callback, and 189 * only after all connections have been removed 190 * could the application safely destroy the port. 191 * 192 * @return PJ_SUCCESS on success. 193 */ 194 PJ_DECL(pj_status_t) 195 pjmedia_wav_player_set_eof_cb2(pjmedia_port *port, 196 void *user_data, 197 void (*cb)(pjmedia_port *port, 198 void *usr_data)); 199 200 201 /** 202 * @} 203 */ 204 205 206 /** 207 * @defgroup PJMEDIA_FILE_REC File Writer (Recorder) 208 * @ingroup PJMEDIA_PORT 209 * @brief Audio capture/recording to WAV file 210 * @{ 211 */ 212 213 214 /** 215 * WAV file writer options. 216 */ 217 enum pjmedia_file_writer_option 218 { 219 /** 220 * Tell the file writer to save the audio in PCM format. 221 */ 222 PJMEDIA_FILE_WRITE_PCM = 0, 223 224 /** 225 * Tell the file writer to save the audio in G711 Alaw format. 226 */ 227 PJMEDIA_FILE_WRITE_ALAW = 1, 228 229 /** 230 * Tell the file writer to save the audio in G711 Alaw format. 231 */ 232 PJMEDIA_FILE_WRITE_ULAW = 2, 233 }; 234 235 236 /** 237 * Create a media port to record streams to a WAV file. Note that the port 238 * must be closed properly (with #pjmedia_port_destroy()) so that the WAV 239 * header can be filled with correct values (such as the file length). 240 * WAV writer port supports for writing audio in uncompressed 16 bit PCM format 241 * or compressed G.711 U-law/A-law format, this needs to be specified in 242 * \a flags param. 243 * 244 * @param pool Pool to create memory buffers for this port. 245 * @param filename File name. 246 * @param clock_rate The sampling rate. 247 * @param channel_count Number of channels. 248 * @param samples_per_frame Number of samples per frame. 249 * @param bits_per_sample Number of bits per sample (eg 16). 250 * @param flags Port creation flags, see 251 * #pjmedia_file_writer_option. 252 * @param buff_size Buffer size to be allocated. If the value is 253 * zero or negative, the port will use default buffer 254 * size (which is about 4KB). 255 * @param p_port Pointer to receive the file port instance. 256 * 257 * @return PJ_SUCCESS on success. 258 */ 259 PJ_DECL(pj_status_t) pjmedia_wav_writer_port_create(pj_pool_t *pool, 260 const char *filename, 261 unsigned clock_rate, 262 unsigned channel_count, 263 unsigned samples_per_frame, 264 unsigned bits_per_sample, 265 unsigned flags, 266 pj_ssize_t buff_size, 267 pjmedia_port **p_port ); 268 269 270 /** 271 * Get current writing position. Note that this does not necessarily match 272 * the size written to the file, since the WAV writer employs some internal 273 * buffering. Also the value reported here only indicates the payload size 274 * (it does not include the size of the WAV header), 275 * 276 * @param port The file writer port. 277 * 278 * @return Positive value to indicate the position (in bytes), 279 * or negative value containing the error code. 280 */ 281 PJ_DECL(pj_ssize_t) pjmedia_wav_writer_port_get_pos( pjmedia_port *port ); 282 283 284 #if !DEPRECATED_FOR_TICKET_2251 285 /** 286 * Register the callback to be called when the file writing has reached 287 * certain size. Application can use this callback, for example, to limit 288 * the size of the output file. 289 * 290 * @param port The file writer port. 291 * @param pos The file position on which the callback will be called. 292 * @param user_data User data to be specified in the callback, and will be 293 * given on the callback. 294 * @param cb Callback to be called. If the callback returns non- 295 * PJ_SUCCESS, the writing will stop. Note that if 296 * application destroys the port in the callback, it must 297 * return non-PJ_SUCCESS here. 298 * 299 * @return PJ_SUCCESS on success. 300 */ 301 PJ_DECL(pj_status_t) 302 pjmedia_wav_writer_port_set_cb( pjmedia_port *port, 303 pj_size_t pos, 304 void *user_data, 305 pj_status_t (*cb)(pjmedia_port *port, 306 void *usr_data)); 307 #endif 308 309 310 /** 311 * Register the callback to be called when the file writing has reached 312 * certain size. Application can use this callback, for example, to limit 313 * the size of the output file. 314 * 315 * @param port The file writer port. 316 * @param pos The file position on which the callback will be called. 317 * @param user_data User data to be specified in the callback, and will be 318 * given on the callback. 319 * @param cb Callback to be called. Note that if 320 * application wishes to stop the writing, it 321 * can disconnect the port in the callback, and 322 * only after all connections have been removed 323 * could the application safely destroy the port. 324 * 325 * @return PJ_SUCCESS on success. 326 */ 327 PJ_DECL(pj_status_t) 328 pjmedia_wav_writer_port_set_cb2(pjmedia_port *port, 329 pj_size_t pos, 330 void *user_data, 331 void (*cb)(pjmedia_port *port, 332 void *usr_data)); 333 334 335 /** 336 * @} 337 */ 338 339 340 PJ_END_DECL 341 342 343 #endif /* __PJMEDIA_WAV_PORT_H__ */ 344