/ 
Audio-Opusfile-1.000
River stage zero No dependents
/ Audio::Opusfile

NAME

Audio::Opusfile - partial interface to the libopusfile Ogg Opus library

SYNOPSIS

use Audio::Opusfile;
my $of = Audio::Opusfile->new_from_file('silence.opus');
my $tags = $of->tags;
say $tags->query('TITLE'); # Cellule

DESCRIPTION

Opus is a totally open, royalty-free, highly versatile audio codec. Opus is unmatched for interactive speech and music transmission over the Internet, but is also intended for storage and streaming applications. It is standardized by the Internet Engineering Task Force (IETF) as RFC 6716 which incorporated technology from Skype's SILK codec and Xiph.Org's CELT codec.

libopusfile is a library for decoding and basic manipulation of Ogg Opus files.

Audio::Opusfile is an interface to libopusfile. It exports nearly all of the functions for obtaining metadata of an Opus file or buffer in that library. Future versions will additionally provide functions for decoding Opus data into PCM.

The API might change in future versions.

METHODS

Audio::Opusfile->new_from_file($file)

Creates a new Audio::Opusfile object from an Ogg Opus file.

Dies if the given file does not exist or is not a valid Ogg Opus file.

Audio::Opusfile->new_from_memory($buffer)

Creates a new Audio::Opusfile object from a buffer containing Ogg Opus data.

Dies if the given buffer does not contain valid data.

Audio::Opusfile::test($buffer)

Returns true if the given buffer looks like the beginning of a valid Ogg Opus file, false otherwise.

Dies if the given buffer does not have sufficient data to tell if it is an Opus stream or if it looks like a Opus stream but parsing it failed.

$of->head

Returns an Audio::Opusfile::Head object corresponding to the file.

$of->tags

Returns an Audio::Opusfile::Tags object corresponding to the file.

$of->seekable

Returns whether or not the data source being read is seekable.

Returns the number of links in this chained stream. Always returns 1 for unseekable sources.

Get the serial number of the given link in a (possibly-chained) Ogg Opus stream. If the given index is greater than the total number of links, this returns the serial number of the last link.

If the source is not seekable, $link_index is negative, or $link_index is not given, then this function returns the serial number of the current link.

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

The stream must be seekable to get the total. A negative value is returned if the stream is not seekable.

Warning: If the Opus stream (or link) is concurrently multiplexed with other logical streams (e.g., video), this returns the size of the entire stream (or link), not just the number of bytes in the first logical Opus stream. Returning the latter would require scanning the entire file.

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

Users looking for op_time_total() should use this function instead. Because timestamps in Opus are fixed at 48 kHz, there is no need for a separate function to convert this to seconds.

The stream must be seekable to get the total. A negative value is returned if the stream is not seekable.

Retrieve the index of the current link.

This is the link that produced the data most recently read by op_read_float() or its associated functions, or, after a seek, the link that the seek target landed in. Reading more data may advance the link index (even on the first read after a seek).

Computes the bitrate of the stream (with no arguments), or of an individual link in a (possibly-chained) Ogg Opus stream (with one nonnegative argument).

The stream must be seekable to compute the bitrate. A negative value is returned if the stream is not seekable.

Warning: If the Opus stream (or link) is concurrently multiplexed with other logical streams (e.g., video), this uses the size of the entire stream (or link) to compute the bitrate, not just the number of bytes in the first logical Opus stream.

$of->bitrate_instant

Compute the instantaneous bitrate, measured as the ratio of bits to playable samples decoded since a) the last call to bitrate_instant, b) the last seek, or c) the start of playback, whichever was most recent.

This will spike somewhat after a seek or at the start/end of a chain boundary, as pre-skip, pre-roll, and end-trimming causes samples to be decoded but not played.

$of->raw_tell

Obtain the current value of the position indicator of $of. This is the byte position that is currently being read from.

$of->pcm_tell

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

If the stream is not properly timestamped, this might not increment by the proper amount between reads, or even return monotonically increasing values.

$of->raw_seek($offset)

