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