]> iEval git - audio-opusfile.git/blame_incremental - lib/Audio/Opusfile.pm
We're no longer very incomplete
[audio-opusfile.git] / lib / Audio / Opusfile.pm
... / ...
CommitLineData
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
49our $VERSION = '0.003';
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);
76require Audio::Opusfile::Head;
77require Audio::Opusfile::Tags;
78require Audio::Opusfile::PictureTag;
79
80# Preloaded methods go here.
81
82sub new_from_file {
83 my ($class, $file) = @_;
84 open_file($file)
85}
86
87sub new_from_memory {
88 my ($class, $buf) = @_;
89 open_memory($buf)
90}
91
921;
93__END__
94
95=encoding utf-8
96
97=head1 NAME
98
99Audio::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
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
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.
124
125The 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
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
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
153=item B<$of>->head
154
155Returns an L<Audio::Opusfile::Head> object corresponding to the file.
156
157=item B<$of>->tags
158
159Returns an L<Audio::Opusfile::Tags> object corresponding to the file.
160
161=item B<$of>->seekable
162
163Returns whether or not the data source being read is seekable.
164
165=item B<$of>->link_count
166
167Returns the number of links in this chained stream. Always returns 1
168for unseekable sources.
169
170=item B<$of>->serialno([I<$link_index>])
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
180=item B<$of>->op_raw_total([I<$link_index>])
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
196=item B<$of>->op_pcm_total([I<$link_index>])
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
209=item B<$of>->op_bitrate([I<$link_index>])
210
211Computes the bitrate of the stream (with no arguments), or of an
212individual link in a (possibly-chained) Ogg Opus stream (with one
213nonnegative argument).
214
215The stream must be seekable to compute the bitrate. A negative value
216is returned if the stream is not seekable.
217
218B<Warning:> If the Opus stream (or link) is concurrently multiplexed with
219other logical streams (e.g., video), this uses the size of the entire
220stream (or link) to compute the bitrate, not just the number of bytes
221in the first logical Opus stream.
222
223=back
224
225=head1 EXPORT
226
227All constants are exported by default:
228
229 OPUS_CHANNEL_COUNT_MAX
230 OP_ABSOLUTE_GAIN
231 OP_DEC_FORMAT_FLOAT
232 OP_DEC_FORMAT_SHORT
233 OP_DEC_USE_DEFAULT
234 OP_EBADHEADER
235 OP_EBADLINK
236 OP_EBADPACKET
237 OP_EBADTIMESTAMP
238 OP_EFAULT
239 OP_EIMPL
240 OP_EINVAL
241 OP_ENOSEEK
242 OP_ENOTAUDIO
243 OP_ENOTFORMAT
244 OP_EOF
245 OP_EREAD
246 OP_EVERSION
247 OP_FALSE
248 OP_GET_SERVER_INFO_REQUEST
249 OP_HEADER_GAIN
250 OP_HOLE
251 OP_HTTP_PROXY_HOST_REQUEST
252 OP_HTTP_PROXY_PASS_REQUEST
253 OP_HTTP_PROXY_PORT_REQUEST
254 OP_HTTP_PROXY_USER_REQUEST
255 OP_PIC_FORMAT_GIF
256 OP_PIC_FORMAT_JPEG
257 OP_PIC_FORMAT_PNG
258 OP_PIC_FORMAT_UNKNOWN
259 OP_PIC_FORMAT_URL
260 OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST
261 OP_TRACK_GAIN
262
263
264=head1 SEE ALSO
265
266L<Audio::Opusfile::Head>,
267L<Audio::Opusfile::Tags>,
268L<http://opus-codec.org/>,
269L<http://opus-codec.org/docs/opusfile_api-0.7/index.html>
270
271=head1 AUTHOR
272
273Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
274
275=head1 COPYRIGHT AND LICENSE
276
277Copyright (C) 2016 by Marius Gavrilescu
278
279This library is free software; you can redistribute it and/or modify
280it under the same terms as Perl itself, either Perl version 5.24.0 or,
281at your option, any later version of Perl 5 you may have available.
282
283
284=cut
This page took 0.083576 seconds and 4 git commands to generate.