Top Description Inners Fields Constructors Methods
org.lwjgl.util.opus

public Class OpusFile

extends Object
Class Inheritance
Imports
javax.annotation.*, java.nio.*, org.lwjgl.system.*

Introduction

This is the documentation for the libopusfile C API.

The libopusfile package provides a convenient high-level API for decoding and basic manipulation of all Ogg Opus audio streams. libopusfile is implemented as a layer on top of Xiph.Org's reference libogg and libopus libraries.

libopusfile provides several sets of built-in routines for file/stream access, and may also use custom stream I/O routines provided by the embedded environment. There are built-in I/O routines provided for ANSI-compliant stdio (FILE *), memory buffers, and URLs (including file: URLs, plus optionally http: and https: URLs).

Organization

The main API is divided into several sections:

Several additional sections are not tied to the main API.

Overview

The libopusfile API always decodes files to 48 kHz. The original sample rate is not preserved by the lossy compression, though it is stored in the header to allow you to resample to it after decoding (the libopusfile API does not currently provide a resampler, but the the Speex resampler is a good choice if you need one). In general, if you are playing back the audio, you should leave it at 48 kHz, provided your audio hardware supports it. When decoding to a file, it may be worth resampling back to the original sample rate, so as not to surprise users who might not expect the sample rate to change after encoding to Opus and decoding.

Opus files can contain anywhere from 1 to 255 channels of audio. The channel mappings for up to 8 channels are the same as the Vorbis mappings. A special stereo API can convert everything to 2 channels, making it simple to support multichannel files in an application which only has stereo output. Although the libopusfile ABI provides support for the theoretical maximum number of channels, the current implementation does not support files with more than 8 channels, as they do not have well-defined channel mappings.

Like all Ogg files, Opus files may be "chained". That is, multiple Opus files may be combined into a single, longer file just by concatenating the original files. This is commonly done in internet radio streaming, as it allows the title and artist to be updated each time the song changes, since each link in the chain includes its own set of metadata.

libopusfile fully supports chained files. It will decode the first Opus stream found in each link of a chained file (ignoring any other streams that might be concurrently multiplexed with it, such as a video stream).

The channel count can also change between links. If your application is not prepared to deal with this, it can use the stereo API to ensure the audio from all links will always get decoded into a common format. Since libopusfile always decodes to 48 kHz, you do not have to worry about the sample rate changing between links (as was possible with Vorbis). This makes application support for chained files with libopusfile very easy.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
OpusFile.Functions

Contains the function pointers loaded from Opus.getLibrary().

Field Summary

Modifier and TypeField and Description
public static final int
OP_ABSOLUTE_GAIN

Gain offset type that indicates that the provided offset should be used as the gain directly, without applying any the header or track gains.

public static final int
OP_ALBUM_GAIN

Gain offset type that indicates that the provided offset is relative to the R128_ALBUM_GAIN value (if any), in addition to the header gain.

public static final int
OP_DEC_FORMAT_FLOAT

Indicates that the decoding callback should produce 32-bit native-endian float samples.

public static final int
OP_DEC_FORMAT_SHORT

Indicates that the decoding callback should produce signed 16-bit native-endian output samples.

public static final int
OP_DEC_USE_DEFAULT

Indicates that the decoding callback did not decode anything, and that libopusfile should decode normally instead.

public static final int
OP_EBADHEADER

Error codes.

public static final int
OP_EBADLINK

Error codes.

public static final int
OP_EBADPACKET

Error codes.

public static final int
OP_EBADTIMESTAMP

Error codes.

public static final int
OP_EFAULT

Error codes.

public static final int
OP_EIMPL

Error codes.

public static final int
OP_EINVAL

Error codes.

public static final int
OP_ENOSEEK

Error codes.

public static final int
OP_ENOTAUDIO

Error codes.

public static final int
OP_ENOTFORMAT

Error codes.

public static final int
OP_EOF

Error codes.

public static final int
OP_EREAD

Error codes.

public static final int
OP_EVERSION

Error codes.

public static final int
OP_FALSE

Error codes.

public static final int
OP_GET_SERVER_INFO_REQUEST

These are the raw numbers used to define the request codes.

public static final int
OP_HEADER_GAIN

Gain offset type that indicates that the provided offset is relative to the header gain.

public static final int
OP_HOLE

Error codes.

public static final int
OP_HTTP_PROXY_HOST_REQUEST

These are the raw numbers used to define the request codes.

public static final int
OP_HTTP_PROXY_PASS_REQUEST

These are the raw numbers used to define the request codes.

public static final int
OP_HTTP_PROXY_PORT_REQUEST

These are the raw numbers used to define the request codes.

public static final int
OP_HTTP_PROXY_USER_REQUEST

These are the raw numbers used to define the request codes.

public static final int
OP_PIC_FORMAT_GIF

Picture tag image formats.

public static final int
OP_PIC_FORMAT_JPEG

Picture tag image formats.

public static final int
OP_PIC_FORMAT_PNG

Picture tag image formats.

public static final int
OP_PIC_FORMAT_UNKNOWN

Picture tag image formats.

public static final int
OP_PIC_FORMAT_URL

Picture tag image formats.

public static final int
OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST

These are the raw numbers used to define the request codes.

public static final int
OP_TRACK_GAIN

Gain offset type that indicates that the provided offset is relative to the R128_TRACK_GAIN value (if any), in addition to the header gain.

public static final int
OPUS_CHANNEL_COUNT_MAX

Constructor Summary

AccessConstructor and Description
protected
OpusFile()

Method Summary

Modifier and TypeMethod and Description
public static long
nop_fdopen(long _cb, int _fd, long _mode)

Unsafe version of: op_fdopen

