GlueGen v2.6.0-rc-20250712
GlueGen, Native Binding Generator for Java™ (public API).
AudioFormat.java
Go to the documentation of this file.
1/**
2 * Copyright 2013-2023 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28package com.jogamp.common.av;
29
30/**
31 * Specifies the linear audio PCM format.
32 */
33public class AudioFormat {
34 /**
35 * @param sampleRate sample rate in Hz (1/s), e.g. 44100 Hz
36 * @param sampleSize sample size in bits, e.g. 16 bits
37 * @param channelCount number of channels, e.g. 2 channels for stereo
38 * @param signed true if signed PCM values, false for unsigned values
39 * @param fixedP true for fixed point values, false for unsigned floating point values with a sampleSize of 32 (float) or 64 (double)
40 * @param planar true for planar data package (each channel in own data buffer), false for packed data channels interleaved in one buffer.
41 * @param littleEndian true for little-endian byte order, false for big endian byte order
42 */
43 public AudioFormat(final int sampleRate, final int sampleSize, final int channelCount, final boolean signed, final boolean fixedP, final boolean planar, final boolean littleEndian) {
44 this.sampleRate = sampleRate;
45 this.sampleSize = sampleSize;
46 this.channelCount = channelCount;
47 this.signed = signed;
48 this.fixedP = fixedP;
49 this.planar = planar;
50 this.littleEndian = littleEndian;
51 if( !fixedP ) {
52 if( sampleSize != 32 && sampleSize != 64 ) {
53 throw new IllegalArgumentException("Floating point: sampleSize "+sampleSize+" bits");
54 }
55 if( !signed ) {
56 throw new IllegalArgumentException("Floating point: unsigned");
57 }
58 }
59 }
60
61 /** Sample rate in Hz (1/s, e.g. 44100 Hz. */
62 public final int sampleRate;
63 /** Sample size in bits, e.g. 16 bits. */
64 public final int sampleSize;
65 /** Number of channels, e.g. 2 channels for stereo. */
66 public final int channelCount;
67 /** Signed PCM values if true, otherwise unsigned values. */
68 public final boolean signed;
69 /** Fixed or floating point values. Floating point 'float' has {@link #sampleSize} 32, 'double' has {@link #sampleSize} 64. */
70 public final boolean fixedP;
71 /** Planar or packed samples. If planar, each channel has their own data buffer. If packed, channel data is interleaved in one buffer. */
72 public final boolean planar;
73 /** Little-endian byte order if true, otherwise big endian byte order. */
74 public final boolean littleEndian;
75
76
77 //
78 // Time <-> Bytes
79 //
80
81 /**
82 * Returns the byte size of the given duration in seconds
83 * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}.
84 * <pre>
85 * final float bytesPerSample = sampleSize/8;
86 * return Math.round( duration * channelCount * bytesPerSample * sampleRate );
87 * </pre>
88 * <p>
89 * Time -> Byte Count
90 * </p>
91 * @param duration duration in seconds
92 */
93 public final int getDurationsByteSize(final float duration) {
94 final float bytesPerSample = sampleSize >>> 3; // /8
95 return Math.round( duration * channelCount * bytesPerSample * sampleRate );
96 }
97
98 /**
99 * Returns the duration in seconds of the given byte count
100 * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}.
101 * <pre>
102 * final float bytesPerSample = sampleSize/8;
103 * return byteCount / ( channelCount * bytesPerSample * sampleRate )
104 * </pre>
105 * <p>
106 * Byte Count -> Time
107 * </p>
108 * @param byteCount size in bytes
109 */
110 public final float getBytesDuration(final int byteCount) {
111 final float bytesPerSample = sampleSize >>> 3; // /8
112 return byteCount / ( channelCount * bytesPerSample * sampleRate );
113 }
114
115 /**
116 * Returns the duration in seconds of the given sample count per frame and channel
117 * according to the {@link #sampleRate}, i.e.
118 * <pre>
119 * (float)sampleCount / sampleRate
120 * </pre>
121 * <p>
122 * Sample Count -> Time
123 * </p>
124 * @param sampleCount sample count per frame and channel
125 */
126 public final float getSamplesDuration(final int sampleCount) {
127 return (float)sampleCount / sampleRate;
128 }
129
130 /**
131 * Returns the rounded frame count of the given duration and frame duration, both in seconds.
132 * <pre>
133 * Math.max(1, Math.round( duration / frameDuration ))
134 * </pre>
135 * <p>
136 * Note: <code>frameDuration</code> can be derived by <i>sample count per frame and channel</i>
137 * via {@link #getSamplesDuration(int)} or by <i>byte count</i> via {@link #getBytesDuration(int)}.
138 * </p>
139 * <p>
140 * Frame Time -> Frame Count
141 * </p>
142 * @param duration duration in seconds
143 * @param frameDuration duration per frame in seconds, i.e. 1/frame_rate
144 * @see #getSamplesDuration(int)
145 * @see #getBytesDuration(int)
146 */
147 public final int getFrameCount(final float duration, final float frameDuration) {
148 return Math.max(1, Math.round( duration / frameDuration ));
149 }
150
151 /**
152 * Returns the byte size of given sample count
153 * according to the {@link #sampleSize}, i.e.:
154 * <pre>
155 * sampleCount * ( sampleSize / 8 )
156 * </pre>
157 * <p>
158 * Note: To retrieve the byte size for all channels,
159 * you need to pre-multiply <code>sampleCount</code> with {@link #channelCount}.
160 * </p>
161 * <p>
162 * Sample Count -> Byte Count
163 * </p>
164 * @param sampleCount sample count
165 */
166 public final int getSamplesByteCount(final int sampleCount) {
167 return sampleCount * ( sampleSize >>> 3 );
168 }
169
170 /**
171 * Returns the sample count of given byte count
172 * according to the {@link #sampleSize}, i.e.:
173 * <pre>
174 * ( byteCount * 8 ) / sampleSize
175 * </pre>
176 * <p>
177 * Note: If <code>byteCount</code> covers all channels and you request the sample size per channel,
178 * you need to divide the result by <code>sampleCount</code> by {@link #channelCount}.
179 * </p>
180 * <p>
181 * Byte Count -> Sample Count
182 * </p>
183 * @param byteCount number of bytes
184 */
185 public final int getBytesSampleCount(final int byteCount) {
186 return ( byteCount << 3 ) / sampleSize;
187 }
188
189 @Override
190 public String toString() {
191 return "AudioFormat[sampleRate "+sampleRate+", sampleSize "+sampleSize+", channelCount "+channelCount+
192 ", signed "+signed+", fixedP "+fixedP+", "+(planar?"planar":"packed")+", "+(littleEndian?"little":"big")+"-endian]"; }
193}
Specifies the linear audio PCM format.
final boolean fixedP
Fixed or floating point values.
final int getFrameCount(final float duration, final float frameDuration)
Returns the rounded frame count of the given duration and frame duration, both in seconds.
final int getSamplesByteCount(final int sampleCount)
Returns the byte size of given sample count according to the sampleSize, i.e.
final float getBytesDuration(final int byteCount)
Returns the duration in seconds of the given byte count according to sampleSize, channelCount and sam...
AudioFormat(final int sampleRate, final int sampleSize, final int channelCount, final boolean signed, final boolean fixedP, final boolean planar, final boolean littleEndian)
final float getSamplesDuration(final int sampleCount)
Returns the duration in seconds of the given sample count per frame and channel according to the samp...
final boolean littleEndian
Little-endian byte order if true, otherwise big endian byte order.
final int channelCount
Number of channels, e.g.
final boolean planar
Planar or packed samples.
final int sampleRate
Sample rate in Hz (1/s, e.g.
final boolean signed
Signed PCM values if true, otherwise unsigned values.
final int getDurationsByteSize(final float duration)
Returns the byte size of the given duration in seconds according to sampleSize, channelCount and samp...
final int sampleSize
Sample size in bits, e.g.
final int getBytesSampleCount(final int byteCount)
Returns the sample count of given byte count according to the sampleSize, i.e.