Top Description Fields Constructors Methods
org.lwjgl.stb

public Class STBVorbis

extends Object
Class Inheritance
Imports
javax.annotation.*, java.nio.*, org.lwjgl.*, org.lwjgl.system.*, org.lwjgl.system.libc.LibCStdlib
Native bindings to stb_vorbis.c from the stb library.

Ogg Vorbis audio decoder.

Limitations

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.)

Field Summary

Modifier and TypeField and Description
public static final int
VORBIS__no_error

Error code.

public static final int
VORBIS_bad_packet_type

Error code.

public static final int
VORBIS_cant_find_last_page

Error code.

public static final int
VORBIS_continued_packet_flag_invalid

Error code.

public static final int
VORBIS_feature_not_supported

Error code.

public static final int
VORBIS_file_open_failure

Error code.

public static final int
VORBIS_incorrect_stream_serial_number

Error code.

public static final int
VORBIS_invalid_api_mixing

Error code.

public static final int
VORBIS_invalid_first_page

Error code.

public static final int
VORBIS_invalid_setup

Error code.

public static final int
VORBIS_invalid_stream

Error code.

public static final int
VORBIS_invalid_stream_structure_version

Error code.

public static final int
VORBIS_missing_capture_pattern

Error code.

public static final int
VORBIS_need_more_data

Error code.

public static final int
VORBIS_ogg_skeleton_not_supported

Error code.

public static final int
VORBIS_outofmem

Error code.

public static final int
VORBIS_seek_failed

Error code.

public static final int
VORBIS_seek_invalid

Error code.

public static final int
VORBIS_seek_without_length

Error code.

public static final int
VORBIS_too_many_channels

Error code.

public static final int
VORBIS_unexpected_eof

Error code.

Constructor Summary

AccessConstructor and Description
protected
STBVorbis()

Method Summary

Modifier and TypeMethod and Description
public static native void
nstb_vorbis_close(long f)

Unsafe version of: close

public static native int
nstb_vorbis_decode_filename(long filename, long channels, long sample_rate, long output)

Unsafe version of: decode_filename

public static native int
nstb_vorbis_decode_filename(long filename, int[] channels, int[] sample_rate, long output)

Array version of: nstb_vorbis_decode_filename

public static native int
nstb_vorbis_decode_frame_pushdata(long f, long datablock, int
the length of datablock, in bytes
datablock_length_in_bytes, long channels, long output, long samples)

Unsafe version of: decode_frame_pushdata

public static native int
nstb_vorbis_decode_frame_pushdata(long f, long datablock, int datablock_length_in_bytes, int[] channels, long output, int[] samples)

Array version of: nstb_vorbis_decode_frame_pushdata

public static native int
nstb_vorbis_decode_memory(long mem, int
the data length, in bytes
len, long channels, long sample_rate, long output)

Unsafe version of: decode_memory

public static native int
nstb_vorbis_decode_memory(long mem, int len, int[] channels, int[] sample_rate, long output)

Array version of: nstb_vorbis_decode_memory

public static native void
nstb_vorbis_flush_pushdata(long f)

Unsafe version of: flush_pushdata

public static native void
nstb_vorbis_get_comment(long f, long __result)

Unsafe version of: get_comment

public static native int
nstb_vorbis_get_error(long f)

Unsafe version of: get_error

public static native int
nstb_vorbis_get_file_offset(long f)

Unsafe version of: get_file_offset

public static native int
nstb_vorbis_get_frame_float(long f, long channels, long output)

Unsafe version of: get_frame_float

public static native int
nstb_vorbis_get_frame_float(long f, int[] channels, long output)

Array version of: nstb_vorbis_get_frame_float

public static native int
nstb_vorbis_get_frame_short(long f, int
the number of channels
num_c, long buffer, int num_samples)

Unsafe version of: get_frame_short

public static native int
nstb_vorbis_get_frame_short_interleaved(long f, int num_c, long buffer, int
the size of buffer
num_shorts)

