Package org.lwjgl.stb

Class STBVorbis

  • public class STBVorbis
extends java.lang.Object
    Native bindings to stb_vorbis.c from the stb library.

    Ogg Vorbis audio decoder.

    Limitations

    • floor 0 not supported (used in old ogg vorbis files pre-2004)
    • lossless sample-truncation at beginning ignored
    • cannot concatenate multiple vorbis streams
    • sample positions are 32-bit, limiting seekable 192Khz files to around 6 hours (Ogg supports 64-bit)

    THREAD SAFETY

    Individual stb_vorbis* handles are not thread-safe; you cannot decode from them from multiple threads at the same time. However, you can have multiple stb_vorbis* handles and decode from them independently in multiple threads.

    PUSHDATA API

    This API allows you to get blocks of data from any source and hand them to stb_vorbis. you have to buffer them; stb_vorbis will tell you how much it used, and you have to give it the rest next time; and stb_vorbis may not have enough data to work with and you will need to give it the same data again PLUS more. Note that the Vorbis specification does not bound the size of an individual frame.

    PULLING INPUT API

    This API assumes stb_vorbis is allowed to pull data from a source -- either a block of memory containing the _entire_ vorbis stream, or a FILE * that you or it create, or possibly some other reading mechanism if you go modify the source to replace the FILE * case with some kind of callback to your code. (But if you don't support seeking, you may just want to go ahead and use pushdata.)

    • Method Detail

      • nstb_vorbis_get_info

        public static void nstb_vorbis_get_info​(long f,
                                        long __result)
        Unsafe version of: get_info

      • stb_vorbis_get_info

        public static STBVorbisInfo stb_vorbis_get_info​(long f,
                                                STBVorbisInfo __result)
        Returns general information about the specified file.
        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_get_error

        public static int nstb_vorbis_get_error​(long f)
        Unsafe version of: get_error

      • stb_vorbis_get_error

        public static int stb_vorbis_get_error​(long f)
        Returns the last error detected (clears it, too).
        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_close

        public static void nstb_vorbis_close​(long f)
        Unsafe version of: close

      • stb_vorbis_close

        public static void stb_vorbis_close​(long f)
        Closes an ogg vorbis file and free all memory in use
        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_get_sample_offset

        public static int nstb_vorbis_get_sample_offset​(long f)
        Unsafe version of: get_sample_offset

      • stb_vorbis_get_sample_offset

        public static int stb_vorbis_get_sample_offset​(long f)
        Returns the offset (in samples) from the beginning of the file that will be returned by the next decode, if it is known, or -1 otherwise. After a flush_pushdata call, this may take a while before it becomes valid again.

        NOT WORKING YET after a seek with PULLDATA API.

        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_get_file_offset

        public static int nstb_vorbis_get_file_offset​(long f)
        Unsafe version of: get_file_offset

      • stb_vorbis_get_file_offset

        public static int stb_vorbis_get_file_offset​(long f)
        Returns the current seek point within the file, or offset from the beginning of the memory buffer. In pushdata mode it returns 0.
        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_open_pushdata

        public static long nstb_vorbis_open_pushdata​(long datablock,
                                             int datablock_length_in_bytes,
                                             long datablock_memory_consumed_in_bytes,
                                             long error,
                                             long alloc_buffer)
        Unsafe version of: open_pushdata
        Parameters:
        datablock_length_in_bytes - the length of datablock, in bytes

      • stb_vorbis_open_pushdata

        public static long stb_vorbis_open_pushdata​(java.nio.ByteBuffer datablock,
                                            java.nio.IntBuffer datablock_memory_consumed_in_bytes,
                                            java.nio.IntBuffer error,
                                            @Nullable
                                            STBVorbisAlloc alloc_buffer)
        Creates a vorbis decoder by passing in the initial data block containing the ogg&vorbis headers (you don't need to do parse them, just provide the first N bytes of the file -- you're told if it's not enough, see below)
        Parameters:
        datablock - the data block containing the ogg vorbis headers
        datablock_memory_consumed_in_bytes - returns the amount of data parsed/consumed, in bytes
        error - returns the error code
        alloc_buffer - an STBVorbisAlloc struct
        Returns:
        On success, returns an stb_vorbis *, does not set error, returns the amount of data parsed/consumed on this call in *datablock_memory_consumed_in_bytes; On failure, returns NULL on error and sets *error, does not change *datablock_memory_consumed. If it returns NULL and *error is need_more_data, then the input block was incomplete and you need to pass in a larger block from the start of the file.

      • nstb_vorbis_decode_frame_pushdata

        public static int nstb_vorbis_decode_frame_pushdata​(long f,
                                                    long datablock,
                                                    int datablock_length_in_bytes,
                                                    long channels,
                                                    long output,
                                                    long samples)
        Unsafe version of: decode_frame_pushdata
        Parameters:
        datablock_length_in_bytes - the length of datablock, in bytes

      • stb_vorbis_decode_frame_pushdata

        public static int stb_vorbis_decode_frame_pushdata​(long f,
                                                   java.nio.ByteBuffer datablock,
                                                   @Nullable
                                                   java.nio.IntBuffer channels,
                                                   PointerBuffer output,
                                                   java.nio.IntBuffer samples)
        Decodes a frame of audio sample data if possible from the passed-in data block.

        Note that on resynch, stb_vorbis will rarely consume all of the buffer, instead only datablock_length_in_bytes-3 or less. This is because it wants to avoid missing parts of a page header if they cross a datablock boundary, without writing state-machiney code to record a partial detection.

        The number of channels returned are stored in *channels (which can be NULL -- it is always the same as the number of channels reported by get_info). *output will contain an array of float* buffers, one per channel. In other words, (*output)[0][0] contains the first sample from the first channel, and (*output)[1][0] contains the first sample from the second channel.

        Parameters:
        f - an ogg vorbis file decoder
        datablock - the data block containing the audio sample data
        channels - place to write number of float * buffers
        output - place to write float ** array of float * buffers
        samples - place to write number of output samples
        Returns:
        the number of bytes we used from datablock. Possible cases:
        • 0 bytes used, 0 samples output (need more data)
        • N bytes used, 0 samples output (resynching the stream, keep going)
        • N bytes used, M samples output (one frame of data)

        Note that after opening a file, you will ALWAYS get one N-bytes,0-sample frame, because Vorbis always "discards" the first frame.

      • nstb_vorbis_flush_pushdata

        public static void nstb_vorbis_flush_pushdata​(long f)
        Unsafe version of: flush_pushdata

      • stb_vorbis_flush_pushdata

        public static void stb_vorbis_flush_pushdata​(long f)
        Inform stb_vorbis that your next datablock will not be contiguous with previous ones (e.g. you've seeked in the data); future attempts to decode frames will cause stb_vorbis to resynchronize (as noted above), and once it sees a valid Ogg page (typically 4-8KB, as large as 64KB), it will begin decoding the next frame.

        If you want to seek using pushdata, you need to seek in your file, then call stb_vorbis_flush_pushdata(), then start calling decoding, then once decoding is returning you data, call get_sample_offset, and if you don't like the result, seek your file again and repeat.

        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_decode_filename

        public static int nstb_vorbis_decode_filename​(long filename,
                                              long channels,
                                              long sample_rate,
                                              long output)
        Unsafe version of: decode_filename

      • stb_vorbis_decode_filename

        public static int stb_vorbis_decode_filename​(java.nio.ByteBuffer filename,
                                             java.nio.IntBuffer channels,
                                             java.nio.IntBuffer sample_rate,
                                             PointerBuffer output)

public static int stb_vorbis_decode_filename​(java.lang.CharSequence filename,
                                             java.nio.IntBuffer channels,
                                             java.nio.IntBuffer sample_rate,
                                             PointerBuffer output)
        Decode an entire file and output the data interleaved into a malloc()ed buffer stored in *output. When you're done with it, just LibCStdlib.free(java.nio.ByteBuffer) the pointer returned in *output.
        Parameters:
        filename - the file name
        channels - returns the number of channels
        sample_rate - returns the sample rate
        output - returns a pointer to the decoded data
        Returns:
        the number of samples decoded, or -1 if the file could not be opened or was not an ogg vorbis file

      • stb_vorbis_decode_filename

        @Nullable
public static java.nio.ShortBuffer stb_vorbis_decode_filename​(java.lang.CharSequence filename,
                                                              java.nio.IntBuffer channels,
                                                              java.nio.IntBuffer sample_rate)
        Decode an entire file and output the data interleaved into a malloc()ed buffer stored in *output. When you're done with it, just LibCStdlib.free(java.nio.ByteBuffer) the pointer returned in *output.
        Parameters:
        filename - the file name
        channels - returns the number of channels
        sample_rate - returns the sample rate
        Returns:
        the number of samples decoded, or -1 if the file could not be opened or was not an ogg vorbis file

      • nstb_vorbis_decode_memory

        public static int nstb_vorbis_decode_memory​(long mem,
                                            int len,
                                            long channels,
                                            long sample_rate,
                                            long output)
        Unsafe version of: decode_memory
        Parameters:
        len - the data length, in bytes

      • stb_vorbis_decode_memory

        public static int stb_vorbis_decode_memory​(java.nio.ByteBuffer mem,
                                           java.nio.IntBuffer channels,
                                           java.nio.IntBuffer sample_rate,
                                           PointerBuffer output)
        In-memory version of decode_filename.
        Parameters:
        mem - the data to decode
        channels - returns the number of channels
        sample_rate - returns the sample rate
        output - returns a pointer to the decoded data

      • stb_vorbis_decode_memory

        @Nullable
public static java.nio.ShortBuffer stb_vorbis_decode_memory​(java.nio.ByteBuffer mem,
                                                            java.nio.IntBuffer channels,
                                                            java.nio.IntBuffer sample_rate)
        In-memory version of decode_filename.
        Parameters:
        mem - the data to decode
        channels - returns the number of channels
        sample_rate - returns the sample rate

      • nstb_vorbis_open_memory

        public static long nstb_vorbis_open_memory​(long mem,
                                           int len,
                                           long error,
                                           long alloc_buffer)
        Unsafe version of: open_memory
        Parameters:
        len - the data length, in bytes

      • stb_vorbis_open_memory

        public static long stb_vorbis_open_memory​(java.nio.ByteBuffer mem,
                                          java.nio.IntBuffer error,
                                          @Nullable
                                          STBVorbisAlloc alloc_buffer)
        Creates an ogg vorbis decoder from an ogg vorbis stream in memory (note this must be the entire stream!).
        Parameters:
        mem - the data to decode
        error - returns an error code
        alloc_buffer - an STBVorbisAlloc struct
        Returns:
        the ogg vorbis decoder. On failure, returns NULL and sets *error.

      • nstb_vorbis_open_filename

        public static long nstb_vorbis_open_filename​(long filename,
                                             long error,
                                             long alloc_buffer)
        Unsafe version of: open_filename

      • stb_vorbis_open_filename

        public static long stb_vorbis_open_filename​(java.nio.ByteBuffer filename,
                                            java.nio.IntBuffer error,
                                            @Nullable
                                            STBVorbisAlloc alloc_buffer)

public static long stb_vorbis_open_filename​(java.lang.CharSequence filename,
                                            java.nio.IntBuffer error,
                                            @Nullable
                                            STBVorbisAlloc alloc_buffer)
        Creates an ogg vorbis decoder from a file name.
        Parameters:
        filename - the file name
        error - returns an error code
        alloc_buffer - an STBVorbisAlloc struct
        Returns:
        the ogg vorbis decoder. On failure, returns NULL and sets *error.

      • nstb_vorbis_seek_frame

        public static int nstb_vorbis_seek_frame​(long f,
                                         int sample_number)
        Unsafe version of: seek_frame

      • stb_vorbis_seek_frame

        public static boolean stb_vorbis_seek_frame​(long f,
                                            int sample_number)
        Seeks in the Vorbis file to (approximately) sample_number. After calling seek_frame(), the next call to get_frame_*() will include the specified sample.
        Parameters:
        f - an ogg vorbis file decoder
        sample_number - the sample index

      • nstb_vorbis_seek

        public static int nstb_vorbis_seek​(long f,
                                   int sample_number)
        Unsafe version of: seek

      • stb_vorbis_seek

        public static boolean stb_vorbis_seek​(long f,
                                      int sample_number)
        Seeks in the Vorbis file to (approximately) sample_number. After calling stb_vorbis_seek(), the next call to stb_vorbis_get_samples_* will start with the specified sample.
        Parameters:
        f - an ogg vorbis file decoder
        sample_number - the sample index

      • nstb_vorbis_seek_start

        public static int nstb_vorbis_seek_start​(long f)
        Unsafe version of: seek_start

      • stb_vorbis_seek_start

        public static boolean stb_vorbis_seek_start​(long f)
        This function is equivalent to seek(f,0).
        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_stream_length_in_samples

        public static int nstb_vorbis_stream_length_in_samples​(long f)
        Unsafe version of: stream_length_in_samples

      • stb_vorbis_stream_length_in_samples

        public static int stb_vorbis_stream_length_in_samples​(long f)
        Returns the total length of the vorbis stream, in samples.
        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_stream_length_in_seconds

        public static float nstb_vorbis_stream_length_in_seconds​(long f)
        Unsafe version of: stream_length_in_seconds

      • stb_vorbis_stream_length_in_seconds

        public static float stb_vorbis_stream_length_in_seconds​(long f)
        Returns the total length of the vorbis stream, in samples.
        Parameters:
        f - an ogg vorbis file decoder

      • nstb_vorbis_get_frame_float

        public static int nstb_vorbis_get_frame_float​(long f,
                                              long channels,
                                              long output)
        Unsafe version of: get_frame_float

      • stb_vorbis_get_frame_float

        public static int stb_vorbis_get_frame_float​(long f,
                                             @Nullable
                                             java.nio.IntBuffer channels,
                                             PointerBuffer output)
        Decodes the next frame and return the number of samples.

        You generally should not intermix calls to stb_vorbis_get_frame_*() and stb_vorbis_get_samples_*(), since the latter calls the former.

        Parameters:
        f - an ogg vorbis file decoder
        channels - returns the number of channels. Can be NULL -- it is always the same as the number of channels reported by get_info.
        output - returns a pointer to an array of float* buffers, one per channel. These outputs will be overwritten on the next call to stb_vorbis_get_frame_*.
        Returns:
        the number of samples per channel

      • nstb_vorbis_get_frame_short

        public static int nstb_vorbis_get_frame_short​(long f,
                                              int num_c,
                                              long buffer,
                                              int num_samples)
        Unsafe version of: get_frame_short
        Parameters:
        num_c - the number of channels

      • stb_vorbis_get_frame_short

        public static int stb_vorbis_get_frame_short​(long f,
                                             PointerBuffer buffer,
                                             int num_samples)
        Decodes the next frame and returns the number of samples per channel. Note that for interleaved data, you pass in the number of shorts (the size of your array), but the return value is the number of samples per channel, not the total number of samples.

        The data is coerced to the number of channels you request according to the channel coercion rules (see below). You must pass in the size of your buffer(s) so that stb_vorbis will not overwrite the end of the buffer. The maximum buffer size needed can be gotten from get_info; however, the Vorbis I specification implies an absolute maximum of 4096 samples per channel.

        Channel coercion rules

        Let M be the number of channels requested, and N the number of channels present, and Cn be the nth channel; let stereo L be the sum of all L and center channels, and stereo R be the sum of all R and center channels (channel assignment from the vorbis spec).

        
 M    N      output
 1    k      sum(Ck) for all k
 2    *      stereo L, stereo R
 k    l      k > l, the first l channels, then 0s
 k    l      k <= l, the first k channels

        Note that this is not good surround etc. mixing at all! It's just so you get something useful.

        Parameters:
        f - an ogg vorbis file decoder
        buffer - the output buffer, an array of pointers with length num_c, each pointing to a short array with length num_samples
        num_samples - the number of samples
        Returns:
        the number of samples per channel

      • nstb_vorbis_get_frame_short_interleaved

        public static int nstb_vorbis_get_frame_short_interleaved​(long f,
                                                          int num_c,
                                                          long buffer,
                                                          int num_shorts)
        Unsafe version of: get_frame_short_interleaved
        Parameters:
        num_shorts - the size of buffer

      • stb_vorbis_get_frame_short_interleaved

        public static int stb_vorbis_get_frame_short_interleaved​(long f,
                                                         int num_c,
                                                         java.nio.ShortBuffer buffer)
        Interleaved version of get_frame_short.

        Note that for interleaved data, you pass in the number of shorts (the size of your array), but the return value is the number of samples per channel, not the total number of samples.

        Parameters:
        f - an ogg vorbis file decoder
        num_c - the number of channels
        buffer - the output buffer
        Returns:
        the number of samples per channel

      • nstb_vorbis_get_samples_float

        public static int nstb_vorbis_get_samples_float​(long f,
                                                int channels,
                                                long buffer,
                                                int num_samples)
        Unsafe version of: get_samples_float
        Parameters:
        channels - the number of channels to decode

      • stb_vorbis_get_samples_float

        public static int stb_vorbis_get_samples_float​(long f,
                                               PointerBuffer buffer,
                                               int num_samples)
        Gets num_samples samples, not necessarily on a frame boundary -- this requires buffering so you have to supply the buffers. DOES NOT APPLY THE COERCION RULES.
        Parameters:
        f - an ogg vorbis file decoder
        buffer - the output buffer, an array of pointers with length channels, each pointing to a float array with length num_samples
        num_samples - the number of samples to decode
        Returns:
        the number of samples stored per channel; it may be less than requested at the end of the file. If there are no more samples in the file, returns 0.

      • nstb_vorbis_get_samples_float_interleaved

        public static int nstb_vorbis_get_samples_float_interleaved​(long f,
                                                            int channels,
                                                            long buffer,
                                                            int num_floats)
        Unsafe version of: get_samples_float_interleaved
        Parameters:
        num_floats - the size of buffer

      • stb_vorbis_get_samples_float_interleaved

        public static int stb_vorbis_get_samples_float_interleaved​(long f,
                                                           int channels,
                                                           java.nio.FloatBuffer buffer)
        Interleaved version of get_samples_float.
        Parameters:
        f - an ogg vorbis file decoder
        channels - the number of channels
        buffer - the output buffer
        Returns:
        the number of samples stored per channel; it may be less than requested at the end of the file. If there are no more samples in the file, returns 0.

      • nstb_vorbis_get_samples_short

        public static int nstb_vorbis_get_samples_short​(long f,
                                                int channels,
                                                long buffer,
                                                int num_samples)
        Unsafe version of: get_samples_short
        Parameters:
        channels - the number of channels

      • stb_vorbis_get_samples_short

        public static int stb_vorbis_get_samples_short​(long f,
                                               PointerBuffer buffer,
                                               int num_samples)
        Gets num_samples samples, not necessarily on a frame boundary -- this requires buffering so you have to supply the buffers. Applies the coercion rules above to produce channels channels.
        Parameters:
        f - an ogg vorbis file decoder
        buffer - the output buffer, an array of pointers with length channels, each pointing to a short array with length num_samples
        num_samples - the number of samples
        Returns:
        the number of samples stored per channel; it may be less than requested at the end of the file. If there are no more samples in the file, returns 0.

      • nstb_vorbis_get_samples_short_interleaved

        public static int nstb_vorbis_get_samples_short_interleaved​(long f,
                                                            int channels,
                                                            long buffer,
                                                            int num_shorts)
        Unsafe version of: get_samples_short_interleaved
        Parameters:
        num_shorts - the size of buffer

      • stb_vorbis_get_samples_short_interleaved

        public static int stb_vorbis_get_samples_short_interleaved​(long f,
                                                           int channels,
                                                           java.nio.ShortBuffer buffer)
        Interleaved version of get_samples_short.
        Parameters:
        f - an ogg vorbis file decoder
        channels - the number of channels
        buffer - the output buffer
        Returns:
        the number of samples stored per channel; it may be less than requested at the end of the file. If there are no more samples in the file, returns 0.

      • nstb_vorbis_open_pushdata

        public static long nstb_vorbis_open_pushdata​(long datablock,
                                             int datablock_length_in_bytes,
                                             int[] datablock_memory_consumed_in_bytes,
                                             int[] error,
                                             long alloc_buffer)
        Array version of: nstb_vorbis_open_pushdata(long, int, long, long, long)

      • stb_vorbis_open_pushdata

        public static long stb_vorbis_open_pushdata​(java.nio.ByteBuffer datablock,
                                            int[] datablock_memory_consumed_in_bytes,
                                            int[] error,
                                            @Nullable
                                            STBVorbisAlloc alloc_buffer)
        Array version of: open_pushdata

      • stb_vorbis_decode_frame_pushdata

        public static int stb_vorbis_decode_frame_pushdata​(long f,
                                                   java.nio.ByteBuffer datablock,
                                                   @Nullable
                                                   int[] channels,
                                                   PointerBuffer output,
                                                   int[] samples)
        Array version of: decode_frame_pushdata

      • stb_vorbis_decode_filename

        public static int stb_vorbis_decode_filename​(java.nio.ByteBuffer filename,
                                             int[] channels,
                                             int[] sample_rate,
                                             PointerBuffer output)

public static int stb_vorbis_decode_filename​(java.lang.CharSequence filename,
                                             int[] channels,
                                             int[] sample_rate,
                                             PointerBuffer output)
        Array version of: decode_filename

      • stb_vorbis_decode_memory

        public static int stb_vorbis_decode_memory​(java.nio.ByteBuffer mem,
                                           int[] channels,
                                           int[] sample_rate,
                                           PointerBuffer output)
        Array version of: decode_memory

      • stb_vorbis_open_memory

        public static long stb_vorbis_open_memory​(java.nio.ByteBuffer mem,
                                          int[] error,
                                          @Nullable
                                          STBVorbisAlloc alloc_buffer)
        Array version of: open_memory

      • stb_vorbis_open_filename

        public static long stb_vorbis_open_filename​(java.nio.ByteBuffer filename,
                                            int[] error,
                                            @Nullable
                                            STBVorbisAlloc alloc_buffer)

public static long stb_vorbis_open_filename​(java.lang.CharSequence filename,
                                            int[] error,
                                            @Nullable
                                            STBVorbisAlloc alloc_buffer)
        Array version of: open_filename

      • stb_vorbis_get_frame_float

        public static int stb_vorbis_get_frame_float​(long f,
                                             @Nullable
                                             int[] channels,
                                             PointerBuffer output)
        Array version of: get_frame_float

      • stb_vorbis_get_frame_short_interleaved

        public static int stb_vorbis_get_frame_short_interleaved​(long f,
                                                         int num_c,
                                                         short[] buffer)
        Array version of: get_frame_short_interleaved

      • stb_vorbis_get_samples_float_interleaved

        public static int stb_vorbis_get_samples_float_interleaved​(long f,
                                                           int channels,
                                                           float[] buffer)
        Array version of: get_samples_float_interleaved

      • stb_vorbis_get_samples_short_interleaved

        public static int stb_vorbis_get_samples_short_interleaved​(long f,
                                                           int channels,
                                                           short[] buffer)
        Array version of: get_samples_short_interleaved