1 /* Copyright (c) 2017 Jean-Marc Valin */ 2 /* 3 Redistribution and use in source and binary forms, with or without 4 modification, are permitted provided that the following conditions 5 are met: 6 7 - Redistributions of source code must retain the above copyright 8 notice, this list of conditions and the following disclaimer. 9 10 - Redistributions in binary form must reproduce the above copyright 11 notice, this list of conditions and the following disclaimer in the 12 documentation and/or other materials provided with the distribution. 13 14 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 15 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 16 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 17 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 18 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 21 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 22 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 23 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 24 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 */ 26 27 #ifndef OPUSENC_H 28 # define OPUSENC_H 29 30 /**\mainpage 31 \section Introduction 32 33 This is the documentation for the <tt>libopusenc</tt> C API. 34 35 The <tt>libopusenc</tt> package provides a convenient high-level API for 36 encoding Ogg Opus files. 37 38 \section Organization 39 40 The main API is divided into several sections: 41 - \ref encoding 42 - \ref comments 43 - \ref encoder_ctl 44 - \ref callbacks 45 - \ref error_codes 46 47 \section Overview 48 49 The <tt>libopusfile</tt> API provides an easy way to encode Ogg Opus files using 50 <tt>libopus</tt>. 51 */ 52 53 # if defined(__cplusplus) 54 extern "C" { 55 # endif 56 57 #include <stddef.h> 58 #include <opus.h> 59 60 #ifndef OPE_EXPORT 61 # if defined(WIN32) 62 # if defined(OPE_BUILD) && defined(DLL_EXPORT) 63 # define OPE_EXPORT __declspec(dllexport) 64 # else 65 # define OPE_EXPORT 66 # endif 67 # elif defined(__GNUC__) && defined(OPE_BUILD) 68 # define OPE_EXPORT __attribute__ ((visibility ("default"))) 69 # else 70 # define OPE_EXPORT 71 # endif 72 #endif 73 74 /**\defgroup error_codes Error Codes*/ 75 /*@{*/ 76 /**\name List of possible error codes 77 Many of the functions in this library return a negative error code when a 78 function fails. 79 This list provides a brief explanation of the common errors. 80 See each individual function for more details on what a specific error code 81 means in that context.*/ 82 /*@{*/ 83 84 85 /* Bump this when we change the API. */ 86 /** API version for this header. Can be used to check for features at compile time. */ 87 #define OPE_API_VERSION 0 88 89 #define OPE_OK 0 90 /* Based on the relevant libopus code minus 10. */ 91 #define OPE_BAD_ARG -11 92 #define OPE_INTERNAL_ERROR -13 93 #define OPE_UNIMPLEMENTED -15 94 #define OPE_ALLOC_FAIL -17 95 96 /* Specific to libopusenc. */ 97 #define OPE_CANNOT_OPEN -30 98 #define OPE_TOO_LATE -31 99 #define OPE_INVALID_PICTURE -32 100 #define OPE_INVALID_ICON -33 101 #define OPE_WRITE_FAIL -34 102 #define OPE_CLOSE_FAIL -35 103 104 /*@}*/ 105 /*@}*/ 106 107 108 /* These are the "raw" request values -- they should usually not be used. */ 109 #define OPE_SET_DECISION_DELAY_REQUEST 14000 110 #define OPE_GET_DECISION_DELAY_REQUEST 14001 111 #define OPE_SET_MUXING_DELAY_REQUEST 14002 112 #define OPE_GET_MUXING_DELAY_REQUEST 14003 113 #define OPE_SET_COMMENT_PADDING_REQUEST 14004 114 #define OPE_GET_COMMENT_PADDING_REQUEST 14005 115 #define OPE_SET_SERIALNO_REQUEST 14006 116 #define OPE_GET_SERIALNO_REQUEST 14007 117 #define OPE_SET_PACKET_CALLBACK_REQUEST 14008 118 /*#define OPE_GET_PACKET_CALLBACK_REQUEST 14009*/ 119 #define OPE_SET_HEADER_GAIN_REQUEST 14010 120 #define OPE_GET_HEADER_GAIN_REQUEST 14011 121 #define OPE_GET_NB_STREAMS_REQUEST 14013 122 #define OPE_GET_NB_COUPLED_STREAMS_REQUEST 14015 123 124 /**\defgroup encoder_ctl Encoding Options*/ 125 /*@{*/ 126 127 /**\name Control parameters 128 129 Macros for setting encoder options.*/ 130 /*@{*/ 131 132 #define OPE_SET_DECISION_DELAY(x) OPE_SET_DECISION_DELAY_REQUEST, __opus_check_int(x) 133 #define OPE_GET_DECISION_DELAY(x) OPE_GET_DECISION_DELAY_REQUEST, __opus_check_int_ptr(x) 134 #define OPE_SET_MUXING_DELAY(x) OPE_SET_MUXING_DELAY_REQUEST, __opus_check_int(x) 135 #define OPE_GET_MUXING_DELAY(x) OPE_GET_MUXING_DELAY_REQUEST, __opus_check_int_ptr(x) 136 #define OPE_SET_COMMENT_PADDING(x) OPE_SET_COMMENT_PADDING_REQUEST, __opus_check_int(x) 137 #define OPE_GET_COMMENT_PADDING(x) OPE_GET_COMMENT_PADDING_REQUEST, __opus_check_int_ptr(x) 138 #define OPE_SET_SERIALNO(x) OPE_SET_SERIALNO_REQUEST, __opus_check_int(x) 139 #define OPE_GET_SERIALNO(x) OPE_GET_SERIALNO_REQUEST, __opus_check_int_ptr(x) 140 /* FIXME: Add type-checking macros to these. */ 141 #define OPE_SET_PACKET_CALLBACK(x,u) OPE_SET_PACKET_CALLBACK_REQUEST, (x), (u) 142 /*#define OPE_GET_PACKET_CALLBACK(x,u) OPE_GET_PACKET_CALLBACK_REQUEST, (x), (u)*/ 143 #define OPE_SET_HEADER_GAIN(x) OPE_SET_HEADER_GAIN_REQUEST, __opus_check_int(x) 144 #define OPE_GET_HEADER_GAIN(x) OPE_GET_HEADER_GAIN_REQUEST, __opus_check_int_ptr(x) 145 #define OPE_GET_NB_STREAMS(x) OPE_GET_NB_STREAMS_REQUEST, __opus_check_int_ptr(x) 146 #define OPE_GET_NB_COUPLED_STREAMS(x) OPE_GET_NB_COUPLED_STREAMS_REQUEST, __opus_check_int_ptr(x) 147 /*@}*/ 148 /*@}*/ 149 150 /**\defgroup callbacks Callback Functions */ 151 /*@{*/ 152 153 /**\name Callback functions 154 155 These are the callbacks that can be implemented for an encoder.*/ 156 /*@{*/ 157 158 /** Called for writing a page. 159 \param user_data user-defined data passed to the callback 160 \param ptr buffer to be written 161 \param len number of bytes to be written 162 \return error code 163 \retval 0 success 164 \retval 1 failure 165 */ 166 typedef int (*ope_write_func)(void *user_data, const unsigned char *ptr, opus_int32 len); 167 168 /** Called for closing a stream. 169 \param user_data user-defined data passed to the callback 170 \return error code 171 \retval 0 success 172 \retval 1 failure 173 */ 174 typedef int (*ope_close_func)(void *user_data); 175 176 /** Called on every packet encoded (including header). 177 \param user_data user-defined data passed to the callback 178 \param packet_ptr packet data 179 \param packet_len number of bytes in the packet 180 \param flags optional flags (none defined for now so zero) 181 */ 182 typedef void (*ope_packet_func)(void *user_data, const unsigned char *packet_ptr, opus_int32 packet_len, opus_uint32 flags); 183 184 /** Callback functions for accessing the stream. */ 185 typedef struct { 186 /** Callback for writing to the stream. */ 187 ope_write_func write; 188 /** Callback for closing the stream. */ 189 ope_close_func close; 190 } OpusEncCallbacks; 191 /*@}*/ 192 /*@}*/ 193 194 /** Opaque comments struct. */ 195 typedef struct OggOpusComments OggOpusComments; 196 197 /** Opaque encoder struct. */ 198 typedef struct OggOpusEnc OggOpusEnc; 199 200 /**\defgroup comments Comments Handling */ 201 /*@{*/ 202 203 /**\name Functions for handling comments 204 205 These functions make it possible to add comments and pictures to Ogg Opus files.*/ 206 /*@{*/ 207 208 /** Create a new comments object. 209 \return Newly-created comments object. */ 210 OPE_EXPORT OggOpusComments *ope_comments_create(void); 211 212 /** Create a deep copy of a comments object. 213 \param comments Comments object to copy 214 \return Deep copy of input. */ 215 OPE_EXPORT OggOpusComments *ope_comments_copy(OggOpusComments *comments); 216 217 /** Destroys a comments object. 218 \param comments Comments object to destroy*/ 219 OPE_EXPORT void ope_comments_destroy(OggOpusComments *comments); 220 221 /** Add a comment. 222 \param[in,out] comments Where to add the comments 223 \param tag Tag for the comment (must not contain = char) 224 \param val Value for the tag 225 \return Error code 226 */ 227 OPE_EXPORT int ope_comments_add(OggOpusComments *comments, const char *tag, const char *val); 228 229 /** Add a comment as a single tag=value string. 230 \param[in,out] comments Where to add the comments 231 \param tag_and_val string of the form tag=value (must contain = char) 232 \return Error code 233 */ 234 OPE_EXPORT int ope_comments_add_string(OggOpusComments *comments, const char *tag_and_val); 235 236 /** Add a picture from a file. 237 \param[in,out] comments Where to add the comments 238 \param filename File name for the picture 239 \param picture_type Type of picture (-1 for default) 240 \param description Description (NULL means no comment) 241 \return Error code 242 */ 243 OPE_EXPORT int ope_comments_add_picture(OggOpusComments *comments, const char *filename, int picture_type, const char *description); 244 245 /** Add a picture already in memory. 246 \param[in,out] comments Where to add the comments 247 \param ptr Pointer to picture in memory 248 \param size Size of picture pointed to by ptr 249 \param picture_type Type of picture (-1 for default) 250 \param description Description (NULL means no comment) 251 \return Error code 252 */ 253 OPE_EXPORT int ope_comments_add_picture_from_memory(OggOpusComments *comments, const char *ptr, size_t size, int picture_type, const char *description); 254 255 /*@}*/ 256 /*@}*/ 257 258 /**\defgroup encoding Encoding */ 259 /*@{*/ 260 261 /**\name Functions for encoding Ogg Opus files 262 263 These functions make it possible to encode Ogg Opus files.*/ 264 /*@{*/ 265 266 /** Create a new OggOpus file. 267 \param path Path where to create the file 268 \param comments Comments associated with the stream 269 \param rate Input sampling rate (48 kHz is faster) 270 \param channels Number of channels 271 \param family Mapping family (0 for mono/stereo, 1 for surround) 272 \param[out] error Error code (NULL if no error is to be returned) 273 \return Newly-created encoder. 274 */ 275 OPE_EXPORT OggOpusEnc *ope_encoder_create_file(const char *path, OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error); 276 277 /** Create a new OggOpus stream to be handled using callbacks 278 \param callbacks Callback functions 279 \param user_data Pointer to be associated with the stream and passed to the callbacks 280 \param comments Comments associated with the stream 281 \param rate Input sampling rate (48 kHz is faster) 282 \param channels Number of channels 283 \param family Mapping family (0 for mono/stereo, 1 for surround) 284 \param[out] error Error code (NULL if no error is to be returned) 285 \return Newly-created encoder. 286 */ 287 OPE_EXPORT OggOpusEnc *ope_encoder_create_callbacks(const OpusEncCallbacks *callbacks, void *user_data, 288 OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error); 289 290 /** Create a new OggOpus stream to be used along with.ope_encoder_get_page(). 291 This is mostly useful for muxing with other streams. 292 \param comments Comments associated with the stream 293 \param rate Input sampling rate (48 kHz is faster) 294 \param channels Number of channels 295 \param family Mapping family (0 for mono/stereo, 1 for surround) 296 \param[out] error Error code (NULL if no error is to be returned) 297 \return Newly-created encoder. 298 */ 299 OPE_EXPORT OggOpusEnc *ope_encoder_create_pull(OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error); 300 301 /** Deferred initialization of the encoder to force an explicit channel mapping. This can be used to override the default channel coupling, 302 but using it for regular surround will almost certainly lead to worse quality. 303 \param[in,out] enc Encoder 304 \param family Mapping family (0 for mono/stereo, 1 for surround) 305 \param streams Total number of streams 306 \param coupled_streams Number of coupled streams 307 \param mapping Channel mapping 308 \return Error code 309 */ 310 OPE_EXPORT int ope_encoder_deferred_init_with_mapping(OggOpusEnc *enc, int family, int streams, 311 int coupled_streams, const unsigned char *mapping); 312 313 /** Add/encode any number of float samples to the stream. 314 \param[in,out] enc Encoder 315 \param pcm Floating-point PCM values in the +/-1 range (interleaved if multiple channels) 316 \param samples_per_channel Number of samples for each channel 317 \return Error code*/ 318 OPE_EXPORT int ope_encoder_write_float(OggOpusEnc *enc, const float *pcm, int samples_per_channel); 319 320 /** Add/encode any number of 16-bit linear samples to the stream. 321 \param[in,out] enc Encoder 322 \param pcm Linear 16-bit PCM values in the [-32768,32767] range (interleaved if multiple channels) 323 \param samples_per_channel Number of samples for each channel 324 \return Error code*/ 325 OPE_EXPORT int ope_encoder_write(OggOpusEnc *enc, const opus_int16 *pcm, int samples_per_channel); 326 327 /** Get the next page from the stream (only if using ope_encoder_create_pull()). 328 \param[in,out] enc Encoder 329 \param[out] page Next available encoded page 330 \param[out] len Size (in bytes) of the page returned 331 \param flush If non-zero, forces a flush of the page (if any data avaiable) 332 \return 1 if there is a page available, 0 if not. */ 333 OPE_EXPORT int ope_encoder_get_page(OggOpusEnc *enc, unsigned char **page, opus_int32 *len, int flush); 334 335 /** Finalizes the stream, but does not deallocate the object. 336 \param[in,out] enc Encoder 337 \return Error code 338 */ 339 OPE_EXPORT int ope_encoder_drain(OggOpusEnc *enc); 340 341 /** Deallocates the obect. Make sure to ope_drain() first. 342 \param[in,out] enc Encoder 343 */ 344 OPE_EXPORT void ope_encoder_destroy(OggOpusEnc *enc); 345 346 /** Ends the stream and create a new stream within the same file. 347 \param[in,out] enc Encoder 348 \param comments Comments associated with the stream 349 \return Error code 350 */ 351 OPE_EXPORT int ope_encoder_chain_current(OggOpusEnc *enc, OggOpusComments *comments); 352 353 /** Ends the stream and create a new file. 354 \param[in,out] enc Encoder 355 \param path Path where to write the new file 356 \param comments Comments associated with the stream 357 \return Error code 358 */ 359 OPE_EXPORT int ope_encoder_continue_new_file(OggOpusEnc *enc, const char *path, OggOpusComments *comments); 360 361 /** Ends the stream and create a new file (callback-based). 362 \param[in,out] enc Encoder 363 \param user_data Pointer to be associated with the new stream and passed to the callbacks 364 \param comments Comments associated with the stream 365 \return Error code 366 */ 367 OPE_EXPORT int ope_encoder_continue_new_callbacks(OggOpusEnc *enc, void *user_data, OggOpusComments *comments); 368 369 /** Write out the header now rather than wait for audio to begin. 370 \param[in,out] enc Encoder 371 \return Error code 372 */ 373 OPE_EXPORT int ope_encoder_flush_header(OggOpusEnc *enc); 374 375 /** Sets encoder options. 376 \param[in,out] enc Encoder 377 \param request Use a request macro 378 \return Error code 379 */ 380 OPE_EXPORT int ope_encoder_ctl(OggOpusEnc *enc, int request, ...); 381 382 /** Converts a libopusenc error code into a human readable string. 383 * 384 * @param error Error number 385 * @returns Error string 386 */ 387 OPE_EXPORT const char *ope_strerror(int error); 388 389 /** Returns a string representing the version of libopusenc being used at run time. 390 \return A string describing the version of this library */ 391 OPE_EXPORT const char *ope_get_version_string(void); 392 393 /** ABI version for this header. Can be used to check for features at run time. 394 \return An integer representing the ABI version */ 395 OPE_EXPORT int ope_get_abi_version(void); 396 397 /*@}*/ 398 /*@}*/ 399 400 # if defined(__cplusplus) 401 } 402 # endif 403 404 #endif 405