Unsafe version of: get_frame_short_interleaved

public static native int
nstb_vorbis_get_frame_short_interleaved(long f, int num_c, short[] buffer, int num_shorts)

Array version of: nstb_vorbis_get_frame_short_interleaved

public static native void
nstb_vorbis_get_info(long f, long __result)

Unsafe version of: get_info

public static native int
nstb_vorbis_get_sample_offset(long f)

Unsafe version of: get_sample_offset

public static native int
nstb_vorbis_get_samples_float(long f, int
the number of channels to decode
channels, long buffer, int num_samples)

Unsafe version of: get_samples_float

public static native int
nstb_vorbis_get_samples_float_interleaved(long f, int channels, long buffer, int
the size of buffer
num_floats)

Unsafe version of: get_samples_float_interleaved

public static native int
nstb_vorbis_get_samples_float_interleaved(long f, int channels, float[] buffer, int num_floats)

Array version of: nstb_vorbis_get_samples_float_interleaved

public static native int
nstb_vorbis_get_samples_short(long f, int
the number of channels
channels, long buffer, int num_samples)

Unsafe version of: get_samples_short

public static native int
nstb_vorbis_get_samples_short_interleaved(long f, int channels, long buffer, int
the size of buffer
num_shorts)

Unsafe version of: get_samples_short_interleaved

public static native int
nstb_vorbis_get_samples_short_interleaved(long f, int channels, short[] buffer, int num_shorts)

Array version of: nstb_vorbis_get_samples_short_interleaved

public static native long
nstb_vorbis_open_filename(long filename, long error, long alloc_buffer)

Unsafe version of: open_filename

public static native long
nstb_vorbis_open_filename(long filename, int[] error, long alloc_buffer)

Array version of: nstb_vorbis_open_filename

public static native long
nstb_vorbis_open_memory(long mem, int
the data length, in bytes
len, long error, long alloc_buffer)

Unsafe version of: open_memory

public static native long
nstb_vorbis_open_memory(long mem, int len, int[] error, long alloc_buffer)

Array version of: nstb_vorbis_open_memory

public static native long
nstb_vorbis_open_pushdata(long datablock, int
the length of datablock, in bytes
datablock_length_in_bytes, long datablock_memory_consumed_in_bytes, long error, long alloc_buffer)

Unsafe version of: open_pushdata

public static native 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

public static native int
nstb_vorbis_seek(long f, int sample_number)

Unsafe version of: seek

public static native int
nstb_vorbis_seek_frame(long f, int sample_number)

Unsafe version of: seek_frame

public static native int
nstb_vorbis_seek_start(long f)

Unsafe version of: seek_start

public static native int
nstb_vorbis_stream_length_in_samples(long f)

Unsafe version of: stream_length_in_samples

public static native float
nstb_vorbis_stream_length_in_seconds(long f)

Unsafe version of: stream_length_in_seconds

public static void
stb_vorbis_close(long
an ogg vorbis file decoder
f)

Closes an ogg vorbis file and free all memory in use

public static int

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(ByteBuffer
the file name
filename, IntBuffer
returns the number of channels
channels, IntBuffer
returns the sample rate
sample_rate, PointerBuffer
returns a pointer to the decoded data
output)

Decode an entire file and output the data interleaved into a malloc()ed buffer stored in *output.

public static int

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(CharSequence
the file name
filename, IntBuffer
returns the number of channels
channels, IntBuffer
returns the sample rate
sample_rate, PointerBuffer
returns a pointer to the decoded data
output)

Decode an entire file and output the data interleaved into a malloc()ed buffer stored in *output.

public static ShortBuffer

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(CharSequence
the file name
filename, IntBuffer
returns the number of channels
channels, IntBuffer
returns the sample rate
sample_rate)

Decode an entire file and output the data interleaved into a malloc()ed buffer stored in *output.

