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.003';
  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 - Very incomplete 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. At the moment its only
 121 function is reading metadata and tags from an Ogg Opus file or buffer.
 122 Future versions will give access to a larger part of the libopusfile
 123 API.
 124
 125 Expect the API to 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 B<$of>->head
 154
 155 Returns an L<Audio::Opusfile::Head> object corresponding to the file.
 156
 157 =item B<$of>->tags
 158
 159 Returns an L<Audio::Opusfile::Tags> object corresponding to the file.
 160
 161 =item B<$of>->seekable
 162
 163 Returns whether or not the data source being read is seekable.
 164
 165 =item B<$of>->link_count
 166
 167 Returns the number of links in this chained stream. Always returns 1
 168 for unseekable sources.
 169
 170 =item B<$of>->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 =back
 181
 182 =head1 EXPORT
 183
 184 All constants are exported by default:
 185
 186   OPUS_CHANNEL_COUNT_MAX
 187   OP_ABSOLUTE_GAIN
 188   OP_DEC_FORMAT_FLOAT
 189   OP_DEC_FORMAT_SHORT
 190   OP_DEC_USE_DEFAULT
 191   OP_EBADHEADER
 192   OP_EBADLINK
 193   OP_EBADPACKET
 194   OP_EBADTIMESTAMP
 195   OP_EFAULT
 196   OP_EIMPL
 197   OP_EINVAL
 198   OP_ENOSEEK
 199   OP_ENOTAUDIO
 200   OP_ENOTFORMAT
 201   OP_EOF
 202   OP_EREAD
 203   OP_EVERSION
 204   OP_FALSE
 205   OP_GET_SERVER_INFO_REQUEST
 206   OP_HEADER_GAIN
 207   OP_HOLE
 208   OP_HTTP_PROXY_HOST_REQUEST
 209   OP_HTTP_PROXY_PASS_REQUEST
 210   OP_HTTP_PROXY_PORT_REQUEST
 211   OP_HTTP_PROXY_USER_REQUEST
 212   OP_PIC_FORMAT_GIF
 213   OP_PIC_FORMAT_JPEG
 214   OP_PIC_FORMAT_PNG
 215   OP_PIC_FORMAT_UNKNOWN
 216   OP_PIC_FORMAT_URL
 217   OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
 218   OP_TRACK_GAIN
 219
 220
 221 =head1 SEE ALSO
 222
 223 L<Audio::Opusfile::Head>,
 224 L<Audio::Opusfile::Tags>,
 225 L<http://opus-codec.org/>,
 226 L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>
 227
 228 =head1 AUTHOR
 229
 230 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 231
 232 =head1 COPYRIGHT AND LICENSE
 233
 234 Copyright (C) 2016 by Marius Gavrilescu
 235
 236 This library is free software; you can redistribute it and/or modify
 237 it under the same terms as Perl itself, either Perl version 5.24.0 or,
 238 at your option, any later version of Perl 5 you may have available.
 239
 240
 241 =cut