Add explicit user data for packet callback, add OPUS_GET_LOOKAHEAD, fix error code
[libopusenc.git] / include / 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
30
31 # if defined(__cplusplus)
32 extern "C" {
33 # endif
34
35 #include "opus.h"
36
37 #ifndef OPE_EXPORT
38 # if defined(WIN32)
39 #  if defined(OPE_BUILD) && defined(DLL_EXPORT)
40 #   define OPE_EXPORT __declspec(dllexport)
41 #  else
42 #   define OPE_EXPORT
43 #  endif
44 # elif defined(__GNUC__) && defined(OPE_BUILD)
45 #  define OPE_EXPORT __attribute__ ((visibility ("default")))
46 # else
47 #  define OPE_EXPORT
48 # endif
49 #endif
50
51 #define OPE_OK 0
52 /* Based on the relevant libopus code minus 10. */
53 #define OPE_BAD_ARG -11
54 #define OPE_INTERNAL_ERROR -13
55 #define OPE_UNIMPLEMENTED -15
56 #define OPE_ALLOC_FAIL -17
57
58 /* Specific to libopusenc. */
59 #define OPE_CANNOT_OPEN -30
60 #define OPE_TOO_LATE -31
61 #define OPE_UNRECOVERABLE -32
62
63
64 /* These are the "raw" request values -- they should usually not be used. */
65 #define OPE_SET_DECISION_DELAY_REQUEST      14000
66 #define OPE_GET_DECISION_DELAY_REQUEST      14001
67 #define OPE_SET_MUXING_DELAY_REQUEST        14002
68 #define OPE_GET_MUXING_DELAY_REQUEST        14003
69 #define OPE_SET_COMMENT_PADDING_REQUEST     14004
70 #define OPE_GET_COMMENT_PADDING_REQUEST     14005
71 #define OPE_SET_SERIALNO_REQUEST            14006
72 #define OPE_GET_SERIALNO_REQUEST            14007
73 #define OPE_SET_PACKET_CALLBACK_REQUEST     14008
74 #define OPE_GET_PACKET_CALLBACK_REQUEST     14009
75
76 #define OPE_SET_DECISION_DELAY(x) OPE_SET_DECISION_DELAY_REQUEST, __opus_check_int(x)
77 #define OPE_GET_DECISION_DELAY(x) OPE_GET_DECISION_DELAY_REQUEST, __opus_check_int_ptr(x)
78 #define OPE_SET_MUXING_DELAY(x) OPE_SET_MUXING_DELAY_REQUEST, __opus_check_int(x)
79 #define OPE_GET_MUXING_DELAY(x) OPE_GET_MUXING_DELAY_REQUEST, __opus_check_int_ptr(x)
80 #define OPE_SET_COMMENT_PADDING(x) OPE_SET_COMMENT_PADDING_REQUEST, __opus_check_int(x)
81 #define OPE_GET_COMMENT_PADDING(x) OPE_GET_COMMENT_PADDING_REQUEST, __opus_check_int_ptr(x)
82 #define OPE_SET_SERIALNO(x) OPE_SET_SERIALNO_REQUEST, __opus_check_int(x)
83 #define OPE_GET_SERIALNO(x) OPE_GET_SERIALNO_REQUEST, __opus_check_int_ptr(x)
84 /* FIXME: Add type-checking macros to these. */
85 #define OPE_SET_PACKET_CALLBACK(x,u) OPE_SET_PACKET_CALLBACK_REQUEST, (x), (u)
86 #define OPE_GET_PACKET_CALLBACK(x,u) OPE_GET_PACKET_CALLBACK_REQUEST, (x), (u)
87
88 typedef int (*ope_write_func)(void *user_data, const unsigned char *ptr, int len);
89
90 typedef int (*ope_close_func)(void *user_data);
91
92 typedef int (*ope_packet_func)(void *user_data, const unsigned char *packet_ptr, int packet_len, opus_uint32 flags);
93
94 /** Callback functions for accessing the stream. */
95 typedef struct {
96   /** Callback for writing to the stream. */
97   ope_write_func write;
98   /** Callback for closing the stream. */
99   ope_close_func close;
100 } OpusEncCallbacks;
101
102 /** Opaque comments struct. */
103 typedef struct OggOpusComments OggOpusComments;
104
105 /** Opaque encoder struct. */
106 typedef struct OggOpusEnc OggOpusEnc;
107
108 /** Create a new comments object. */
109 OPE_EXPORT OggOpusComments *ope_comments_create(void);
110
111 /** Create a deep copy of a comments object. */
112 OPE_EXPORT OggOpusComments *ope_comments_copy(OggOpusComments *comments);
113
114 /** Destroys a comments object. */
115 OPE_EXPORT void ope_comments_destroy(OggOpusComments *comments);
116
117 /** Add a comment. */
118 OPE_EXPORT int ope_comments_add(OggOpusComments *comments, const char *tag, const char *val);
119
120 /** Add a comment. */
121 OPE_EXPORT int ope_comments_add_string(OggOpusComments *comments, const char *tag_and_val);
122
123 /** Add a picture. */
124 OPE_EXPORT int ope_comments_add_picture(OggOpusComments *comments, const char *spec);
125
126
127 /** Create a new OggOpus file. */
128 OPE_EXPORT OggOpusEnc *ope_encoder_create_file(const char *path, const OggOpusComments *comments, int rate, int channels, int family, int *error);
129
130 /** Create a new OggOpus file (callback-based). */
131 OPE_EXPORT OggOpusEnc *ope_encoder_create_callbacks(const OpusEncCallbacks *callbacks, void *user_data,
132     const OggOpusComments *comments, int rate, int channels, int family, int *error);
133
134 /** Create a new OggOpus stream, pulling one page at a time. */
135 OPE_EXPORT OggOpusEnc *ope_encoder_create_pull(const OggOpusComments *comments, int rate, int channels, int family, int *error);
136
137 /** Add/encode any number of float samples to the file. */
138 OPE_EXPORT int ope_encoder_write_float(OggOpusEnc *enc, const float *pcm, int samples_per_channel);
139
140 /** Add/encode any number of int16 samples to the file. */
141 OPE_EXPORT int ope_encoder_write(OggOpusEnc *enc, const opus_int16 *pcm, int samples_per_channel);
142
143 /** Get the next page from the stream. Returns 1 if there is a page available, 0 if not. */
144 OPE_EXPORT int ope_encoder_get_page(OggOpusEnc *enc, unsigned char **page, int *len, int flush);
145
146 /** Finalizes the stream, but does not deallocate the object. */
147 OPE_EXPORT int ope_encoder_drain(OggOpusEnc *enc);
148
149 /** Deallocates the obect. Make sure to ope_drain() first. */
150 OPE_EXPORT void ope_encoder_destroy(OggOpusEnc *enc);
151
152 /** Ends the stream and create a new stream within the same file. */
153 OPE_EXPORT int ope_encoder_chain_current(OggOpusEnc *enc, const OggOpusComments *comments);
154
155 /** Ends the stream and create a new file. */
156 OPE_EXPORT int ope_encoder_continue_new_file(OggOpusEnc *enc, const char *path, const OggOpusComments *comments);
157
158 /** Ends the stream and create a new file (callback-based). */
159 OPE_EXPORT int ope_encoder_continue_new_callbacks(OggOpusEnc *enc, void *user_data, const OggOpusComments *comments);
160
161 /** Write out the header now rather than wait for audio to begin. */
162 OPE_EXPORT int ope_encoder_flush_header(OggOpusEnc *enc);
163
164 /** Goes straight to the libopus ctl() functions. */
165 OPE_EXPORT int ope_encoder_ctl(OggOpusEnc *enc, int request, ...);
166
167 # if defined(__cplusplus)
168 }
169 # endif
170
171 #endif