lib/Audio/Opusfile/Head.pm

   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
   8 our $VERSION = '0.004';
   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
 131 Copyright (C) 2016 by Marius Gavrilescu
 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