Seek to a byte offset relative to the compressed data.

This also scans packets to update the PCM cursor. It will cross a logical bitstream boundary, but only if it can't get any packets out of the tail of the link to which it seeks.

$of->pcm_seek($offset)

Seek to the specified PCM offset, such that decoding will begin at exactly the requested position. The PCM offset is in samples at 48 kHz relative to the start of the stream.

$of->set_gain_offset($gain_type, $gain_offset)

Sets the gain to be used for decoded output.

By default, the gain in the header is applied with no additional offset. The total gain (including header gain and/or track gain, if applicable, and this offset), will be clamped to [-32768,32767]/256 dB. This is more than enough to saturate or underflow 16-bit PCM.

Note: The new gain will not be applied to any already buffered, decoded output. This means you cannot change it sample-by-sample, as at best it will be updated packet-by-packet. It is meant for setting a target volume level, rather than applying smooth fades, etc.

$gain_type is one of OP_HEADER_GAIN, OP_TRACK_GAIN, or OP_ABSOLUTE_GAIN. $gain_offset is in 1/256ths of a dB.

$of->set_dither_enabled($enabled)

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

By default, when libopusfile is compiled to use floating-point internally, calling read() or read_stereo() will first decode to float, and then convert to fixed-point using noise-shaping dithering. This flag can be used to disable that dithering. When the application uses read_float() or read_float_stereo(), or when the library has been compiled to decode directly to fixed point, this flag has no effect.

$of->read([$bufsize])

It is recommended to use read_float instead of this method if the rest of your audio processing chain can handle floating point.

Reads more samples from the stream. $bufsize is the maximum number of samples read, and it defaults to 1048576. Returns a list whose first element is the link index this data was decoded from, and the rest of the elements are PCM samples, as signed 16-bit values at 48 kHz with a nominal range of [-32768,32767). Multiple channels are interleaved using the Vorbis channel ordering.

You can use $of->head($li)->channel_count to find out the channel count of a given link index.

$of->read_float([$bufsize])

Like read, but samples are signed floats with a nominal range of [-1.0, 1.0].

$of->read_stereo([$bufsize])

Like read, but downmixes the stream to stereo (therefore you will always get two channels) and does NOT return the link index (the first return value is the first sample).

$of->read_float_stereo([$bufsize])

Like read_float, but downmixes the stream to stereo (therefore you will always get two channels) and does NOT return the link index (the first return value is the first sample).

EXPORT

All constants are exported by default:

OPUS_CHANNEL_COUNT_MAX
OP_ABSOLUTE_GAIN
OP_DEC_FORMAT_FLOAT
OP_DEC_FORMAT_SHORT
OP_DEC_USE_DEFAULT
OP_EBADHEADER
OP_EBADLINK
OP_EBADPACKET
OP_EBADTIMESTAMP
OP_EFAULT
OP_EIMPL
OP_EINVAL
OP_ENOSEEK
OP_ENOTAUDIO
OP_ENOTFORMAT
OP_EOF
OP_EREAD
OP_EVERSION
OP_FALSE
OP_GET_SERVER_INFO_REQUEST
OP_HEADER_GAIN
OP_HOLE
OP_HTTP_PROXY_HOST_REQUEST
OP_HTTP_PROXY_PASS_REQUEST
OP_HTTP_PROXY_PORT_REQUEST
OP_HTTP_PROXY_USER_REQUEST
OP_PIC_FORMAT_GIF
OP_PIC_FORMAT_JPEG
OP_PIC_FORMAT_PNG
OP_PIC_FORMAT_UNKNOWN
OP_PIC_FORMAT_URL
OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
OP_TRACK_GAIN

SEE ALSO

Audio::Opusfile::Head, Audio::Opusfile::Tags, http://opus-codec.org/, http://opus-codec.org/docs/opusfile_api-0.7/index.html

AUTHOR

Marius Gavrilescu, <marius@ieval.ro>

COPYRIGHT AND LICENSE

Copyright (C) 2016-2017 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.0 or, at your option, any later version of Perl 5 you may have available.