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