public static long
nop_fopen(long _cb, long _path, long _mode)

Unsafe version of: op_fopen

public static long
nop_freopen(long _cb, long _path, long _mode, long _stream)

Unsafe version of: op_freopen

public static long
nop_head(long _of, int _li)

Unsafe version of: op_head

public static long
nop_mem_stream_create(long _cb, long _data, long
the size of the block of memory
_size)

Unsafe version of: op_mem_stream_create

public static long
nop_open_callbacks(long _stream, long _cb, long _initial_data, long
the number of bytes in _initial_data.

If the stream is seekable, its current position (as reported by "tell()" at the start of this function) must be equal to _initial_bytes. Otherwise, seeking to absolute positions will generate inconsistent results.

_initial_bytes, long _error)

Unsafe version of: op_open_callbacks

public static long
nop_open_file(long _path, long _error)

Unsafe version of: op_open_file

public static long
nop_open_memory(long _data, long
the number of bytes in the buffer
_size, long _error)

Unsafe version of: op_open_memory

public static int
nop_read(long _of, long _pcm, int
the number of values that can be stored in _pcm.

It is recommended that this be large enough for at least 120 ms of data at 48 kHz per channel (5760 values per channel). Smaller buffers will simply return less data, possibly consuming more memory to buffer the data internally. libopusfile may return less data than requested. If so, there is no guarantee that the remaining data in _pcm will be unmodified.

_buf_size, long _li)

Unsafe version of: op_read

public static int
nop_read_float(long _of, long _pcm, int
the number of floats that can be stored in _pcm.

It is recommended that this be large enough for at least 120 ms of data at 48 kHz per channel (5760 samples per channel). Smaller buffers will simply return less data, possibly consuming more memory to buffer the data internally. If less than _buf_size values are returned, libopusfile makes no guarantee that the remaining data in _pcm will be unmodified.

_buf_size, long _li)

Unsafe version of: op_read_float

public static int
nop_read_float_stereo(long _of, long _pcm, int
the number of values that can be stored in _pcm.

It is recommended that this be large enough for at least 120 ms of data at 48 kHz per channel (11520 values total). Smaller buffers will simply return less data, possibly consuming more memory to buffer the data internally. If less than _buf_size values are returned, libopusfile makes no guarantee that the remaining data in _pcm will be unmodified.

_buf_size)

Unsafe version of: op_read_float_stereo

public static int
nop_read_stereo(long _of, long _pcm, int
the number of values that can be stored in _pcm.

It is recommended that this be large enough for at least 120 ms of data at 48 kHz per channel (11520 values total). Smaller buffers will simply return less data, possibly consuming more memory to buffer the data internally. If less than _buf_size values are returned, libopusfile makes no guarantee that the remaining data in _pcm will be unmodified.

_buf_size)

Unsafe version of: op_read_stereo

public static void
nop_set_decode_callback(long _of, long _decode_cb, long _ctx)

Unsafe version of: op_set_decode_callback

public static long
nop_tags(long _of, int _li)

Unsafe version of: op_tags

public static int
nop_test(long _head, long _initial_data, long
the number of bytes in _initial_data
_initial_bytes)

Unsafe version of: op_test

public static long
nop_test_callbacks(long _stream, long _cb, long _initial_data, long
the number of bytes in _initial_data.

If the stream is seekable, its current position (as reported by "tell()" at the start of this function) must be equal to _initial_bytes. Otherwise, seeking to absolute positions will generate inconsistent results.

_initial_bytes, long _error)

Unsafe version of: op_test_callbacks

public static long
nop_test_file(long _path, long _error)

Unsafe version of: op_test_file

public static long
nop_test_memory(long _data, long
the number of bytes in the buffer
_size, long _error)

Unsafe version of: op_test_memory

public static long
nopus_granule_sample(long _head, long _gp)

Unsafe version of: granule_sample

public static int
nopus_head_parse(long _head, long _data, long
the number of bytes of data in the ID header packet
_len)

Unsafe version of: head_parse

public static void
nopus_picture_tag_clear(long _pic)

Unsafe version of: picture_tag_clear

public static void
nopus_picture_tag_init(long _pic)

Unsafe version of: picture_tag_init

public static int
nopus_picture_tag_parse(long _pic, long _tag)

Unsafe version of: picture_tag_parse

public static int
nopus_tagcompare(long _tag_name, long _comment)

Unsafe version of: tagcompare

public static int
nopus_tagncompare(long _tag_name, int
the number of characters in the tag name. This must be non-negative.
_tag_len, long _comment)

Unsafe version of: tagncompare

public static int
nopus_tags_add(long _tags, long _tag, long _value)

Unsafe version of: tags_add

public static int
nopus_tags_add_comment(long _tags, long _comment)

Unsafe version of: tags_add_comment

public static void
nopus_tags_clear(long _tags)

Unsafe version of: tags_clear

public static int
nopus_tags_copy(long _dst, long _src)

Unsafe version of: tags_copy

public static int
nopus_tags_get_album_gain(long _tags, long _gain_q8)

Unsafe version of: tags_get_album_gain

public static long
nopus_tags_get_binary_suffix(long _tags, long
returns the number of bytes of binary suffix data returned
_len)

Unsafe version of: tags_get_binary_suffix

public static int
nopus_tags_get_track_gain(long _tags, long _gain_q8)

Unsafe version of: tags_get_track_gain

public static void
nopus_tags_init(long _tags)

Unsafe version of: tags_init

public static int
nopus_tags_parse(long _tags, long _data, long
the number of bytes of data in the 'info' header packet
_len)

Unsafe version of: tags_parse

public static long
nopus_tags_query(long _tags, long _tag, int _count)

Unsafe version of: tags_query

public static int
nopus_tags_query_count(long _tags, long _tag)

Unsafe version of: tags_query_count

public static int
nopus_tags_set_binary_suffix(long _tags, long _data, int
the number of bytes of binary data to append. This may be zero to remove any existing binary suffix data.
_len)

Unsafe version of: tags_set_binary_suffix

public static int

Returns:

the bitrate on success, or a negative value on error.

EINVAL The stream was only partially open, the stream was not seekable, or _li was larger than the number of links.

op_bitrate(long
the OggOpusFile from which to retrieve the bitrate
_of, int
the index of the link whose bitrate should be computed. Use a negative number to get the bitrate of the whole stream.
_li)

Computes the bitrate of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream.

public static int

Returns:

the bitrate, in bits per second, or a negative value on error:
  • FALSE No data has been decoded since any of the events described above
  • EINVAL The stream was only partially open
op_bitrate_instant(long
the OggOpusFile from which to retrieve the bitrate
_of)

Compute the instantaneous bitrate, measured as the ratio of bits to playable samples decoded since

  1. the last call to op_bitrate_instant(),
  2. the last seek, or
  3. the start of playback, whichever was most recent.
public static int

Returns:

the channel count of the given link.

If _li is greater than the total number of links, this returns the channel count of the last link. If the stream is not seekable, this always returns the channel count of the current link.

op_channel_count(long
the OggOpusFile from which to retrieve the channel count
_of, int
the index of the link whose channel count should be retrieved. Use a negative number to get the channel count of the current link.
_li)

Get the channel count of the given link in a (possibly-chained) Ogg Opus stream.

public static long

Returns:

a stream handle to use with the callbacks, or NULL on error
op_fdopen(OpusFileCallbacks
the callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_cb, int
the file descriptor to open
_fd, ByteBuffer
the mode to open the file in
_mode)

Opens a stream with fdopen() and fills in a set of callbacks that can be used to access it.

public static long

Returns:

a stream handle to use with the callbacks, or NULL on error
op_fdopen(OpusFileCallbacks
the callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_cb, int
the file descriptor to open
_fd, CharSequence
the mode to open the file in
_mode)

Opens a stream with fdopen() and fills in a set of callbacks that can be used to access it.

public static long

Returns:

a stream handle to use with the callbacks, or NULL on error
op_fopen(OpusFileCallbacks
the callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_cb, ByteBuffer
the path to the file to open. On Windows, this string must be UTF-8 (to allow access to files whose names cannot be represented in the current MBCS code page). All other systems use the native character encoding.
_path, ByteBuffer
the mode to open the file in
_mode)

Opens a stream with fopen() and fills in a set of callbacks that can be used to access it.

public static long

Returns:

a stream handle to use with the callbacks, or NULL on error
op_fopen(OpusFileCallbacks
the callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_cb, CharSequence
the path to the file to open. On Windows, this string must be UTF-8 (to allow access to files whose names cannot be represented in the current MBCS code page). All other systems use the native character encoding.
_path, CharSequence
the mode to open the file in
_mode)

Opens a stream with fopen() and fills in a set of callbacks that can be used to access it.

public static void
op_free(long
the OggOpusFile to free
_of)

Release all memory used by an OggOpusFile.

public static long

Returns:

a stream handle to use with the callbacks, or NULL on error
op_freopen(OpusFileCallbacks
the callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_cb, ByteBuffer
the path to the file to open. On Windows, this string must be UTF-8 (to allow access to files whose names cannot be represented in the current MBCS code page). All other systems use the native character encoding.
_path, ByteBuffer
the mode to open the file in
_mode, long
a stream previously returned by op_fopen, op_fdopen, or op_freopen
_stream)

Opens a stream with freopen() and fills in a set of callbacks that can be used to access it.

public static long

Returns:

a stream handle to use with the callbacks, or NULL on error
op_freopen(OpusFileCallbacks
the callbacks to use for this file. If there is an error opening the file, nothing will be filled in here.
_cb, CharSequence
the path to the file to open. On Windows, this string must be UTF-8 (to allow access to files whose names cannot be represented in the current MBCS code page). All other systems use the native character encoding.
_path, CharSequence
the mode to open the file in
_mode, long
a stream previously returned by op_fopen, op_fdopen, or op_freopen
_stream)

Opens a stream with freopen() and fills in a set of callbacks that can be used to access it.

public static OpusHead

Returns:

the contents of the ID header for the given link
op_head(long
the OggOpusFile from which to retrieve the ID header information
_of, int
the index of the link whose ID header information should be retrieved. Use a negative number to get the ID header information of the current link. For an unseekable stream, _li is ignored, and the ID header information for the current link is always returned, if available.
_li)

Get the ID header information for the given link in a (possibly chained) Ogg Opus stream.

public static long

Returns:

a stream handle to use with the callbacks, or NULL on error
op_mem_stream_create(OpusFileCallbacks
the callbacks to use for this stream. If there is an error creating the stream, nothing will be filled in here.
_cb, ByteBuffer
the block of memory to read from
_data)

Creates a stream that reads from the given block of memory.

public static long

Returns:

a freshly opened OggOpusFile, or NULL on error.

libopusfile does not take ownership of the stream if the call fails. The calling application is responsible for closing the stream if this call returns an error.

