Bump version and update Changes

[audio-opusfile.git] / lib / Audio / Opusfile.pm

diff --git a/lib/Audio/Opusfile.pm b/lib/Audio/Opusfile.pm
index 430de4fa0e7248a1f4d81c5ada727df18c10002f..c17306b7eeafc8cc76b76cb4a47ccf239f4743a7 100644 (file)
--- a/lib/Audio/Opusfile.pm
+++ b/lib/Audio/Opusfile.pm
@@ -46,7 +46,7 @@ my @constants =
 our @EXPORT_OK = @constants;
 our @EXPORT = @constants;
 
-our $VERSION = '0.001';
+our $VERSION = '0.004';
 
 sub AUTOLOAD {
     # This AUTOLOAD is used to 'autoload' constants from the constant()
@@ -73,7 +73,9 @@ sub AUTOLOAD {
 
 require XSLoader;
 XSLoader::load('Audio::Opusfile', $VERSION);
+require Audio::Opusfile::Head;
 require Audio::Opusfile::Tags;
+require Audio::Opusfile::PictureTag;
 
 # Preloaded methods go here.
 
@@ -82,6 +84,11 @@ sub new_from_file {
        open_file($file)
 }
 
+sub new_from_memory {
+       my ($class, $buf) = @_;
+       open_memory($buf)
+}
+
 1;
 __END__
 
@@ -89,7 +96,7 @@ __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
 
@@ -110,11 +117,12 @@ 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. At the moment its only
-function is reading 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
 
@@ -126,10 +134,92 @@ 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.
 
+=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.
+
 =item B<$of>->tags
 
 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
@@ -173,6 +263,7 @@ All constants are exported by default:
 
 =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>