our @EXPORT_OK = @constants;
our @EXPORT = @constants;
-our $VERSION = '0.003';
-
-sub AUTOLOAD {
- # This AUTOLOAD is used to 'autoload' constants from the constant()
- # XS function.
-
- my $constname;
- our $AUTOLOAD;
- ($constname = $AUTOLOAD) =~ s/.*:://;
- croak "&Audio::Opusfile::constant not defined" if $constname eq 'constant';
- my ($error, $val) = constant($constname);
- if ($error) { croak $error; }
- {
- no strict 'refs';
- # Fixed between 5.005_53 and 5.005_61
-#XXX if ($] >= 5.00561) {
-#XXX *$AUTOLOAD = sub () { $val };
-#XXX }
-#XXX else {
- *$AUTOLOAD = sub { $val };
-#XXX }
- }
- goto &$AUTOLOAD;
+our $VERSION = '1.000';
+
+sub AUTOLOAD { ## no critic (ProhibitAutoloading)
+ my $constname;
+ our $AUTOLOAD;
+ ($constname = $AUTOLOAD) =~ s/.*:://s;
+ croak '&Audio::Opusfile::constant not defined' if $constname eq 'constant';
+ my ($error, $val) = constant($constname);
+ if ($error) { croak $error; }
+ {
+ no strict 'refs'; ## no critic (ProhibitNoStrict)
+ *$AUTOLOAD = sub { $val };
+ }
+ goto &$AUTOLOAD;
}
require XSLoader;
require Audio::Opusfile::Tags;
require Audio::Opusfile::PictureTag;
-# Preloaded methods go here.
-
sub new_from_file {
my ($class, $file) = @_;
open_file($file)
=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
is an Opus stream or if it looks like a Opus stream but parsing it
failed.
-=item B<$of>->head
+=item $of->B<head>
Returns an L<Audio::Opusfile::Head> object corresponding to the file.
-=item B<$of>->tags
+=item $of->B<tags>
Returns an L<Audio::Opusfile::Tags> object corresponding to the file.
-=item B<$of>->seekable
+=item $of->B<seekable>
Returns whether or not the data source being read is seekable.
-=item B<$of>->link_count
+=item $of->B<link_count>
Returns the number of links in this chained stream. Always returns 1
for unseekable sources.
-=item B<$of>->serialno([I<$link_index>])
+=item $of->B<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
I<$link_index> is not given, then this function returns the serial
number of the current link.
+=item $of->B<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 $of->B<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 $of->B<current_link>
+
+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).
+
+=item $of->B<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.
+
+=item $of->B<bitrate_instant>
+
+Compute the instantaneous bitrate, measured as the ratio of bits to
+playable samples decoded since a) the last call to B<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.
+
+=item $of->B<raw_tell>
+
+Obtain the current value of the position indicator of I<$of>. This is
+the byte position that is currently being read from.
+
+=item $of->B<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.
+
+=item $of->B<raw_seek>(I<$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.
+
+=item $of->B<pcm_seek>(I<$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.
+
+=item $of->B<set_gain_offset>(I<$gain_type>, I<$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.
+
+B<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.
+
+I<$gain_type> is one of OP_HEADER_GAIN, OP_TRACK_GAIN, or
+OP_ABSOLUTE_GAIN. I<$gain_offset> is in 1/256ths of a dB.
+
+=item $of->B<set_dither_enabled>(I<$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.
+
+=item $of->B<read>([I<$bufsize>])
+
+It is recommended to use B<read_float> instead of this method if the
+rest of your audio processing chain can handle floating point.
+
+Reads more samples from the stream. I<$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 L<Vorbis channel ordering|https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9>.
+
+You can use C<< $of->head($li)->channel_count >> to find out the
+channel count of a given link index.
+
+=item $of->B<read_float>([I<$bufsize>])
+
+Like B<read>, but samples are signed floats with a nominal range of
+[-1.0, 1.0].
+
+=item $of->B<read_stereo>([I<$bufsize>])
+
+Like B<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).
+
+=item $of->B<read_float_stereo>([I<$bufsize>])
+
+Like B<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).
+
=back
=head1 EXPORT
=head1 COPYRIGHT AND LICENSE
-Copyright (C) 2016 by Marius Gavrilescu
+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,
projects / audio-opusfile.git / blobdiff