From 10773025288df2601f2f4c1d804bcb524676941d Mon Sep 17 00:00:00 2001 From: Marius Gavrilescu Date: Sat, 10 Dec 2016 19:38:23 +0200 Subject: [PATCH] Document the previously added functions --- lib/Audio/Opusfile.pm | 114 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 106 insertions(+), 8 deletions(-) diff --git a/lib/Audio/Opusfile.pm b/lib/Audio/Opusfile.pm index c17306b..09fe9c7 100644 --- a/lib/Audio/Opusfile.pm +++ b/lib/Audio/Opusfile.pm @@ -150,24 +150,24 @@ 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 +=item $of->B Returns an L object corresponding to the file. -=item B<$of>->tags +=item $of->B Returns an L object corresponding to the file. -=item B<$of>->seekable +=item $of->B Returns whether or not the data source being read is seekable. -=item B<$of>->link_count +=item $of->B 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([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 @@ -177,7 +177,7 @@ 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>]) +=item $of->B([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 @@ -193,7 +193,7 @@ 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>]) +=item $of->B([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) @@ -206,7 +206,7 @@ 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>]) +=item $of->B([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 @@ -220,6 +220,104 @@ 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 + +Compute the instantaneous bitrate, measured as the ratio of bits to +playable samples decoded since a) the last call to B, +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 + +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 + +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(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(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(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 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(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([I<$bufsize>]) + +It is recommended to use B 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. + +You can use C<< $of->head($li)->channel_count >> to find out the +channel count of a given link index. + +=item $of->B([I<$bufsize>]) + +Like B, but samples are signed floats with a nominal range of +[-1.0, 1.0]. + +=item $of->B([I<$bufsize>]) + +Like B, 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([I<$bufsize>]) + +Like B, 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 -- 2.39.2