our @EXPORT_OK = @constants;
our @EXPORT = @constants;
-our $VERSION = '0.002001';
+our $VERSION = '0.003';
sub AUTOLOAD {
# This AUTOLOAD is used to 'autoload' constants from the constant()
require XSLoader;
XSLoader::load('Audio::Opusfile', $VERSION);
+require Audio::Opusfile::Head;
require Audio::Opusfile::Tags;
require Audio::Opusfile::PictureTag;
open_file($file)
}
+sub new_from_memory {
+ my ($class, $buf) = @_;
+ open_memory($buf)
+}
+
1;
__END__
=head1 NAME
-Audio::Opusfile - Very incomplete interface to the libopusfile Ogg Opus library
+Audio::Opusfile - partial interface to the libopusfile Ogg Opus library
=head1 SYNOPSIS
libopusfile is a library for decoding and basic manipulation of Ogg
Opus files.
-Audio::Opusfile is an interface to libopusfile. At the moment its only
-function is reading metadata and tags from an Ogg Opus file. Future
-versions will give access to a larger part of the libopusfile API.
+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.
-Expect the API to change in future versions.
+The API might change in future versions.
=head1 METHODS
Dies if the given file does not exist or is not a valid Ogg Opus file.
+=item Audio::Opusfile->B<new_from_memory>(I<$buffer>)
+
+Creates a new Audio::Opusfile object from a buffer containing Ogg Opus
+data.
+
+Dies if the given buffer does not contain valid data.
+
+=item Audio::Opusfile::test(I<$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.
+
=item B<$of>->head
Returns an L<Audio::Opusfile::Head> object corresponding to the file.
Returns an L<Audio::Opusfile::Tags> object corresponding to the file.
+=item B<$of>->seekable
+
+Returns whether or not the data source being read is seekable.
+
+=item B<$of>->link_count
+
+Returns the number of links in this chained stream. Always returns 1
+for unseekable sources.
+
+=item B<$of>->serialno([I<$link_index>])
+
+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, I<$link_index> is negative, or
+I<$link_index> is not given, then this function returns the serial
+number of the current link.
+
+=item B<$of>->op_raw_total([I<$link_index>])
+
+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.
+
+B<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.
+
+=item B<$of>->op_pcm_total([I<$link_index>])
+
+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.
+
+=item B<$of>->op_bitrate([I<$link_index>])
+
+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.
+
+B<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.
+
=back
=head1 EXPORT
=head1 SEE ALSO
+L<Audio::Opusfile::Head>,
L<Audio::Opusfile::Tags>,
L<http://opus-codec.org/>,
L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>