]>
Commit | Line | Data |
---|---|---|
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 - 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 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 | =item B<$of>->op_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 B<$of>->op_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 B<$of>->op_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 | =back | |
224 | ||
225 | =head1 EXPORT | |
226 | ||
227 | All 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 | ||
266 | L<Audio::Opusfile::Head>, | |
267 | L<Audio::Opusfile::Tags>, | |
268 | L<http://opus-codec.org/>, | |
269 | L<http://opus-codec.org/docs/opusfile_api-0.7/index.html> | |
270 | ||
271 | =head1 AUTHOR | |
272 | ||
273 | Marius Gavrilescu, E<lt>marius@ieval.roE<gt> | |
274 | ||
275 | =head1 COPYRIGHT AND LICENSE | |
276 | ||
277 | Copyright (C) 2016 by Marius Gavrilescu | |
278 | ||
279 | This library is free software; you can redistribute it and/or modify | |
280 | it under the same terms as Perl itself, either Perl version 5.24.0 or, | |
281 | at your option, any later version of Perl 5 you may have available. | |
282 | ||
283 | ||
284 | =cut |