]> iEval git - audio-opusfile.git/blob - lib/Audio/Opusfile.pm
a6bbc4751e47f78a72df63a33acf8d70c7751248
[audio-opusfile.git] / 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.005';
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<bitrate>([I<$link_index>])
210
211 Computes the bitrate of the stream (with no arguments), or of an
212 individual link in a (possibly-chained) Ogg Opus stream (with one
213 nonnegative argument).
214
215 The stream must be seekable to compute the bitrate. A negative value
216 is returned if the stream is not seekable.
217
218 B<Warning:> If the Opus stream (or link) is concurrently multiplexed with
219 other logical streams (e.g., video), this uses the size of the entire
220 stream (or link) to compute the bitrate, not just the number of bytes
221 in the first logical Opus stream.
222
223 =item $of->B<bitrate_instant>
224
225 Compute the instantaneous bitrate, measured as the ratio of bits to
226 playable samples decoded since a) the last call to B<bitrate_instant>,
227 b) the last seek, or c) the start of playback, whichever was most
228 recent.
229
230 This will spike somewhat after a seek or at the start/end of a chain
231 boundary, as pre-skip, pre-roll, and end-trimming causes samples to be
232 decoded but not played.
233
234 =item $of->B<raw_tell>
235
236 Obtain the current value of the position indicator of I<$of>. This is
237 the byte position that is currently being read from.
238
239 =item $of->B<pcm_tell>
240
241 Obtain the PCM offset of the next sample to be read.
242
243 If the stream is not properly timestamped, this might not increment by
244 the proper amount between reads, or even return monotonically
245 increasing values.
246
247 =item $of->B<raw_seek>(I<$offset>)
248
249 Seek to a byte offset relative to the compressed data.
250
251 This also scans packets to update the PCM cursor. It will cross a
252 logical bitstream boundary, but only if it can't get any packets out
253 of the tail of the link to which it seeks.
254
255 =item $of->B<pcm_seek>(I<$offset>)
256
257 Seek to the specified PCM offset, such that decoding will begin at
258 exactly the requested position. The PCM offset is in samples at 48 kHz
259 relative to the start of the stream.
260
261 =item $of->B<set_gain_offset>(I<$gain_type>, I<$gain_offset>)
262
263 Sets the gain to be used for decoded output.
264
265 By default, the gain in the header is applied with no additional
266 offset. The total gain (including header gain and/or track gain, if
267 applicable, and this offset), will be clamped to [-32768,32767]/256
268 dB. This is more than enough to saturate or underflow 16-bit PCM.
269
270 B<Note:> The new gain will not be applied to any already buffered,
271 decoded output. This means you cannot change it sample-by-sample, as
272 at best it will be updated packet-by-packet. It is meant for setting a
273 target volume level, rather than applying smooth fades, etc.
274
275 I<$gain_type> is one of OP_HEADER_GAIN, OP_TRACK_GAIN, or
276 OP_ABSOLUTE_GAIN. I<$gain_offset> is in 1/256ths of a dB.
277
278 =item $of->B<set_dither_enabled>(I<$enabled>)
279
280 Sets whether or not dithering is enabled for 16-bit decoding.
281
282 By default, when libopusfile is compiled to use floating-point
283 internally, calling read() or read_stereo() will first decode to
284 float, and then convert to fixed-point using noise-shaping dithering.
285 This flag can be used to disable that dithering. When the application
286 uses read_float() or read_float_stereo(), or when the library has been
287 compiled to decode directly to fixed point, this flag has no effect.
288
289 =item $of->B<read>([I<$bufsize>])
290
291 It is recommended to use B<read_float> instead of this method if the
292 rest of your audio processing chain can handle floating point.
293
294 Reads more samples from the stream. I<$bufsize> is the maximum number
295 of samples read, and it defaults to 1048576. Returns a list whose
296 first element is the link index this data was decoded from, and the
297 rest of the elements are PCM samples, as signed 16-bit values at 48
298 kHz with a nominal range of [-32768,32767). Multiple channels are
299 interleaved using the L<Vorbis channel ordering|https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9>.
300
301 You can use C<< $of->head($li)->channel_count >> to find out the
302 channel count of a given link index.
303
304 =item $of->B<read_float>([I<$bufsize>])
305
306 Like B<read>, but samples are signed floats with a nominal range of
307 [-1.0, 1.0].
308
309 =item $of->B<read_stereo>([I<$bufsize>])
310
311 Like B<read>, but downmixes the stream to stereo (therefore you will
312 always get two channels) and does NOT return the link index (the first
313 return value is the first sample).
314
315 =item $of->B<read_float_stereo>([I<$bufsize>])
316
317 Like B<read_float>, but downmixes the stream to stereo (therefore you
318 will always get two channels) and does NOT return the link index (the
319 first return value is the first sample).
320
321 =back
322
323 =head1 EXPORT
324
325 All constants are exported by default:
326
327 OPUS_CHANNEL_COUNT_MAX
328 OP_ABSOLUTE_GAIN
329 OP_DEC_FORMAT_FLOAT
330 OP_DEC_FORMAT_SHORT
331 OP_DEC_USE_DEFAULT
332 OP_EBADHEADER
333 OP_EBADLINK
334 OP_EBADPACKET
335 OP_EBADTIMESTAMP
336 OP_EFAULT
337 OP_EIMPL
338 OP_EINVAL
339 OP_ENOSEEK
340 OP_ENOTAUDIO
341 OP_ENOTFORMAT
342 OP_EOF
343 OP_EREAD
344 OP_EVERSION
345 OP_FALSE
346 OP_GET_SERVER_INFO_REQUEST
347 OP_HEADER_GAIN
348 OP_HOLE
349 OP_HTTP_PROXY_HOST_REQUEST
350 OP_HTTP_PROXY_PASS_REQUEST
351 OP_HTTP_PROXY_PORT_REQUEST
352 OP_HTTP_PROXY_USER_REQUEST
353 OP_PIC_FORMAT_GIF
354 OP_PIC_FORMAT_JPEG
355 OP_PIC_FORMAT_PNG
356 OP_PIC_FORMAT_UNKNOWN
357 OP_PIC_FORMAT_URL
358 OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
359 OP_TRACK_GAIN
360
361
362 =head1 SEE ALSO
363
364 L<Audio::Opusfile::Head>,
365 L<Audio::Opusfile::Tags>,
366 L<http://opus-codec.org/>,
367 L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>
368
369 =head1 AUTHOR
370
371 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
372
373 =head1 COPYRIGHT AND LICENSE
374
375 Copyright (C) 2016 by Marius Gavrilescu
376
377 This library is free software; you can redistribute it and/or modify
378 it under the same terms as Perl itself, either Perl version 5.24.0 or,
379 at your option, any later version of Perl 5 you may have available.
380
381
382 =cut
This page took 0.07262 seconds and 3 git commands to generate.