view release on metacpan or  search on metacpan

lib/Audio/Opusfile.pm  view on Meta::CPAN

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