Back to index

libsfml  1.6+dfsg2
stb_vorbis.h
Go to the documentation of this file.
00001 // Ogg Vorbis I audio decoder  -- version 0.99994
00002 //
00003 // Written in April 2007 by Sean Barrett, sponsored by RAD Game Tools.
00004 //
00005 // Placed in the public domain April 2007 by the author: no copyright is
00006 // claimed, and you may use it for any purpose you like.
00007 //
00008 // No warranty for any purpose is expressed or implied by the author (nor
00009 // by RAD Game Tools). Report bugs and send enhancements to the author.
00010 //
00011 // Get the latest version and other information at:
00012 //     http://nothings.org/stb_vorbis/
00013 
00014 
00015 // Todo:
00016 //
00017 //   - seeking (note you can seek yourself using the pushdata API)
00018 //
00019 // Limitations:
00020 //
00021 //   - floor 0 not supported (used in old ogg vorbis files)
00022 //   - lossless sample-truncation at beginning ignored
00023 //   - cannot concatenate multiple vorbis streams
00024 //   - sample positions are 32-bit, limiting seekable 192Khz
00025 //       files to around 6 hours (Ogg supports 64-bit)
00026 // 
00027 // All of these limitations may be removed in future versions.
00028 
00029 
00031 //
00032 //  HEADER BEGINS HERE
00033 //
00034 
00035 #ifndef STB_VORBIS_INCLUDE_STB_VORBIS_H
00036 #define STB_VORBIS_INCLUDE_STB_VORBIS_H
00037 
00038 #if defined(STB_VORBIS_NO_CRT) && !defined(STB_VORBIS_NO_STDIO)
00039 #define STB_VORBIS_NO_STDIO 1
00040 #endif
00041 
00042 #ifndef STB_VORBIS_NO_STDIO
00043 #include <stdio.h>
00044 #endif
00045 
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00051 
00052 // Individual stb_vorbis* handles are not thread-safe; you cannot decode from
00053 // them from multiple threads at the same time. However, you can have multiple
00054 // stb_vorbis* handles and decode from them independently in multiple thrads.
00055 
00056 
00058 
00059 // normally stb_vorbis uses malloc() to allocate memory at startup,
00060 // and alloca() to allocate temporary memory during a frame on the
00061 // stack. (Memory consumption will depend on the amount of setup
00062 // data in the file and how you set the compile flags for speed
00063 // vs. size. In my test files the maximal-size usage is ~150KB.)
00064 //
00065 // You can modify the wrapper functions in the source (setup_malloc,
00066 // setup_temp_malloc, temp_malloc) to change this behavior, or you
00067 // can use a simpler allocation model: you pass in a buffer from
00068 // which stb_vorbis will allocate _all_ its memory (including the
00069 // temp memory). "open" may fail with a VORBIS_outofmem if you
00070 // do not pass in enough data; there is no way to determine how
00071 // much you do need except to succeed (at which point you can
00072 // query get_info to find the exact amount required. yes I know
00073 // this is lame).
00074 //
00075 // If you pass in a non-NULL buffer of the type below, allocation
00076 // will occur from it as described above. Otherwise just pass NULL
00077 // to use malloc()/alloca()
00078 
00079 typedef struct
00080 {
00081    char *alloc_buffer;
00082    int   alloc_buffer_length_in_bytes;
00083 } stb_vorbis_alloc;
00084 
00085 
00087 
00088 typedef struct stb_vorbis stb_vorbis;
00089 
00090 typedef struct
00091 {
00092    unsigned int sample_rate;
00093    int channels;
00094 
00095    unsigned int setup_memory_required;
00096    unsigned int setup_temp_memory_required;
00097    unsigned int temp_memory_required;
00098 
00099    int max_frame_size;
00100 } stb_vorbis_info;
00101 
00102 // get general information about the file
00103 extern stb_vorbis_info stb_vorbis_get_info(stb_vorbis *f);
00104 
00105 // get the last error detected (clears it, too)
00106 extern int stb_vorbis_get_error(stb_vorbis *f);
00107 
00108 // close an ogg vorbis file and free all memory in use
00109 extern void stb_vorbis_close(stb_vorbis *f);
00110 
00111 // this function returns the offset (in samples) from the beginning of the
00112 // file that will be returned by the next decode, if it is known, or -1
00113 // otherwise. after a flush_pushdata() call, this may take a while before
00114 // it becomes valid again.
00115 // NOT WORKING YET after a seek with PULLDATA API
00116 extern int stb_vorbis_get_sample_offset(stb_vorbis *f);
00117 
00118 // returns the current seek point within the file, or offset from the beginning
00119 // of the memory buffer. In pushdata mode it returns 0.
00120 extern unsigned int stb_vorbis_get_file_offset(stb_vorbis *f);
00121 
00123 
00124 #ifndef STB_VORBIS_NO_PUSHDATA_API
00125 
00126 // this API allows you to get blocks of data from any source and hand
00127 // them to stb_vorbis. you have to buffer them; stb_vorbis will tell
00128 // you how much it used, and you have to give it the rest next time;
00129 // and stb_vorbis may not have enough data to work with and you will
00130 // need to give it the same data again PLUS more. Note that the Vorbis
00131 // specification does not bound the size of an individual frame.
00132 
00133 extern stb_vorbis *stb_vorbis_open_pushdata(
00134          unsigned char *datablock, int datablock_length_in_bytes,
00135          int *datablock_memory_consumed_in_bytes,
00136          int *error,
00137          stb_vorbis_alloc *alloc_buffer);
00138 // create a vorbis decoder by passing in the initial data block containing
00139 //    the ogg&vorbis headers (you don't need to do parse them, just provide
00140 //    the first N bytes of the file--you're told if it's not enough, see below)
00141 // on success, returns an stb_vorbis *, does not set error, returns the amount of
00142 //    data parsed/consumed on this call in *datablock_memory_consumed_in_bytes;
00143 // on failure, returns NULL on error and sets *error, does not change *datablock_memory_consumed
00144 // if returns NULL and *error is VORBIS_need_more_data, then the input block was
00145 //       incomplete and you need to pass in a larger block from the start of the file
00146 
00147 extern int stb_vorbis_decode_frame_pushdata(
00148          stb_vorbis *f, unsigned char *datablock, int datablock_length_in_bytes,
00149          int *channels,             // place to write number of float * buffers
00150          float ***output,           // place to write float ** array of float * buffers
00151          int *samples               // place to write number of output samples
00152      );
00153 // decode a frame of audio sample data if possible from the passed-in data block
00154 //
00155 // return value: number of bytes we used from datablock
00156 // possible cases:
00157 //     0 bytes used, 0 samples output (need more data)
00158 //     N bytes used, 0 samples output (resynching the stream, keep going)
00159 //     N bytes used, M samples output (one frame of data)
00160 // note that after opening a file, you will ALWAYS get one N-bytes,0-sample
00161 // frame, because Vorbis always "discards" the first frame.
00162 //
00163 // Note that on resynch, stb_vorbis will rarely consume all of the buffer,
00164 // instead only datablock_length_in_bytes-3 or less. This is because it wants
00165 // to avoid missing parts of a page header if they cross a datablock boundary,
00166 // without writing state-machiney code to record a partial detection.
00167 //
00168 // The number of channels returned are stored in *channels (which can be
00169 // NULL--it is always the same as the number of channels reported by
00170 // get_info). *output will contain an array of float* buffers, one per
00171 // channel. In other words, (*output)[0][0] contains the first sample from
00172 // the first channel, and (*output)[1][0] contains the first sample from
00173 // the second channel.
00174 
00175 extern void stb_vorbis_flush_pushdata(stb_vorbis *f);
00176 // inform stb_vorbis that your next datablock will not be contiguous with
00177 // previous ones (e.g. you've seeked in the data); future attempts to decode
00178 // frames will cause stb_vorbis to resynchronize (as noted above), and
00179 // once it sees a valid Ogg page (typically 4-8KB, as large as 64KB), it
00180 // will begin decoding the _next_ frame.
00181 //
00182 // if you want to seek using pushdata, you need to seek in your file, then
00183 // call stb_vorbis_flush_pushdata(), then start calling decoding, then once
00184 // decoding is returning you data, call stb_vorbis_get_sample_offset, and
00185 // if you don't like the result, seek your file again and repeat.
00186 #endif
00187 
00188 
00190 
00191 #ifndef STB_VORBIS_NO_PULLDATA_API
00192 // This API assumes stb_vorbis is allowed to pull data from a source--
00193 // either a block of memory containing the _entire_ vorbis stream, or a
00194 // FILE * that you or it create, or possibly some other reading mechanism
00195 // if you go modify the source to replace the FILE * case with some kind
00196 // of callback to your code. (But if you don't support seeking, you may
00197 // just want to go ahead and use pushdata.)
00198 
00199 #if !defined(STB_VORBIS_NO_STDIO) && !defined(STB_VORBIS_NO_INTEGER_CONVERSION)
00200 extern int stb_vorbis_decode_filename(char *filename, int *channels, short **output);
00201 #endif
00202 extern int stb_vorbis_decode_memory(unsigned char *mem, int len, int *channels, short **output);
00203 // decode an entire file and output the data interleaved into a malloc()ed
00204 // buffer stored in *output. The return value is the number of samples
00205 // decoded, or -1 if the file could not be opened or was not an ogg vorbis file.
00206 // When you're done with it, just free() the pointer returned in *output.
00207 
00208 extern stb_vorbis * stb_vorbis_open_memory(unsigned char *data, int len,
00209                                   int *error, stb_vorbis_alloc *alloc_buffer);
00210 // create an ogg vorbis decoder from an ogg vorbis stream in memory (note
00211 // this must be the entire stream!). on failure, returns NULL and sets *error
00212 
00213 #ifndef STB_VORBIS_NO_STDIO
00214 extern stb_vorbis * stb_vorbis_open_filename(char *filename,
00215                                   int *error, stb_vorbis_alloc *alloc_buffer);
00216 // create an ogg vorbis decoder from a filename via fopen(). on failure,
00217 // returns NULL and sets *error (possibly to VORBIS_file_open_failure).
00218 
00219 extern stb_vorbis * stb_vorbis_open_file(FILE *f, int close_handle_on_close,
00220                                   int *error, stb_vorbis_alloc *alloc_buffer);
00221 // create an ogg vorbis decoder from an open FILE *, looking for a stream at
00222 // the _current_ seek point (ftell). on failure, returns NULL and sets *error.
00223 // note that stb_vorbis must "own" this stream; if you seek it in between
00224 // calls to stb_vorbis, it will become confused. Morever, if you attempt to
00225 // perform stb_vorbis_seek_*() operations on this file, it will assume it
00226 // owns the _entire_ rest of the file after the start point. Use the next
00227 // function, stb_vorbis_open_file_section(), to limit it.
00228 
00229 extern stb_vorbis * stb_vorbis_open_file_section(FILE *f, int close_handle_on_close,
00230                 int *error, stb_vorbis_alloc *alloc_buffer, unsigned int len);
00231 // create an ogg vorbis decoder from an open FILE *, looking for a stream at
00232 // the _current_ seek point (ftell); the stream will be of length 'len' bytes.
00233 // on failure, returns NULL and sets *error. note that stb_vorbis must "own"
00234 // this stream; if you seek it in between calls to stb_vorbis, it will become
00235 // confused.
00236 #endif
00237 
00238 extern int stb_vorbis_seek_frame(stb_vorbis *f, unsigned int sample_number);
00239 extern int stb_vorbis_seek(stb_vorbis *f, unsigned int sample_number);
00240 // NOT WORKING YET
00241 // these functions seek in the Vorbis file to (approximately) 'sample_number'.
00242 // after calling seek_frame(), the next call to get_frame_*() will include
00243 // the specified sample. after calling stb_vorbis_seek(), the next call to
00244 // stb_vorbis_get_samples_* will start with the specified sample. If you
00245 // do not need to seek to EXACTLY the target sample when using get_samples_*,
00246 // you can also use seek_frame().
00247 
00248 extern void stb_vorbis_seek_start(stb_vorbis *f);
00249 // this function is equivalent to stb_vorbis_seek(f,0), but it
00250 // actually works
00251 
00252 extern unsigned int stb_vorbis_stream_length_in_samples(stb_vorbis *f);
00253 extern float        stb_vorbis_stream_length_in_seconds(stb_vorbis *f);
00254 // these functions return the total length of the vorbis stream
00255 
00256 extern int stb_vorbis_get_frame_float(stb_vorbis *f, int *channels, float ***output);
00257 // decode the next frame and return the number of samples. the number of
00258 // channels returned are stored in *channels (which can be NULL--it is always
00259 // the same as the number of channels reported by get_info). *output will
00260 // contain an array of float* buffers, one per channel. These outputs will
00261 // be overwritten on the next call to stb_vorbis_get_frame_*.
00262 //
00263 // You generally should not intermix calls to stb_vorbis_get_frame_*()
00264 // and stb_vorbis_get_samples_*(), since the latter calls the former.
00265 
00266 #ifndef STB_VORBIS_NO_INTEGER_CONVERSION
00267 extern int stb_vorbis_get_frame_short_interleaved(stb_vorbis *f, int num_c, short *buffer, int num_shorts);
00268 extern int stb_vorbis_get_frame_short            (stb_vorbis *f, int num_c, short **buffer, int num_samples);
00269 #endif
00270 // decode the next frame and return the number of samples per channel. the
00271 // data is coerced to the number of channels you request according to the
00272 // channel coercion rules (see below). You must pass in the size of your
00273 // buffer(s) so that stb_vorbis will not overwrite the end of the buffer.
00274 // The maximum buffer size needed can be gotten from get_info(); however,
00275 // the Vorbis I specification implies an absolute maximum of 4096 samples
00276 // per channel. Note that for interleaved data, you pass in the number of
00277 // shorts (the size of your array), but the return value is the number of
00278 // samples per channel, not the total number of samples.
00279 
00280 // Channel coercion rules:
00281 //    Let M be the number of channels requested, and N the number of channels present,
00282 //    and Cn be the nth channel; let stereo L be the sum of all L and center channels,
00283 //    and stereo R be the sum of all R and center channels (channel assignment from the
00284 //    vorbis spec).
00285 //        M    N       output
00286 //        1    k      sum(Ck) for all k
00287 //        2    *      stereo L, stereo R
00288 //        k    l      k > l, the first l channels, then 0s
00289 //        k    l      k <= l, the first k channels
00290 //    Note that this is not _good_ surround etc. mixing at all! It's just so
00291 //    you get something useful.
00292 
00293 extern int stb_vorbis_get_samples_float_interleaved(stb_vorbis *f, int channels, float *buffer, int num_floats);
00294 extern int stb_vorbis_get_samples_float(stb_vorbis *f, int channels, float **buffer, int num_samples);
00295 // gets num_samples samples, not necessarily on a frame boundary--this requires
00296 // buffering so you have to supply the buffers. DOES NOT APPLY THE COERCION RULES.
00297 // Returns the number of samples stored per channel; it may be less than requested
00298 // at the end of the file. If there are no more samples in the file, returns 0.
00299 
00300 #ifndef STB_VORBIS_NO_INTEGER_CONVERSION
00301 extern int stb_vorbis_get_samples_short_interleaved(stb_vorbis *f, int channels, short *buffer, int num_shorts);
00302 extern int stb_vorbis_get_samples_short(stb_vorbis *f, int channels, short **buffer, int num_samples);
00303 #endif
00304 // gets num_samples samples, not necessarily on a frame boundary--this requires
00305 // buffering so you have to supply the buffers. Applies the coercion rules above
00306 // to produce 'channels' channels. Returns the number of samples stored per channel;
00307 // it may be less than requested at the end of the file. If there are no more
00308 // samples in the file, returns 0.
00309 
00310 #endif
00311 
00313 
00314 enum STBVorbisError
00315 {
00316    VORBIS__no_error,
00317 
00318    VORBIS_need_more_data=1,             // not a real error
00319 
00320    VORBIS_invalid_api_mixing,           // can't mix API modes
00321    VORBIS_outofmem,                     // not enough memory
00322    VORBIS_feature_not_supported,        // uses floor 0
00323    VORBIS_too_many_channels,            // STB_VORBIS_MAX_CHANNELS is too small
00324    VORBIS_file_open_failure,            // fopen() failed
00325    VORBIS_seek_without_length,          // can't seek in unknown-length file
00326 
00327    VORBIS_unexpected_eof=10,            // file is truncated?
00328    VORBIS_seek_invalid,                 // seek past EOF
00329 
00330    // decoding errors (corrupt/invalid stream) -- you probably
00331    // don't care about the exact details of these
00332 
00333    // vorbis errors:
00334    VORBIS_invalid_setup=20,
00335    VORBIS_invalid_stream,
00336 
00337    // ogg errors:
00338    VORBIS_missing_capture_pattern=30,
00339    VORBIS_invalid_stream_structure_version,
00340    VORBIS_continued_packet_flag_invalid,
00341    VORBIS_incorrect_stream_serial_number,
00342    VORBIS_invalid_first_page,
00343    VORBIS_bad_packet_type,
00344    VORBIS_cant_find_last_page,
00345    VORBIS_seek_failed
00346 };
00347 
00348 
00349 #ifdef __cplusplus
00350 }
00351 #endif
00352 
00353 #endif // STB_VORBIS_INCLUDE_STB_VORBIS_H
00354 //
00355 //  HEADER ENDS HERE
00356 //