public static int
stb_vorbis_decode_filename(ByteBuffer filename, int[] channels, int[] sample_rate, PointerBuffer output)

Array version of: decode_filename

public static int
stb_vorbis_decode_filename(CharSequence filename, int[] channels, int[] sample_rate, PointerBuffer output)

Array version of: decode_filename

public static int

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.

stb_vorbis_decode_frame_pushdata(long
an ogg vorbis file decoder
f, ByteBuffer
the data block containing the audio sample data
datablock, IntBuffer
place to write number of float * buffers
channels, PointerBuffer
place to write float ** array of float * buffers
output, IntBuffer
place to write number of output samples
samples)

Decodes a frame of audio sample data if possible from the passed-in data block.

public static int
stb_vorbis_decode_frame_pushdata(long f, ByteBuffer datablock, int[] channels, PointerBuffer output, int[] samples)

Array version of: decode_frame_pushdata

public static int
stb_vorbis_decode_memory(ByteBuffer
the data to decode
mem, IntBuffer
returns the number of channels
channels, IntBuffer
returns the sample rate
sample_rate, PointerBuffer
returns a pointer to the decoded data
output)

In-memory version of decode_filename.

public static ShortBuffer
stb_vorbis_decode_memory(ByteBuffer
the data to decode
mem, IntBuffer
returns the number of channels
channels, IntBuffer
returns the sample rate
sample_rate)

In-memory version of decode_filename.

public static int
stb_vorbis_decode_memory(ByteBuffer mem, int[] channels, int[] sample_rate, PointerBuffer output)

Array version of: decode_memory