op_open_callbacks(long
the stream to read from (e.g., a FILE *). This value will be passed verbatim as the first argument to all of the callbacks.
_stream, OpusFileCallbacks
the callbacks with which to access the stream.

"read()" must be implemented. "seek()" and "tell()" may be NULL, or may always return -1 to indicate a stream is unseekable, but if "seek()" is implemented and succeeds on a particular stream, then "tell()" must also. "close()" may be NULL, but if it is not, it will be called when the OggOpusFile is destroyed by op_free. It will not be called if op_open_callbacks() fails with an error.

_cb, ByteBuffer
an initial buffer of data from the start of the stream.

Applications can read some number of bytes from the start of the stream to help identify this as an Opus stream, and then provide them here to allow the stream to be opened, even if it is unseekable.

_initial_data, IntBuffer
returns 0 on success, or a failure code on error.

You may pass in NULL if you don't want the failure code. The failure code will be one of:

  • EREAD An underlying read, seek, or tell operation failed when it should have succeeded, or we failed to find data in the stream we had seen before
  • EFAULT There was a memory allocation failure, or an internal library error
  • EIMPL The stream used a feature that is not implemented, such as an unsupported channel family
  • EINVAL "seek()" was implemented and succeeded on this source, but "tell()" did not, or the starting position indicator was not equal to _initial_bytes
  • ENOTFORMAT The stream contained a link that did not have any logical Opus streams in it
  • EBADHEADER A required header packet was not properly formatted, contained illegal values, or was missing altogether
  • EVERSION An ID header contained an unrecognized version number
  • EBADLINK We failed to find data we had seen before after seeking
  • EBADTIMESTAMP The first or last timestamp in a link failed basic validity checks
_error)

Open a stream using the given set of callbacks to access it.

public static long

Returns:

a freshly opened OggOpusFile, or NULL on error
op_open_file(ByteBuffer
the path to the file to open
_path, IntBuffer
returns 0 on success, or a failure code on error.

You may pass in NULL if you don't want the failure code. The failure code will be EFAULT if the file could not be opened, or one of the other failure codes from op_open_callbacks otherwise.

_error)

Open a stream from the given file path.

public static long

Returns:

a freshly opened OggOpusFile, or NULL on error
op_open_file(CharSequence
the path to the file to open
_path, IntBuffer
returns 0 on success, or a failure code on error.

You may pass in NULL if you don't want the failure code. The failure code will be EFAULT if the file could not be opened, or one of the other failure codes from op_open_callbacks otherwise.

_error)

Open a stream from the given file path.

public static long

Returns:

a freshly opened OggOpusFile, or NULL on error
op_open_memory(ByteBuffer
the memory buffer to open
_data, IntBuffer
returns 0 on success, or a failure code on error.

You may pass in NULL if you don't want the failure code. See op_open_callbacks for a full list of failure codes.

_error)

Open a stream from a memory buffer.

public static int

Returns:

0 on success, or a negative value on error:
  • EREAD An underlying read or seek operation failed
  • EINVAL The stream was only partially open, or the target was outside the valid range for the stream
  • ENOSEEK This stream is not seekable
  • EBADLINK We failed to find data we had seen before, or the bitstream structure was sufficiently malformed that seeking to the target destination was impossible
op_pcm_seek(long
the OggOpusFile in which to seek
_of, long
the PCM offset to seek to. This is in samples at 48 kHz relative to the start of the stream.
_pcm_offset)

Seek to the specified PCM offset, such that decoding will begin at exactly the requested position.

public static long

Returns:

the PCM offset of the next sample to be read. EINVAL The stream was only partially open.
op_pcm_tell(long
the OggOpusFile from which to retrieve the PCM offset
_of)

Obtain the PCM offset of the next sample to be read.

public static long

Returns:

the PCM length of the entire stream if _li is negative, the PCM length of link _li if it is non-negative, or a negative value on error.

EINVAL The stream is not seekable (so we can't know the length), _li wasn't less than the total number of links in the stream, or the stream was only partially open.

op_pcm_total(long
the OggOpusFile from which to retrieve the PCM offset
_of, int
the index of the link whose PCM length should be computed. Use a negative number to get the PCM length of the entire stream.
_li)

Get the total PCM length (number of samples at 48 kHz) of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream.

public static int

Returns:

0 on success, or a negative error code on failure:
  • EREAD The underlying seek operation failed
  • EINVAL The stream was only partially open, or the target was outside the valid range for the stream
  • ENOSEEK This stream is not seekable
  • EBADLINK Failed to initialize a decoder for a stream for an unknown reason
op_raw_seek(long
the OggOpusFile in which to seek
_of, long
the byte position to seek to. This must be between 0 and op_raw_total(_of, -1) (inclusive).
_byte_offset)

Seek to a byte offset relative to the compressed data.

public static long

Returns:

the byte position that is currently being read from. EINVAL The stream was only partially open.
op_raw_tell(long
the OggOpusFile from which to retrieve the position indicator
_of)

Obtain the current value of the position indicator for _of.

public static long

Returns:

the compressed size of the entire stream if _li is negative, the compressed size of link _li if it is non-negative, or a negative value on error.

The compressed size of the entire stream may be smaller than that of the underlying stream if trailing garbage was detected in the file.

EINVAL The stream is not seekable (so we can't know the length),#_li wasn't less than the total number of links in the stream, or the stream was only partially open.

op_raw_total(long
the OggOpusFile from which to retrieve the compressed size
_of, int
the index of the link whose compressed size should be computed. Use a negative number to get the compressed size of the entire stream.
_li)

Get the total (compressed) size of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing overhead.

public static int

Returns:

the number of samples read per channel on success, or a negative value on failure.

The channel count can be retrieved on success by calling op_head(_of,*_li). The number of samples returned may be 0 if the buffer was too small to store even a single sample for all channels, or if end-of-file was reached. The list of possible failure codes follows. Most of them can only be returned by unseekable, chained streams that encounter a new link.

  • HOLE There was a hole in the data, and some samples may have been skipped. Call this function again to continue decoding past the hole
  • EREAD An underlying read operation failed. This may signal a truncation attack from an https: source
  • EFAULT An internal memory allocation failed
  • EIMPL An unseekable stream encountered a new link that used a feature that is not implemented, such as an unsupported channel family
  • EINVAL The stream was only partially open
  • ENOTFORMAT An unseekable stream encountered a new link that did not have any logical Opus streams in it
  • EBADHEADER An unseekable stream encountered a new link with a required header packet that was not properly formatted, contained illegal values, or was missing altogether
  • EVERSION An unseekable stream encountered a new link with an ID header that contained an unrecognized version number
  • EBADPACKET Failed to properly decode the next packet
  • EBADLINK We failed to find data we had seen before
  • EBADTIMESTAMP An unseekable stream encountered a new link with a starting timestamp that failed basic validity checks
op_read(long
the OggOpusFile from which to read
_of, ShortBuffer
a buffer in which to store the output PCM samples, as signed native-endian 16-bit values at 48 kHz with a nominal range of [-32768,32767). Multiple channels are interleaved using the Vorbis channel ordering. This must have room for at least _buf_size values.
_pcm, IntBuffer
the index of the link this data was decoded from.

You may pass NULL if you do not need this information. If this function fails (returning a negative value), this parameter is left unset.

_li)

Reads more samples from the stream.

public static int

Returns:

the number of samples read per channel on success, or a negative value on failure.

The channel count can be retrieved on success by calling op_head(_of,*_li). The number of samples returned may be 0 if the buffer was too small to store even a single sample for all channels, or if end-of-file was reached. The list of possible failure codes follows. Most of them can only be returned by unseekable, chained streams that encounter a new link.

  • HOLE There was a hole in the data, and some samples may have been skipped. Call this function again to continue decoding past the hole
  • EREAD An underlying read operation failed. This may signal a truncation attack from an https: source
  • EFAULT An internal memory allocation failed
  • EIMPL An unseekable stream encountered a new link that used a feature that is not implemented, such as an unsupported channel family
  • EINVAL The stream was only partially open
  • ENOTFORMAT An unseekable stream encountered a new link that did not have any logical Opus streams in it
  • EBADHEADER An unseekable stream encountered a new link with a required header packet that was not properly formatted, contained illegal values, or was missing altogether
  • EVERSION An unseekable stream encountered a new link with an ID header that contained an unrecognized version number
  • EBADPACKET Failed to properly decode the next packet
  • EBADLINK We failed to find data we had seen before
  • EBADTIMESTAMP An unseekable stream encountered a new link with a starting timestamp that failed basic validity checks
op_read_float(long
the OggOpusFile from which to read
_of, FloatBuffer
a buffer in which to store the output PCM samples as signed floats at 48 kHz with a nominal range of [-1.0,1.0].

Multiple channels are interleaved using the Vorbis channel ordering. This must have room for at least _buf_size floats.

_pcm, IntBuffer
the index of the link this data was decoded from.

You may pass NULL if you do not need this information. If this function fails (returning a negative value), this parameter is left unset.

_li)

Reads more samples from the stream.

public static int

Returns:

the number of samples read per channel on success, or a negative value on failure.

The number of samples returned may be 0 if the buffer was too small to store even a single sample for both channels, or if end-of-file was reached. The list of possible failure codes follows. Most of them can only be returned by unseekable, chained streams that encounter a new link.

  • HOLE There was a hole in the data, and some samples may have been skipped. Call this function again to continue decoding past the hole
  • EREAD An underlying read operation failed. This may signal a truncation attack from an https: source
  • EFAULT An internal memory allocation failed
  • EIMPL An unseekable stream encountered a new link that used a feature that is not implemented, such as an unsupported channel family
  • EINVAL The stream was only partially open
  • ENOTFORMAT An unseekable stream encountered a new link that that did not have any logical Opus streams in it
  • EBADHEADER An unseekable stream encountered a new link with a required header packet that was not properly formatted, contained illegal values, or was missing altogether
  • EVERSION An unseekable stream encountered a new link with an ID header that contained an unrecognized version number
  • EBADPACKET Failed to properly decode the next packet
  • EBADLINK We failed to find data we had seen before
  • EBADTIMESTAMP An unseekable stream encountered a new link with a starting timestamp that failed basic validity checks
op_read_float_stereo(long
the OggOpusFile from which to read
_of, FloatBuffer
a buffer in which to store the output PCM samples, as signed floats at 48 kHz with a nominal range of [-1.0,1.0].

The left and right channels are interleaved in the buffer. This must have room for at least _buf_size values.

_pcm)

Reads more samples from the stream and downmixes to stereo, if necessary.

public static int

Returns:

the number of samples read per channel on success, or a negative value on failure.

The number of samples returned may be 0 if the buffer was too small to store even a single sample for both channels, or if end-of-file was reached. The list of possible failure codes follows. Most of them can only be returned by unseekable, chained streams that encounter a new link.

  • HOLE There was a hole in the data, and some samples may have been skipped. Call this function again to continue decoding past the hole
  • EREAD An underlying read operation failed. This may signal a truncation attack from an https: source
  • EFAULT An internal memory allocation failed
  • EIMPL An unseekable stream encountered a new link that used a feature that is not implemented, such as an unsupported channel family
  • EINVAL The stream was only partially open
  • ENOTFORMAT An unseekable stream encountered a new link that did not have any logical Opus streams in it
  • EBADHEADER An unseekable stream encountered a new link with a required header packet that was not properly formatted, contained illegal values, or was missing altogether
  • EVERSION An unseekable stream encountered a new link with an ID header that contained an unrecognized version number
  • EBADPACKET Failed to properly decode the next packet
  • EBADLINK We failed to find data we had seen before
  • EBADTIMESTAMP An unseekable stream encountered a new link with a starting timestamp that failed basic validity checks
op_read_stereo(long
the OggOpusFile from which to read
_of, ShortBuffer
a buffer in which to store the output PCM samples, as signed native-endian 16-bit values at 48 kHz with a nominal range of [-32768,32767).

The left and right channels are interleaved in the buffer. This must have room for at least _buf_size values.

_pcm)

Reads more samples from the stream and downmixes to stereo, if necessary.

public static boolean

Returns:

a non-zero value if seekable, and 0 if unseekable
op_seekable(long
the OggOpusFile whose seekable status is to be returned
_of)

Returns whether or not the stream being read is seekable.

public static int

Returns:

the serial number of the given link.

If _li is greater than the total number of links, this returns the serial number of the last link. If the stream is not seekable, this always returns the serial number of the current link.

op_serialno(long
the OggOpusFile from which to retrieve the serial number
_of, int
the index of the link whose serial number should be retrieved. Use a negative number to get the serial number of the current link.
_li)

Get the serial number of the given link in a (possibly-chained) Ogg Opus stream.

public static void
op_set_decode_callback(long
the OggOpusFile on which to set the decode callback
_of, OPDecodeCBFuncI
the callback function to call. This may be NULL to disable calling the callback.
_decode_cb, long
the application-provided context pointer to pass to the callback on each call
_ctx)

Sets the packet decode callback function.

public static void
op_set_dither_enabled(long
the OggOpusFile on which to enable or disable dithering
_of, boolean
a non-zero value to enable dithering, or 0 to disable it
_enabled)

Sets whether or not dithering is enabled for 16-bit decoding.

public static int

Returns:

0 on success or a negative value on error. EINVAL The _gain_type was unrecognized.
op_set_gain_offset(long
the OggOpusFile on which to set the gain offset
_of, int
one of:
HEADER_GAIN,ALBUM_GAIN,TRACK_GAINABSOLUTE_GAIN
_gain_type, int
the gain offset to apply, in 1/256ths of a dB
_gain_offset_q8)

Sets the gain to be used for decoded output.

public static OpusTags

Returns:

the contents of the comment header for the given link, or NULL if this is an unseekable stream that encountered an invalid link
op_tags(long
the OggOpusFile from which to retrieve the comment header information
_of, int
the index of the link whose comment header information should be retrieved. Use a negative number to get the comment header information of the current link. For an unseekable stream, _li is ignored, and the comment header information for the current link is always returned, if available.
_li)

Get the comment header information for the given link in a (possibly chained) Ogg Opus stream.

public static int

Returns:

0 if the data appears to be Opus, or a negative value on error.
  • FALSE There was not enough data to tell if this was an Opus stream or not
  • EFAULT An internal memory allocation failed
  • EIMPL The stream used a feature that is not implemented, such as an unsupported channel family
  • ENOTFORMAT If the data did not contain a recognizable ID header for an Opus stream
  • EVERSION If the version field signaled a version this library does not know how to parse
  • EBADHEADER The ID header was not properly formatted or contained illegal values
op_test(OpusHead
the parsed ID header contents. You may pass NULL if you do not need this information. If the function fails, the contents of this structure remain untouched.
_head, ByteBuffer
an initial buffer of data from the start of the stream
_initial_data)

Test to see if this is an Opus stream.

public static long

Returns:

a partially opened OggOpusFile, or NULL on error.

libopusfile does not take ownership of the stream if the call fails. The calling application is responsible for closing the stream if this call returns an error.

op_test_callbacks(long
the stream to read from (e.g., a FILE *). This value will be passed verbatim as the first argument to all of the callbacks.
_stream, OpusFileCallbacks
the callbacks with which to access the stream.

"read()" must be implemented. "seek()" and "tell()" may be NULL, or may always return -1 to indicate a stream is unseekable, but if "seek()" is implemented and succeeds on a particular stream, then "tell()" must also. "close()" may be NULL, but if it is not, it will be called when the OggOpusFile is destroyed by op_free. It will not be called if op_open_callbacks fails with an error.

_cb, ByteBuffer
an initial buffer of data from the start of the stream.

Applications can read some number of bytes from the start of the stream to help identify this as an Opus stream, and then provide them here to allow the stream to be tested more thoroughly, even if it is unseekable.

_initial_data, IntBuffer
returns 0 on success, or a failure code on error.

You may pass in NULL if you don't want the failure code. See op_open_callbacks for a full list of failure codes.

_error)

Partially open a stream using the given set of callbacks to access it.

public static long

Returns:

a partially opened OggOpusFile, or NULL on error
op_test_file(ByteBuffer
the path to the file to open
_path, IntBuffer
returns 0 on success, or a failure code on error.

You may pass in NULL if you don't want the failure code. The failure code will be EFAULT if the file could not be opened, or one of the other failure codes from op_open_callbacks otherwise.

_error)

Partially open a stream from the given file path.

public static long

Returns:

a partially opened OggOpusFile, or NULL on error
op_test_file(CharSequence
the path to the file to open
_path, IntBuffer
returns 0 on success, or a failure code on error.

You may pass in NULL if you don't want the failure code. The failure code will be EFAULT if the file could not be opened, or one of the other failure codes from op_open_callbacks otherwise.

_error)

Partially open a stream from the given file path.

public static long

Returns:

a partially opened OggOpusFile, or NULL on error
op_test_memory(ByteBuffer
the memory buffer to open
_data, IntBuffer
returns 0 on success, or a failure code on error.

You may pass in NULL if you don't want the failure code. See op_open_callbacks for a full list of failure codes.

_error)

Partially open a stream from a memory buffer.

public static int

Returns:

0 on success, or a negative value on error:
  • EREAD An underlying read, seek, or tell operation failed when it should have succeeded
  • EFAULT There was a memory allocation failure, or an internal library error
  • EIMPL The stream used a feature that is not implemented, such as an unsupported channel family
  • EINVAL The stream was not partially opened with op_test_callbacks or one of the associated convenience functions
  • ENOTFORMAT The stream contained a link that did not have any logical Opus streams in it
  • EBADHEADER A required header packet was not properly formatted, contained illegal values, or was missing altogether
  • EVERSION An ID header contained an unrecognized version number
  • EBADLINK We failed to find data we had seen before after seeking
  • EBADTIMESTAMP The first or last timestamp in a link failed basic validity checks
op_test_open(long
the OggOpusFile to finish opening
_of)

Finish opening a stream partially opened with op_test_callbacks or one of the associated convenience functions.

public static long

Returns:

the sample offset associated with the given granule position (counting at a 48 kHz sampling rate), or the special value -1 on error (i.e., the granule position was smaller than the pre-skip amount)
opus_granule_sample(OpusHead
the OpusHead information from the ID header of the stream
_head, long
the granule position to convert
_gp)

Converts a granule position to a sample offset for a given Ogg Opus stream.

public static int

Returns:

0 on success or a negative value on error:
  • ENOTFORMAT If the data does not start with the "OpusHead" string.
  • EVERSION If the version field signaled a version this library does not know how to parse.
  • EIMPL If the channel mapping family was 255, which general purpose players should not attempt to play.
  • EBADHEADER If the contents of the packet otherwise violate the Ogg Opus specification:
    • Insufficient data
    • Too much data for the known minor versions
    • An unrecognized channel mapping family
    • Zero channels or too many channels
    • Zero coded streams
    • Too many coupled streams, or
    • An invalid channel mapping index
opus_head_parse(OpusHead
returns the contents of the parsed packet. The contents of this structure are untouched on error. This may be NULL to merely test the header for validity.
_head, ByteBuffer
the contents of the ID header packet
_data)

Parses the contents of the ID header packet of an Ogg Opus stream.

public static void
opus_picture_tag_clear(OpusPictureTag
the OpusPictureTag structure to clear
_pic)

Clears the OpusPictureTag structure.

public static void
opus_picture_tag_init(OpusPictureTag
the OpusPictureTag structure to initialize
_pic)

Initializes an OpusPictureTag structure.

public static int

Returns:

0 on success, or a negative value on failure:
  • ENOTFORMAT The METADATA_BLOCK_PICTURE contents were not valid
  • EFAULT There was not enough memory to store the picture tag contents
opus_picture_tag_parse(OpusPictureTag
returns the parsed picture data.

No sanitation is done on the type, MIME type, or description fields, so these might return invalid values. The contents of this structure are left unmodified on failure.

_pic, ByteBuffer
the METADATA_BLOCK_PICTURE tag contents. The leading "METADATA_BLOCK_PICTURE=" portion is optional, to allow the function to be used on either directly on the values in OpusTags::user_comments or on the return value of tags_query.
_tag)

Parse a single METADATA_BLOCK_PICTURE tag.

public static int

Returns:

0 on success, or a negative value on failure:
  • ENOTFORMAT The METADATA_BLOCK_PICTURE contents were not valid
  • EFAULT There was not enough memory to store the picture tag contents
opus_picture_tag_parse(OpusPictureTag
returns the parsed picture data.

No sanitation is done on the type, MIME type, or description fields, so these might return invalid values. The contents of this structure are left unmodified on failure.

_pic, CharSequence
the METADATA_BLOCK_PICTURE tag contents. The leading "METADATA_BLOCK_PICTURE=" portion is optional, to allow the function to be used on either directly on the values in OpusTags::user_comments or on the return value of tags_query.
_tag)

Parse a single METADATA_BLOCK_PICTURE tag.

public static int

Returns:

an integer less than, equal to, or greater than zero if _comment is found respectively, to be less than, to match, or be greater than a "tag=value" string whose tag matches _tag_name
opus_tagcompare(ByteBuffer
a NUL-terminated, case-insensitive, ASCII string containing the name of the tag to check for (without the terminating '=' character)
_tag_name, ByteBuffer
the comment string to check
_comment)

Check if _comment is an instance of a _tag_name tag.

public static int

Returns:

an integer less than, equal to, or greater than zero if _comment is found respectively, to be less than, to match, or be greater than a "tag=value" string whose tag matches _tag_name
opus_tagcompare(CharSequence
a NUL-terminated, case-insensitive, ASCII string containing the name of the tag to check for (without the terminating '=' character)
_tag_name, CharSequence
the comment string to check
_comment)

Check if _comment is an instance of a _tag_name tag.

public static int

Returns:

an integer less than, equal to, or greater than zero if _comment is found respectively, to be less than, to match, or be greater than a "tag=value" string whose tag matches the first _tag_len characters of _tag_name
opus_tagncompare(ByteBuffer
a case-insensitive ASCII string containing the name of the tag to check for (without the terminating '=' character)
_tag_name, ByteBuffer
the comment string to check
_comment)

Check if _comment is an instance of a _tag_name tag.

public static int

Returns:

an integer less than, equal to, or greater than zero if _comment is found respectively, to be less than, to match, or be greater than a "tag=value" string whose tag matches the first _tag_len characters of _tag_name
opus_tagncompare(CharSequence
a case-insensitive ASCII string containing the name of the tag to check for (without the terminating '=' character)
_tag_name, CharSequence
the comment string to check
_comment)

Check if _comment is an instance of a _tag_name tag.

public static int

Returns:

0 on success, or a negative value on failure:
  • EFAULT An internal memory allocation failed
opus_tags_add(OpusTags
the OpusTags structure to add the (tag, value) pair to
_tags, ByteBuffer
a NUL-terminated, case-insensitive, ASCII string containing the tag to add (without an '=' character)
_tag, ByteBuffer
a NUL-terminated UTF-8 containing the corresponding value
_value)

Add a (tag, value) pair to an initialized OpusTags structure.

public static int

Returns:

0 on success, or a negative value on failure:
  • EFAULT An internal memory allocation failed
opus_tags_add(OpusTags
the OpusTags structure to add the (tag, value) pair to
_tags, CharSequence
a NUL-terminated, case-insensitive, ASCII string containing the tag to add (without an '=' character)
_tag, CharSequence
a NUL-terminated UTF-8 containing the corresponding value
_value)

Add a (tag, value) pair to an initialized OpusTags structure.

public static int

Returns:

0 on success, or a negative value on failure:
  • EFAULT An internal memory allocation failed
opus_tags_add_comment(OpusTags
the OpusTags structure to add the comment to
_tags, ByteBuffer
a NUL-terminated UTF-8 string containing the comment in "TAG=value" form
_comment)

Add a comment to an initialized OpusTags structure.

public static int

Returns:

0 on success, or a negative value on failure:
  • EFAULT An internal memory allocation failed
opus_tags_add_comment(OpusTags
the OpusTags structure to add the comment to
_tags, CharSequence
a NUL-terminated UTF-8 string containing the comment in "TAG=value" form
_comment)

Add a comment to an initialized OpusTags structure.

public static void
opus_tags_clear(OpusTags
the OpusTags structure to clear
_tags)

Clears the OpusTags structure.

public static int

Returns:

  • 0: Success
  • EFAULT If there wasn't enough memory to copy the tags
opus_tags_copy(OpusTags
the OpusTags structure to copy into. If this function fails, the contents of this structure remain untouched.
_dst, OpusTags
the OpusTags structure to copy from
_src)

Performs a deep copy of an OpusTags structure.

public static int

Returns:

0 on success, or a negative value on failure:
  • FALSE There was no album gain available in the given tags
opus_tags_get_album_gain(OpusTags
an initialized OpusTags structure
_tags, IntBuffer
the album gain, in 1/256ths of a dB. This will lie in the range [-32768,32767], and should be applied in addition to the header gain. On error, no value is returned, and the previous contents remain unchanged.
_gain_q8)

Get the album gain from an R128_ALBUM_GAIN tag, if one was specified.

public static ByteBuffer

Returns:

a pointer to the binary suffix data, or NULL if none was present
opus_tags_get_binary_suffix(OpusTags
an initialized OpusTags structure
_tags)

Retrieve the binary suffix data at the end of the packet (if any).

public static int

Returns:

0 on success, or a negative value on failure:
  • FALSE There was no track gain available in the given tags
opus_tags_get_track_gain(OpusTags
an initialized OpusTags structure
_tags, IntBuffer
the track gain, in 1/256ths of a dB. This will lie in the range [-32768,32767], and should be applied in addition to the header gain. On error, no value is returned, and the previous contents remain unchanged.
_gain_q8)

Get the track gain from an R128_TRACK_GAIN tag, if one was specified.

public static void
opus_tags_init(OpusTags
the OpusTags structure to initialize
_tags)

Initializes an OpusTags structure.

public static int

Returns:

  • 0: Success
  • ENOTFORMAT If the data does not start with the "OpusTags" string
  • EBADHEADER If the contents of the packet otherwise violate the Ogg Opus specification
  • EFAULT If there wasn't enough memory to store the tags
opus_tags_parse(OpusTags
an uninitialized OpusTags structure. This returns the contents of the parsed packet. The contents of this structure are untouched on error. This may be NULL to merely test the header for validity.
_tags, ByteBuffer
the contents of the 'comment' header packet
_data)

Parses the contents of the 'comment' header packet of an Ogg Opus stream.

public static String

Returns:

a pointer to the queried tag's value.

This points directly to data in the OpusTags structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer. NULL if no matching tag is found.

opus_tags_query(OpusTags
an initialized OpusTags structure
_tags, ByteBuffer
the tag to look up
_tag, int
the instance of the tag.

The same tag can appear multiple times, each with a distinct value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use tags_query_count to get the legal range for the _count parameter.

_count)

Look up a comment value by its tag.

public static String

Returns:

a pointer to the queried tag's value.

This points directly to data in the OpusTags structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer. NULL if no matching tag is found.

opus_tags_query(OpusTags
an initialized OpusTags structure
_tags, CharSequence
the tag to look up
_tag, int
the instance of the tag.

The same tag can appear multiple times, each with a distinct value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use tags_query_count to get the legal range for the _count parameter.

_count)

Look up a comment value by its tag.

public static int

Returns:

the number of instances of this particular tag
opus_tags_query_count(OpusTags
an initialized OpusTags structure
_tags, ByteBuffer
the tag to look up
_tag)

Look up the number of instances of a tag.

public static int

Returns:

the number of instances of this particular tag
opus_tags_query_count(OpusTags
an initialized OpusTags structure
_tags, CharSequence
the tag to look up
_tag)

Look up the number of instances of a tag.

public static int

Returns:

0 on success, or a negative value on failure:
  • EINVAL _len was negative, or _len was positive but _data was NULL or the least significant bit of the first byte was not set
  • EFAULT An internal memory allocation failed
opus_tags_set_binary_suffix(OpusTags
an initialized OpusTags structure
_tags, ByteBuffer
a buffer of binary data to append after the encoded user comments. The least significant bit of the first byte of this data must be set (to ensure the data is preserved by other editors).
_data)

Replace the binary suffix data at the end of the packet (if any).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait