Audio::Opusfile - partial interface to the libopusfile Ogg Opus library
use Audio::Opusfile; my $of = Audio::Opusfile->new_from_file('silence.opus'); my $tags = $of->tags; say $tags->query('TITLE'); # Cellule
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.
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.
Creates a new Audio::Opusfile object from a buffer containing Ogg Opus data.
Dies if the given buffer does not contain valid data.
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.
Returns an Audio::Opusfile::Head object corresponding to the file.
Returns an Audio::Opusfile::Tags object corresponding to the file.
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.
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.
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.
Obtain the current value of the position indicator of $of. This is the byte position that is currently being read from.
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.
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.
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.
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.
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.
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->head($li)->channel_count
Like read, but samples are signed floats with a nominal range of [-1.0, 1.0].
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).
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).
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
Audio::Opusfile::Head, Audio::Opusfile::Tags, http://opus-codec.org/, http://opus-codec.org/docs/opusfile_api-0.7/index.html
Marius Gavrilescu, <marius@ieval.ro>
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.
To install Audio::Opusfile, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Audio::Opusfile
CPAN shell
perl -MCPAN -e shell install Audio::Opusfile
For more information on module installation, please visit the detailed CPAN module installation guide.