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 B<$of>->op_raw_total([I<$link_index>])
+=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
logical Opus stream. Returning the latter would require scanning the
entire file.
-=item B<$of>->op_pcm_total([I<$link_index>])
+=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)
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>])
+=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
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
projects / audio-opusfile.git / commitdiff