1/***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
5
6/***************************************************************************
7 * This library is free software; you can redistribute it and/or modify *
8 * it under the terms of the GNU Lesser General Public License version *
9 * 2.1 as published by the Free Software Foundation. *
10 * *
11 * This library is distributed in the hope that it will be useful, but *
12 * WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
15 * *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the Free Software *
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA *
19 * 02110-1301 USA *
20 * *
21 * Alternatively, this file is available under the Mozilla Public *
22 * License Version 1.1. You may obtain a copy of the License at *
23 * http://www.mozilla.org/MPL/ *
24 ***************************************************************************/
25
26#ifndef TAGLIB_MPEGHEADER_H
27#define TAGLIB_MPEGHEADER_H
28
29#include "taglib_export.h"
30
31namespace TagLib {
32
33 class ByteVector;
34 class File;
35
36 namespace MPEG {
37
38 //! An implementation of MP3 frame headers
39
40 /*!
41 * This is an implementation of MPEG Layer III headers. The API follows more
42 * or less the binary format of these headers. I've used
43 * <a href="http://www.mp3-tech.org/programmer/frame_header.html">this</a>
44 * document as a reference.
45 */
46
47 class TAGLIB_EXPORT Header
48 {
49 public:
50 /*!
51 * Parses an MPEG header based on \a data.
52 *
53 * \deprecated
54 */
55 Header(const ByteVector &data);
56
57 /*!
58 * Parses an MPEG header based on \a file and \a offset.
59 *
60 * \note If \a checkLength is true, this requires the next MPEG frame to
61 * check if the frame length is parsed and calculated correctly. So it's
62 * suitable for seeking for the first valid frame.
63 */
64 Header(File *file, long offset, bool checkLength = true);
65
66 /*!
67 * Does a shallow copy of \a h.
68 */
69 Header(const Header &h);
70
71 /*!
72 * Destroys this Header instance.
73 */
74 virtual ~Header();
75
76 /*!
77 * Returns true if the frame is at least an appropriate size and has
78 * legal values.
79 */
80 bool isValid() const;
81
82 /*!
83 * The MPEG Version.
84 */
85 enum Version {
86 //! MPEG Version 1
87 Version1 = 0,
88 //! MPEG Version 2
89 Version2 = 1,
90 //! MPEG Version 2.5
91 Version2_5 = 2
92 };
93
94 /*!
95 * Returns the MPEG Version of the header.
96 */
97 Version version() const;
98
99 /*!
100 * Returns the layer version. This will be between the values 1-3.
101 */
102 int layer() const;
103
104 /*!
105 * Returns true if the MPEG protection bit is enabled.
106 */
107 bool protectionEnabled() const;
108
109 /*!
110 * Returns the bitrate encoded in the header.
111 */
112 int bitrate() const;
113
114 /*!
115 * Returns the sample rate in Hz.
116 */
117 int sampleRate() const;
118
119 /*!
120 * Returns true if the frame is padded.
121 */
122 bool isPadded() const;
123
124 /*!
125 * There are a few combinations or one or two channel audio that are
126 * possible:
127 */
128 enum ChannelMode {
129 //! Stereo
130 Stereo = 0,
131 //! Stereo
132 JointStereo = 1,
133 //! Dual Mono
134 DualChannel = 2,
135 //! Mono
136 SingleChannel = 3
137 };
138
139 /*!
140 * Returns the channel mode for this frame.
141 */
142 ChannelMode channelMode() const;
143
144 /*!
145 * Returns true if the copyrighted bit is set.
146 */
147 bool isCopyrighted() const;
148
149 /*!
150 * Returns true if the "original" bit is set.
151 */
152 bool isOriginal() const;
153
154 /*!
155 * Returns the frame length in bytes.
156 */
157 int frameLength() const;
158
159 /*!
160 * Returns the number of frames per sample.
161 */
162 int samplesPerFrame() const;
163
164 /*!
165 * Makes a shallow copy of the header.
166 */
167 Header &operator=(const Header &h);
168
169 private:
170 void parse(File *file, long offset, bool checkLength);
171
172 class HeaderPrivate;
173 HeaderPrivate *d;
174 };
175 }
176}
177
178#endif
179