1 package Audio
::Opusfile
;
8 use parent qw
/Exporter/;
12 qw
/OPUS_CHANNEL_COUNT_MAX
31 OP_GET_SERVER_INFO_REQUEST
34 OP_HTTP_PROXY_HOST_REQUEST
35 OP_HTTP_PROXY_PASS_REQUEST
36 OP_HTTP_PROXY_PORT_REQUEST
37 OP_HTTP_PROXY_USER_REQUEST
43 OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
46 our @EXPORT_OK = @constants;
47 our @EXPORT = @constants;
49 our $VERSION = '0.005001';
52 # This AUTOLOAD is used to 'autoload' constants from the constant()
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; }
63 # Fixed between 5.005_53 and 5.005_61
64 #XXX if ($] >= 5.00561) {
65 #XXX *$AUTOLOAD = sub () { $val };
68 *$AUTOLOAD = sub { $val };
75 XSLoader
::load
('Audio::Opusfile', $VERSION);
76 require Audio
::Opusfile
::Head
;
77 require Audio
::Opusfile
::Tags
;
78 require Audio
::Opusfile
::PictureTag
;
80 # Preloaded methods go here.
83 my ($class, $file) = @_;
88 my ($class, $buf) = @_;
99 Audio::Opusfile - partial interface to the libopusfile Ogg Opus library
104 my $of = Audio::Opusfile->new_from_file('silence.opus');
105 my $tags = $of->tags;
106 say $tags->query('TITLE'); # Cellule
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.
117 libopusfile is a library for decoding and basic manipulation of Ogg
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.
125 The API might change in future versions.
131 =item Audio::Opusfile->B<new_from_file>(I<$file>)
133 Creates a new Audio::Opusfile object from an Ogg Opus file.
135 Dies if the given file does not exist or is not a valid Ogg Opus file.
137 =item Audio::Opusfile->B<new_from_memory>(I<$buffer>)
139 Creates a new Audio::Opusfile object from a buffer containing Ogg Opus
142 Dies if the given buffer does not contain valid data.
144 =item Audio::Opusfile::test(I<$buffer>)
146 Returns true if the given buffer looks like the beginning of a valid
147 Ogg Opus file, false otherwise.
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
155 Returns an L<Audio::Opusfile::Head> object corresponding to the file.
159 Returns an L<Audio::Opusfile::Tags> object corresponding to the file.
161 =item $of->B<seekable>
163 Returns whether or not the data source being read is seekable.
165 =item $of->B<link_count>
167 Returns the number of links in this chained stream. Always returns 1
168 for unseekable sources.
170 =item $of->B<serialno>([I<$link_index>])
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.
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.
180 =item $of->B<raw_total>([I<$link_index>])
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
187 The stream must be seekable to get the total. A negative value is
188 returned if the stream is not seekable.
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
196 =item $of->B<pcm_total>([I<$link_index>])
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).
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.
206 The stream must be seekable to get the total. A negative value is
207 returned if the stream is not seekable.
209 =item $of->B<current_link>
211 Retrieve the index of the current link.
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).
218 =item $of->B<bitrate>([I<$link_index>])
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).
224 The stream must be seekable to compute the bitrate. A negative value
225 is returned if the stream is not seekable.
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.
232 =item $of->B<bitrate_instant>
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
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.
243 =item $of->B<raw_tell>
245 Obtain the current value of the position indicator of I<$of>. This is
246 the byte position that is currently being read from.
248 =item $of->B<pcm_tell>
250 Obtain the PCM offset of the next sample to be read.
252 If the stream is not properly timestamped, this might not increment by
253 the proper amount between reads, or even return monotonically
256 =item $of->B<raw_seek>(I<$offset>)
258 Seek to a byte offset relative to the compressed data.
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.
264 =item $of->B<pcm_seek>(I<$offset>)
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.
270 =item $of->B<set_gain_offset>(I<$gain_type>, I<$gain_offset>)
272 Sets the gain to be used for decoded output.
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.
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.
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.
287 =item $of->B<set_dither_enabled>(I<$enabled>)
289 Sets whether or not dithering is enabled for 16-bit decoding.
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.
298 =item $of->B<read>([I<$bufsize>])
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.
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>.
310 You can use C<< $of->head($li)->channel_count >> to find out the
311 channel count of a given link index.
313 =item $of->B<read_float>([I<$bufsize>])
315 Like B<read>, but samples are signed floats with a nominal range of
318 =item $of->B<read_stereo>([I<$bufsize>])
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).
324 =item $of->B<read_float_stereo>([I<$bufsize>])
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).
334 All constants are exported by default:
336 OPUS_CHANNEL_COUNT_MAX
355 OP_GET_SERVER_INFO_REQUEST
358 OP_HTTP_PROXY_HOST_REQUEST
359 OP_HTTP_PROXY_PASS_REQUEST
360 OP_HTTP_PROXY_PORT_REQUEST
361 OP_HTTP_PROXY_USER_REQUEST
365 OP_PIC_FORMAT_UNKNOWN
367 OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
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>
380 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
382 =head1 COPYRIGHT AND LICENSE
384 Copyright (C) 2016-2017 by Marius Gavrilescu
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.