Commit | Line | Data |
---|---|---|
b9bd6a0d MG |
1 | package Audio::Opusfile::Head; |
2 | # Don't load this module directly, load Audio::Opusfile instead | |
3 | ||
4 | use 5.014000; | |
5 | use strict; | |
6 | use warnings; | |
7 | ||
36bdc941 | 8 | our $VERSION = '0.005001'; |
b9bd6a0d MG |
9 | |
10 | 1; | |
11 | __END__ | |
12 | ||
13 | =encoding utf-8 | |
14 | ||
15 | =head1 NAME | |
16 | ||
17 | Audio::Opusfile::Head - The header of an Ogg Opus file | |
18 | ||
19 | =head1 SYNOPSIS | |
20 | ||
21 | use blib; | |
22 | use Audio::Opusfile; | |
23 | my $of = Audio::Opusfile->new_from_file('empty.opus'); | |
24 | my $head = $of->head; | |
25 | say $head->version; # 1 | |
26 | say $head->channel_count; # 2 | |
27 | say $head->pre_skip; # 356 | |
28 | say $head->input_sample_rate; # 44100 | |
29 | say $head->output_gain; # 0 | |
30 | say $head->mapping_family; # 0 | |
31 | say $head->stream_count; # 1 | |
32 | say $head->coupled_count; # 1 | |
33 | say $head->mapping(0); # 0 | |
34 | say $head->mapping(1); # 1 | |
35 | ||
36 | =head1 DESCRIPTION | |
37 | ||
38 | This module represents the header of an Ogg Opus file. See the | |
39 | documentation of L<Audio::Opusfile> for more information. | |
40 | ||
41 | =head1 METHODS | |
42 | ||
43 | =over | |
44 | ||
45 | =item $head->B<version> | |
46 | ||
47 | The Ogg Opus format version, in the range 0...255. | |
48 | ||
49 | The top 4 bits represent a "major" version, and the bottom four bits | |
50 | represent backwards-compatible "minor" revisions. | |
51 | ||
52 | The current specification describes version 1. | |
53 | ||
54 | =item $head->B<channel_count> | |
55 | ||
56 | The number of channels, in the range 1...255. | |
57 | ||
58 | =item $head->B<pre_skip> | |
59 | ||
60 | The number of samples that should be discarded from the beginning of | |
61 | the stream. | |
62 | ||
63 | =item $head->B<input_sample_rate> | |
64 | ||
65 | The sampling rate of the original input. | |
66 | ||
67 | All Opus audio is coded at 48 kHz, and should also be decoded at 48 | |
68 | kHz for playback (unless the target hardware does not support this | |
69 | sampling rate). However, this field may be used to resample the audio | |
70 | back to the original sampling rate, for example, when saving the | |
71 | output to a file. | |
72 | ||
73 | =item $head->B<output_gain> | |
74 | ||
75 | The gain to apply to the decoded output, in dB, as a Q8 value in the | |
76 | range -32768...32767. | |
77 | ||
78 | The libopusfile API will automatically apply this gain to the decoded | |
79 | output before returning it, scaling it by | |
80 | pow(10,output_gain/(20.0*256)). | |
81 | ||
82 | =item $head->B<mapping_family> | |
83 | ||
84 | The channel mapping family, in the range 0...255. | |
85 | ||
86 | Channel mapping family 0 covers mono or stereo in a single stream. | |
87 | Channel mapping family 1 covers 1 to 8 channels in one or more | |
88 | streams, using the Vorbis speaker assignments. Channel mapping family | |
89 | 255 covers 1 to 255 channels in one or more streams, but without any | |
90 | defined speaker assignment. | |
91 | ||
92 | =item $head->B<stream_count> | |
93 | ||
94 | The number of Opus streams in each Ogg packet, in the range 1...255. | |
95 | ||
96 | =item $head->B<coupled_count> | |
97 | ||
98 | The number of coupled Opus streams in each Ogg packet, in the range | |
99 | 0...127. | |
100 | ||
101 | This must satisfy 0 <= coupled_count <= stream_count and coupled_count | |
102 | + stream_count <= 255. The coupled streams appear first, before all | |
103 | uncoupled streams, in an Ogg Opus packet. | |
104 | ||
105 | =item $head->B<mapping>(I<$k>) | |
106 | ||
107 | The mapping from coded stream channels to output channels. | |
108 | ||
109 | Let C<< index = mapping[k] >> be the value for channel I<$k>. If | |
110 | C<< index < 2 * coupled_count >>, then it refers to the left channel | |
111 | from stream C<< (index/2) >> if even, and the right channel from | |
112 | stream C<< (index/2) >> if odd. Otherwise, it refers to the output of | |
113 | the uncoupled stream C<< (index-coupled_count) >>. | |
114 | ||
115 | Dies if I<$k> is more than OPUS_CHANNEL_COUNT_MAX. | |
116 | ||
117 | =back | |
118 | ||
119 | =head1 SEE ALSO | |
120 | ||
121 | L<Audio::Opusfile>, | |
122 | L<http://opus-codec.org/>, | |
123 | L<http://opus-codec.org/docs/opusfile_api-0.7/structOpusHead.html> | |
124 | ||
125 | =head1 AUTHOR | |
126 | ||
127 | Marius Gavrilescu, E<lt>marius@ieval.roE<gt> | |
128 | ||
129 | =head1 COPYRIGHT AND LICENSE | |
130 | ||
36bdc941 | 131 | Copyright (C) 2016-2017 by Marius Gavrilescu |
b9bd6a0d MG |
132 | |
133 | This library is free software; you can redistribute it and/or modify | |
134 | it under the same terms as Perl itself, either Perl version 5.24.0 or, | |
135 | at your option, any later version of Perl 5 you may have available. | |
136 | ||
137 | ||
138 | =cut |