public static void
stb_vorbis_flush_pushdata(long
an ogg vorbis file decoder
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.

public static STBVorbisComment
stb_vorbis_get_comment(long
an ogg vorbis file decoder
f, STBVorbisComment __result)

Returns ogg comments.

public static int
stb_vorbis_get_error(long
an ogg vorbis file decoder
f)

Returns the last error detected (clears it, too).

public static int
stb_vorbis_get_file_offset(long
an ogg vorbis file decoder
f)

Returns the current seek point within the file, or offset from the beginning of the memory buffer.

public static int

Returns:

the number of samples per channel
stb_vorbis_get_frame_float(long
an ogg vorbis file decoder
f, IntBuffer
returns the number of channels. Can be NULL -- it is always the same as the number of channels reported by get_info.
channels, PointerBuffer
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_*.
output)

Decodes the next frame and return the number of samples.

public static int
stb_vorbis_get_frame_float(long f, int[] channels, PointerBuffer output)

Array version of: get_frame_float

public static int

Returns:

the number of samples per channel
stb_vorbis_get_frame_short(long
an ogg vorbis file decoder
f, PointerBuffer
the output buffer, an array of pointers with length num_c, each pointing to a short array with length num_samples
buffer, int
the number of samples
num_samples)

Decodes the next frame and returns the number of samples per channel.

public static int

Returns:

the number of samples per channel
stb_vorbis_get_frame_short_interleaved(long
an ogg vorbis file decoder
f, int
the number of channels
num_c, ShortBuffer
the output buffer
buffer)

Interleaved version of get_frame_short.

public static int
stb_vorbis_get_frame_short_interleaved(long f, int num_c, short[] buffer)

Array version of: get_frame_short_interleaved

public static STBVorbisInfo
stb_vorbis_get_info(long
an ogg vorbis file decoder
f, STBVorbisInfo __result)

Returns general information about the specified file.

public static int
stb_vorbis_get_sample_offset(long
an ogg vorbis file decoder
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.

public static int

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.
stb_vorbis_get_samples_float(long
an ogg vorbis file decoder
f, PointerBuffer
the output buffer, an array of pointers with length channels, each pointing to a float array with length num_samples
buffer, int
the number of samples to decode
num_samples)

Gets num_samples samples, not necessarily on a frame boundary -- this requires buffering so you have to supply the buffers.

public static int

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.
stb_vorbis_get_samples_float_interleaved(long
an ogg vorbis file decoder
f, int
the number of channels
channels, FloatBuffer
the output buffer
buffer)

Interleaved version of get_samples_float.

public static int
stb_vorbis_get_samples_float_interleaved(long f, int channels, float[] buffer)

Array version of: get_samples_float_interleaved

public static int

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.
stb_vorbis_get_samples_short(long
an ogg vorbis file decoder
f, PointerBuffer
the output buffer, an array of pointers with length channels, each pointing to a short array with length num_samples
buffer, int
the number of samples
num_samples)

Gets num_samples samples, not necessarily on a frame boundary -- this requires buffering so you have to supply the buffers.

public static int

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.
stb_vorbis_get_samples_short_interleaved(long
an ogg vorbis file decoder
f, int
the number of channels
channels, ShortBuffer
the output buffer
buffer)

Interleaved version of get_samples_short.

public static int
stb_vorbis_get_samples_short_interleaved(long f, int channels, short[] buffer)

Array version of: get_samples_short_interleaved

public static long

Returns:

the ogg vorbis decoder. On failure, returns NULL and sets *error.
stb_vorbis_open_filename(ByteBuffer
the file name
filename, IntBuffer
returns an error code
error, STBVorbisAlloc
an STBVorbisAlloc struct
alloc_buffer)

Creates an ogg vorbis decoder from a file name.

public static long

Returns:

the ogg vorbis decoder. On failure, returns NULL and sets *error.
stb_vorbis_open_filename(CharSequence
the file name
filename, IntBuffer
returns an error code
error, STBVorbisAlloc
an STBVorbisAlloc struct
alloc_buffer)

Creates an ogg vorbis decoder from a file name.

public static long
stb_vorbis_open_filename(ByteBuffer filename, int[] error, STBVorbisAlloc alloc_buffer)

Array version of: open_filename

public static long
stb_vorbis_open_filename(CharSequence filename, int[] error, STBVorbisAlloc alloc_buffer)

Array version of: open_filename

public static long

Returns:

the ogg vorbis decoder. On failure, returns NULL and sets *error.
stb_vorbis_open_memory(ByteBuffer
the data to decode
mem, IntBuffer
returns an error code
error, STBVorbisAlloc
an STBVorbisAlloc struct
alloc_buffer)

Creates an ogg vorbis decoder from an ogg vorbis stream in memory (note this must be the entire stream!).

public static long
stb_vorbis_open_memory(ByteBuffer mem, int[] error, STBVorbisAlloc alloc_buffer)

Array version of: open_memory

public static long

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.
stb_vorbis_open_pushdata(ByteBuffer
the data block containing the ogg vorbis headers
datablock, IntBuffer
returns the amount of data parsed/consumed, in bytes
datablock_memory_consumed_in_bytes, IntBuffer
returns the error code
error, STBVorbisAlloc
an STBVorbisAlloc struct
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)

public static long
stb_vorbis_open_pushdata(ByteBuffer datablock, int[] datablock_memory_consumed_in_bytes, int[] error, STBVorbisAlloc alloc_buffer)

Array version of: open_pushdata

public static boolean
stb_vorbis_seek(long
an ogg vorbis file decoder
f, int
the sample index
sample_number)

Seeks in the Vorbis file to (approximately) sample_number.

public static boolean
stb_vorbis_seek_frame(long
an ogg vorbis file decoder
f, int
the sample index
sample_number)

Seeks in the Vorbis file to (approximately) sample_number.

public static boolean
stb_vorbis_seek_start(long
an ogg vorbis file decoder
f)

This function is equivalent to seek(f,0).

public static int
stb_vorbis_stream_length_in_samples(long
an ogg vorbis file decoder
f)

Returns the total length of the vorbis stream, in samples.

public static float
stb_vorbis_stream_length_in_seconds(long
an ogg vorbis file decoder
f)

Returns the total length of the vorbis stream, in samples.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait