require XSLoader;
XSLoader::load('Audio::Opusfile', $VERSION);
+require Audio::Opusfile::Head;
require Audio::Opusfile::Tags;
require Audio::Opusfile::PictureTag;
=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 or buffer.
-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
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>