libopusenc  0.1
Stand-alone encoder library for .opus files.
opusenc.h
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 #if !defined(_opusenc_h)
28 # define _opusenc_h (1)
29 
53 # if defined(__cplusplus)
54 extern "C" {
55 # endif
56 
57 #include <opus.h>
58 
59 #ifndef OPE_EXPORT
60 # if defined(WIN32)
61 # if defined(OPE_BUILD) && defined(DLL_EXPORT)
62 # define OPE_EXPORT __declspec(dllexport)
63 # else
64 # define OPE_EXPORT
65 # endif
66 # elif defined(__GNUC__) && defined(OPE_BUILD)
67 # define OPE_EXPORT __attribute__ ((visibility ("default")))
68 # else
69 # define OPE_EXPORT
70 # endif
71 #endif
72 
82 
83 
84 /* Bump this when we change the API. */
86 #define OPE_API_VERSION 0
87 
88 #define OPE_OK 0
89 /* Based on the relevant libopus code minus 10. */
90 #define OPE_BAD_ARG -11
91 #define OPE_INTERNAL_ERROR -13
92 #define OPE_UNIMPLEMENTED -15
93 #define OPE_ALLOC_FAIL -17
94 
95 /* Specific to libopusenc. */
96 #define OPE_CANNOT_OPEN -30
97 #define OPE_TOO_LATE -31
98 #define OPE_UNRECOVERABLE -32
99 #define OPE_INVALID_PICTURE -33
100 #define OPE_INVALID_ICON -34
101 
103 
104 
105 /* These are the "raw" request values -- they should usually not be used. */
106 #define OPE_SET_DECISION_DELAY_REQUEST 14000
107 #define OPE_GET_DECISION_DELAY_REQUEST 14001
108 #define OPE_SET_MUXING_DELAY_REQUEST 14002
109 #define OPE_GET_MUXING_DELAY_REQUEST 14003
110 #define OPE_SET_COMMENT_PADDING_REQUEST 14004
111 #define OPE_GET_COMMENT_PADDING_REQUEST 14005
112 #define OPE_SET_SERIALNO_REQUEST 14006
113 #define OPE_GET_SERIALNO_REQUEST 14007
114 #define OPE_SET_PACKET_CALLBACK_REQUEST 14008
115 /*#define OPE_GET_PACKET_CALLBACK_REQUEST 14009*/
116 #define OPE_SET_HEADER_GAIN_REQUEST 14010
117 #define OPE_GET_HEADER_GAIN_REQUEST 14011
118 
121 
126 
127 #define OPE_SET_DECISION_DELAY(x) OPE_SET_DECISION_DELAY_REQUEST, __opus_check_int(x)
128 #define OPE_GET_DECISION_DELAY(x) OPE_GET_DECISION_DELAY_REQUEST, __opus_check_int_ptr(x)
129 #define OPE_SET_MUXING_DELAY(x) OPE_SET_MUXING_DELAY_REQUEST, __opus_check_int(x)
130 #define OPE_GET_MUXING_DELAY(x) OPE_GET_MUXING_DELAY_REQUEST, __opus_check_int_ptr(x)
131 #define OPE_SET_COMMENT_PADDING(x) OPE_SET_COMMENT_PADDING_REQUEST, __opus_check_int(x)
132 #define OPE_GET_COMMENT_PADDING(x) OPE_GET_COMMENT_PADDING_REQUEST, __opus_check_int_ptr(x)
133 #define OPE_SET_SERIALNO(x) OPE_SET_SERIALNO_REQUEST, __opus_check_int(x)
134 #define OPE_GET_SERIALNO(x) OPE_GET_SERIALNO_REQUEST, __opus_check_int_ptr(x)
135 /* FIXME: Add type-checking macros to these. */
136 #define OPE_SET_PACKET_CALLBACK(x,u) OPE_SET_PACKET_CALLBACK_REQUEST, (x), (u)
137 /*#define OPE_GET_PACKET_CALLBACK(x,u) OPE_GET_PACKET_CALLBACK_REQUEST, (x), (u)*/
138 #define OPE_SET_HEADER_GAIN(x,u) OPE_SET_HEADER_GAIN_REQUEST, __opus_check_int(x)
139 #define OPE_GET_HEADER_GAIN(x,u) OPE_GET_HEADER_GAIN_REQUEST, __opus_check_int_ptr(x)
140 
142 
145 
150 
152 typedef int (*ope_write_func)(void *user_data, const unsigned char *ptr, opus_int32 len);
153 
155 typedef int (*ope_close_func)(void *user_data);
156 
158 typedef int (*ope_packet_func)(void *user_data, const unsigned char *packet_ptr, opus_int32 packet_len, opus_uint32 flags);
159 
161 typedef struct {
169 
171 typedef struct OggOpusComments OggOpusComments;
172 
174 typedef struct OggOpusEnc OggOpusEnc;
175 
178 
183 
186 OPE_EXPORT OggOpusComments *ope_comments_create(void);
187 
191 OPE_EXPORT OggOpusComments *ope_comments_copy(OggOpusComments *comments);
192 
195 OPE_EXPORT void ope_comments_destroy(OggOpusComments *comments);
196 
203 OPE_EXPORT int ope_comments_add(OggOpusComments *comments, const char *tag, const char *val);
204 
210 OPE_EXPORT int ope_comments_add_string(OggOpusComments *comments, const char *tag_and_val);
211 
219 OPE_EXPORT int ope_comments_add_picture(OggOpusComments *comments, const char *filename, int picture_type, const char *description);
220 
223 
226 
231 
241 OPE_EXPORT OggOpusEnc *ope_encoder_create_file(const char *path, OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error);
242 
253 OPE_EXPORT OggOpusEnc *ope_encoder_create_callbacks(const OpusEncCallbacks *callbacks, void *user_data,
254  OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error);
255 
265 OPE_EXPORT OggOpusEnc *ope_encoder_create_pull(OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error);
266 
272 OPE_EXPORT int ope_encoder_write_float(OggOpusEnc *enc, const float *pcm, int samples_per_channel);
273 
279 OPE_EXPORT int ope_encoder_write(OggOpusEnc *enc, const opus_int16 *pcm, int samples_per_channel);
280 
287 OPE_EXPORT int ope_encoder_get_page(OggOpusEnc *enc, unsigned char **page, opus_int32 *len, int flush);
288 
293 OPE_EXPORT int ope_encoder_drain(OggOpusEnc *enc);
294 
298 OPE_EXPORT void ope_encoder_destroy(OggOpusEnc *enc);
299 
305 OPE_EXPORT int ope_encoder_chain_current(OggOpusEnc *enc, OggOpusComments *comments);
306 
313 OPE_EXPORT int ope_encoder_continue_new_file(OggOpusEnc *enc, const char *path, OggOpusComments *comments);
314 
321 OPE_EXPORT int ope_encoder_continue_new_callbacks(OggOpusEnc *enc, void *user_data, OggOpusComments *comments);
322 
327 OPE_EXPORT int ope_encoder_flush_header(OggOpusEnc *enc);
328 
334 OPE_EXPORT int ope_encoder_ctl(OggOpusEnc *enc, int request, ...);
335 
341 OPE_EXPORT const char *ope_strerror(int error);
342 
345 OPE_EXPORT const char *ope_get_version_string(void);
346 
349 OPE_EXPORT int ope_get_abi_version(void);
350 
353 
354 # if defined(__cplusplus)
355 }
356 # endif
357 
358 #endif
OPE_EXPORT const char * ope_strerror(int error)
Converts a libopusenc error code into a human readable string.
OPE_EXPORT int ope_encoder_drain(OggOpusEnc *enc)
Finalizes the stream, but does not deallocate the object.
OPE_EXPORT OggOpusEnc * ope_encoder_create_callbacks(const OpusEncCallbacks *callbacks, void *user_data, OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error)
Create a new OggOpus stream to be handled using callbacks.
int(* ope_write_func)(void *user_data, const unsigned char *ptr, opus_int32 len)
Called for writing a page.
Definition: opusenc.h:152
int(* ope_close_func)(void *user_data)
Called for closing a stream.
Definition: opusenc.h:155
ope_write_func write
Callback for writing to the stream.
Definition: opusenc.h:163
OPE_EXPORT int ope_encoder_continue_new_file(OggOpusEnc *enc, const char *path, OggOpusComments *comments)
Ends the stream and create a new file.
OPE_EXPORT int ope_encoder_write_float(OggOpusEnc *enc, const float *pcm, int samples_per_channel)
Add/encode any number of float samples to the stream.
OPE_EXPORT void ope_comments_destroy(OggOpusComments *comments)
Destroys a comments object.
OPE_EXPORT const char * ope_get_version_string(void)
Returns a string representing the version of libopusenc being used at run time.
OPE_EXPORT int ope_encoder_flush_header(OggOpusEnc *enc)
Write out the header now rather than wait for audio to begin.
OPE_EXPORT int ope_comments_add_string(OggOpusComments *comments, const char *tag_and_val)
Add a comment as a single tag=value string.
OPE_EXPORT int ope_encoder_ctl(OggOpusEnc *enc, int request,...)
Sets encoder options.
OPE_EXPORT int ope_comments_add_picture(OggOpusComments *comments, const char *filename, int picture_type, const char *description)
Add a picture.
Callback functions for accessing the stream.
Definition: opusenc.h:161
OPE_EXPORT OggOpusEnc * ope_encoder_create_pull(OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error)
Create a new OggOpus stream to be used along with.ope_encoder_get_page().
OPE_EXPORT int ope_comments_add(OggOpusComments *comments, const char *tag, const char *val)
Add a comment.
OPE_EXPORT void ope_encoder_destroy(OggOpusEnc *enc)
Deallocates the obect.
OPE_EXPORT int ope_encoder_write(OggOpusEnc *enc, const opus_int16 *pcm, int samples_per_channel)
Add/encode any number of 16-bit linear samples to the stream.
OPE_EXPORT int ope_encoder_chain_current(OggOpusEnc *enc, OggOpusComments *comments)
Ends the stream and create a new stream within the same file.
int(* ope_packet_func)(void *user_data, const unsigned char *packet_ptr, opus_int32 packet_len, opus_uint32 flags)
Called on every packet encoded (including header).
Definition: opusenc.h:158
OPE_EXPORT OggOpusComments * ope_comments_create(void)
Create a new comments object.
OPE_EXPORT int ope_get_abi_version(void)
ABI version for this header.
OPE_EXPORT OggOpusEnc * ope_encoder_create_file(const char *path, OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error)
Create a new OggOpus file.
OPE_EXPORT OggOpusComments * ope_comments_copy(OggOpusComments *comments)
Create a deep copy of a comments object.
OPE_EXPORT int ope_encoder_get_page(OggOpusEnc *enc, unsigned char **page, opus_int32 *len, int flush)
Get the next page from the stream (only if using ope_encoder_create_pull()).
OPE_EXPORT int ope_encoder_continue_new_callbacks(OggOpusEnc *enc, void *user_data, OggOpusComments *comments)
Ends the stream and create a new file (callback-based).
ope_close_func close
Callback for closing the stream.
Definition: opusenc.h:165