lib/Audio/Opusfile.pm

   1 package Audio::Opusfile;
   2
   3 use 5.014000;
   4 use strict;
   5 use warnings;
   6 use Carp;
   7
   8 use parent qw/Exporter/;
   9 use AutoLoader;
  10
  11 my @constants =
  12   qw/OPUS_CHANNEL_COUNT_MAX
  13          OP_ABSOLUTE_GAIN
  14          OP_DEC_FORMAT_FLOAT
  15          OP_DEC_FORMAT_SHORT
  16          OP_DEC_USE_DEFAULT
  17          OP_EBADHEADER
  18          OP_EBADLINK
  19          OP_EBADPACKET
  20          OP_EBADTIMESTAMP
  21          OP_EFAULT
  22          OP_EIMPL
  23          OP_EINVAL
  24          OP_ENOSEEK
  25          OP_ENOTAUDIO
  26          OP_ENOTFORMAT
  27          OP_EOF
  28          OP_EREAD
  29          OP_EVERSION
  30          OP_FALSE
  31          OP_GET_SERVER_INFO_REQUEST
  32          OP_HEADER_GAIN
  33          OP_HOLE
  34          OP_HTTP_PROXY_HOST_REQUEST
  35          OP_HTTP_PROXY_PASS_REQUEST
  36          OP_HTTP_PROXY_PORT_REQUEST
  37          OP_HTTP_PROXY_USER_REQUEST
  38          OP_PIC_FORMAT_GIF
  39          OP_PIC_FORMAT_JPEG
  40          OP_PIC_FORMAT_PNG
  41          OP_PIC_FORMAT_UNKNOWN
  42          OP_PIC_FORMAT_URL
  43          OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
  44          OP_TRACK_GAIN/;
  45
  46 our @EXPORT_OK = @constants;
  47 our @EXPORT = @constants;
  48
  49 our $VERSION = '1.000';
  50
  51 sub AUTOLOAD { ## no critic (ProhibitAutoloading)
  52         my $constname;
  53         our $AUTOLOAD;
  54         ($constname = $AUTOLOAD) =~ s/.*:://s;
  55         croak '&Audio::Opusfile::constant not defined' if $constname eq 'constant';
  56         my ($error, $val) = constant($constname);
  57         if ($error) { croak $error; }
  58         {
  59                 no strict 'refs'; ## no critic (ProhibitNoStrict)
  60                 *$AUTOLOAD = sub { $val };
  61         }
  62         goto &$AUTOLOAD;
  63 }
  64
  65 require XSLoader;
  66 XSLoader::load('Audio::Opusfile', $VERSION);
  67 require Audio::Opusfile::Head;
  68 require Audio::Opusfile::Tags;
  69 require Audio::Opusfile::PictureTag;
  70
  71 sub new_from_file {
  72         my ($class, $file) = @_;
  73         open_file($file)
  74 }
  75
  76 sub new_from_memory {
  77         my ($class, $buf) = @_;
  78         open_memory($buf)
  79 }
  80
  81 1;
  82 __END__
  83
  84 =encoding utf-8
  85
  86 =head1 NAME
  87
  88 Audio::Opusfile - partial interface to the libopusfile Ogg Opus library
  89
  90 =head1 SYNOPSIS
  91
  92   use Audio::Opusfile;
  93   my $of = Audio::Opusfile->new_from_file('silence.opus');
  94   my $tags = $of->tags;
  95   say $tags->query('TITLE'); # Cellule
  96
  97 =head1 DESCRIPTION
  98
  99 Opus is a totally open, royalty-free, highly versatile audio codec.
 100 Opus is unmatched for interactive speech and music transmission over
 101 the Internet, but is also intended for storage and streaming
 102 applications. It is standardized by the Internet Engineering Task
 103 Force (IETF) as RFC 6716 which incorporated technology from Skype's
 104 SILK codec and Xiph.Org's CELT codec.
 105
 106 libopusfile is a library for decoding and basic manipulation of Ogg
 107 Opus files.
 108
 109 Audio::Opusfile is an interface to libopusfile. It exports nearly all
 110 of the functions for obtaining metadata of an Opus file or buffer in
 111 that library. Future versions will additionally provide functions for
 112 decoding Opus data into PCM.
 113
 114 The API might change in future versions.
 115
 116 =head1 METHODS
 117
 118 =over
 119
 120 =item Audio::Opusfile->B<new_from_file>(I<$file>)
 121
 122 Creates a new Audio::Opusfile object from an Ogg Opus file.
 123
 124 Dies if the given file does not exist or is not a valid Ogg Opus file.
 125
 126 =item Audio::Opusfile->B<new_from_memory>(I<$buffer>)
 127
 128 Creates a new Audio::Opusfile object from a buffer containing Ogg Opus
 129 data.
 130
 131 Dies if the given buffer does not contain valid data.
 132
 133 =item Audio::Opusfile::test(I<$buffer>)
 134
 135 Returns true if the given buffer looks like the beginning of a valid
 136 Ogg Opus file, false otherwise.
 137
 138 Dies if the given buffer does not have sufficient data to tell if it
 139 is an Opus stream or if it looks like a Opus stream but parsing it
 140 failed.
 141
 142 =item $of->B<head>
 143
 144 Returns an L<Audio::Opusfile::Head> object corresponding to the file.
 145
 146 =item $of->B<tags>
 147
 148 Returns an L<Audio::Opusfile::Tags> object corresponding to the file.
 149
 150 =item $of->B<seekable>
 151
 152 Returns whether or not the data source being read is seekable.
 153
 154 =item $of->B<link_count>
 155
 156 Returns the number of links in this chained stream. Always returns 1
 157 for unseekable sources.
 158
 159 =item $of->B<serialno>([I<$link_index>])
 160
 161 Get the serial number of the given link in a (possibly-chained) Ogg
 162 Opus stream. If the given index is greater than the total number of
 163 links, this returns the serial number of the last link.
 164
 165 If the source is not seekable, I<$link_index> is negative, or
 166 I<$link_index> is not given, then this function returns the serial
 167 number of the current link.
 168
 169 =item $of->B<raw_total>([I<$link_index>])
 170
 171 Get the total (compressed) size of the stream (with no arguments), or
 172 of an individual link in a (possibly-chained) Ogg Opus stream (with
 173 one nonnegative argument), including all headers and Ogg muxing
 174 overhead.
 175
 176 The stream must be seekable to get the total. A negative value is
 177 returned if the stream is not seekable.
 178
 179 B<Warning:> If the Opus stream (or link) is concurrently multiplexed
 180 with other logical streams (e.g., video), this returns the size of the
 181 entire stream (or link), not just the number of bytes in the first
 182 logical Opus stream. Returning the latter would require scanning the
 183 entire file.
 184
 185 =item $of->B<pcm_total>([I<$link_index>])
 186
 187 Get the total PCM length (number of samples at 48 kHz) of the stream
 188 (with no arguments), or of an individual link in a (possibly-chained)
 189 Ogg Opus stream (with one nonnegative argument).
 190
 191 Users looking for op_time_total() should use this function instead.
 192 Because timestamps in Opus are fixed at 48 kHz, there is no need for a
 193 separate function to convert this to seconds.
 194
 195 The stream must be seekable to get the total. A negative value is
 196 returned if the stream is not seekable.
 197
 198 =item $of->B<current_link>
 199
 200 Retrieve the index of the current link.
 201
 202 This is the link that produced the data most recently read by
 203 op_read_float() or its associated functions, or, after a seek, the
 204 link that the seek target landed in. Reading more data may advance the
 205 link index (even on the first read after a seek).
 206
 207 =item $of->B<bitrate>([I<$link_index>])
 208
 209 Computes the bitrate of the stream (with no arguments), or of an
 210 individual link in a (possibly-chained) Ogg Opus stream (with one
 211 nonnegative argument).
 212
 213 The stream must be seekable to compute the bitrate. A negative value
 214 is returned if the stream is not seekable.
 215
 216 B<Warning:> If the Opus stream (or link) is concurrently multiplexed with
 217 other logical streams (e.g., video), this uses the size of the entire
 218 stream (or link) to compute the bitrate, not just the number of bytes
 219 in the first logical Opus stream.
 220
 221 =item $of->B<bitrate_instant>
 222
 223 Compute the instantaneous bitrate, measured as the ratio of bits to
 224 playable samples decoded since a) the last call to B<bitrate_instant>,
 225 b) the last seek, or c) the start of playback, whichever was most
 226 recent.
 227
 228 This will spike somewhat after a seek or at the start/end of a chain
 229 boundary, as pre-skip, pre-roll, and end-trimming causes samples to be
 230 decoded but not played.
 231
 232 =item $of->B<raw_tell>
 233
 234 Obtain the current value of the position indicator of I<$of>. This is
 235 the byte position that is currently being read from.
 236
 237 =item $of->B<pcm_tell>
 238
 239 Obtain the PCM offset of the next sample to be read.
 240
 241 If the stream is not properly timestamped, this might not increment by
 242 the proper amount between reads, or even return monotonically
 243 increasing values.
 244
 245 =item $of->B<raw_seek>(I<$offset>)
 246
 247 Seek to a byte offset relative to the compressed data.
 248
 249 This also scans packets to update the PCM cursor. It will cross a
 250 logical bitstream boundary, but only if it can't get any packets out
 251 of the tail of the link to which it seeks.
 252
 253 =item $of->B<pcm_seek>(I<$offset>)
 254
 255 Seek to the specified PCM offset, such that decoding will begin at
 256 exactly the requested position. The PCM offset is in samples at 48 kHz
 257 relative to the start of the stream.
 258
 259 =item $of->B<set_gain_offset>(I<$gain_type>, I<$gain_offset>)
 260
 261 Sets the gain to be used for decoded output.
 262
 263 By default, the gain in the header is applied with no additional
 264 offset. The total gain (including header gain and/or track gain, if
 265 applicable, and this offset), will be clamped to [-32768,32767]/256
 266 dB. This is more than enough to saturate or underflow 16-bit PCM.
 267
 268 B<Note:> The new gain will not be applied to any already buffered,
 269 decoded output. This means you cannot change it sample-by-sample, as
 270 at best it will be updated packet-by-packet. It is meant for setting a
 271 target volume level, rather than applying smooth fades, etc.
 272
 273 I<$gain_type> is one of OP_HEADER_GAIN, OP_TRACK_GAIN, or
 274 OP_ABSOLUTE_GAIN. I<$gain_offset> is in 1/256ths of a dB.
 275
 276 =item $of->B<set_dither_enabled>(I<$enabled>)
 277
 278 Sets whether or not dithering is enabled for 16-bit decoding.
 279
 280 By default, when libopusfile is compiled to use floating-point
 281 internally, calling read() or read_stereo() will first decode to
 282 float, and then convert to fixed-point using noise-shaping dithering.
 283 This flag can be used to disable that dithering. When the application
 284 uses read_float() or read_float_stereo(), or when the library has been
 285 compiled to decode directly to fixed point, this flag has no effect.
 286
 287 =item $of->B<read>([I<$bufsize>])
 288
 289 It is recommended to use B<read_float> instead of this method if the
 290 rest of your audio processing chain can handle floating point.
 291
 292 Reads more samples from the stream. I<$bufsize> is the maximum number
 293 of samples read, and it defaults to 1048576. Returns a list whose
 294 first element is the link index this data was decoded from, and the
 295 rest of the elements are PCM samples, as signed 16-bit values at 48
 296 kHz with a nominal range of [-32768,32767). Multiple channels are
 297 interleaved using the L<Vorbis channel ordering|https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9>.
 298
 299 You can use C<< $of->head($li)->channel_count >> to find out the
 300 channel count of a given link index.
 301
 302 =item $of->B<read_float>([I<$bufsize>])
 303
 304 Like B<read>, but samples are signed floats with a nominal range of
 305 [-1.0, 1.0].
 306
 307 =item $of->B<read_stereo>([I<$bufsize>])
 308
 309 Like B<read>, but downmixes the stream to stereo (therefore you will
 310 always get two channels) and does NOT return the link index (the first
 311 return value is the first sample).
 312
 313 =item $of->B<read_float_stereo>([I<$bufsize>])
 314
 315 Like B<read_float>, but downmixes the stream to stereo (therefore you
 316 will always get two channels) and does NOT return the link index (the
 317 first return value is the first sample).
 318
 319 =back
 320
 321 =head1 EXPORT
 322
 323 All constants are exported by default:
 324
 325   OPUS_CHANNEL_COUNT_MAX
 326   OP_ABSOLUTE_GAIN
 327   OP_DEC_FORMAT_FLOAT
 328   OP_DEC_FORMAT_SHORT
 329   OP_DEC_USE_DEFAULT
 330   OP_EBADHEADER
 331   OP_EBADLINK
 332   OP_EBADPACKET
 333   OP_EBADTIMESTAMP
 334   OP_EFAULT
 335   OP_EIMPL
 336   OP_EINVAL
 337   OP_ENOSEEK
 338   OP_ENOTAUDIO
 339   OP_ENOTFORMAT
 340   OP_EOF
 341   OP_EREAD
 342   OP_EVERSION
 343   OP_FALSE
 344   OP_GET_SERVER_INFO_REQUEST
 345   OP_HEADER_GAIN
 346   OP_HOLE
 347   OP_HTTP_PROXY_HOST_REQUEST
 348   OP_HTTP_PROXY_PASS_REQUEST
 349   OP_HTTP_PROXY_PORT_REQUEST
 350   OP_HTTP_PROXY_USER_REQUEST
 351   OP_PIC_FORMAT_GIF
 352   OP_PIC_FORMAT_JPEG
 353   OP_PIC_FORMAT_PNG
 354   OP_PIC_FORMAT_UNKNOWN
 355   OP_PIC_FORMAT_URL
 356   OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
 357   OP_TRACK_GAIN
 358
 359
 360 =head1 SEE ALSO
 361
 362 L<Audio::Opusfile::Head>,
 363 L<Audio::Opusfile::Tags>,
 364 L<http://opus-codec.org/>,
 365 L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>
 366
 367 =head1 AUTHOR
 368
 369 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 370
 371 =head1 COPYRIGHT AND LICENSE
 372
 373 Copyright (C) 2016-2017 by Marius Gavrilescu
 374
 375 This library is free software; you can redistribute it and/or modify
 376 it under the same terms as Perl itself, either Perl version 5.24.0 or,
 377 at your option, any later version of Perl 5 you may have available.
 378
 379
 380 =cut