001 /* An audio format 002 Copyright (C) 2005 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package javax.sound.sampled; 040 041 import java.util.Collections; 042 import java.util.HashMap; 043 import java.util.Map; 044 045 /** 046 * This class describes an audio format, including its encoding, 047 * the number of channels, its frame rate, etc. 048 * @since 1.3 049 */ 050 public class AudioFormat 051 { 052 /** 053 * This describes a given audio format encoding. 054 * @since 1.3 055 */ 056 public static class Encoding 057 { 058 /** The ALAW encoding. */ 059 public static final Encoding ALAW = new Encoding("alaw"); 060 061 /** The signed PCM encoding. */ 062 public static final Encoding PCM_SIGNED = new Encoding("pcm_signed"); 063 064 /** The unsigned PCM encoding. */ 065 public static final Encoding PCM_UNSIGNED = new Encoding("pcm_unsigned"); 066 067 /** The ULAW encoding. */ 068 public static final Encoding ULAW = new Encoding("ulaw"); 069 070 private String name; 071 072 /** 073 * Create a new encoding descriptor, given its name. 074 * @param name the name 075 */ 076 public Encoding(String name) 077 { 078 this.name = name; 079 } 080 081 public final boolean equals(Object o) 082 { 083 return super.equals(o); 084 } 085 086 public final int hashCode() 087 { 088 return super.hashCode(); 089 } 090 091 /** 092 * Return the name of this encoding. 093 */ 094 public final String toString() 095 { 096 return name; 097 } 098 } 099 100 /** 101 * True if the audio data is stored big-endian. 102 */ 103 protected boolean bigEndian; 104 105 /** 106 * The number of channels of data in this format. 107 */ 108 protected int channels; 109 110 /** 111 * The encoding of this format. 112 */ 113 protected Encoding encoding; 114 115 /** 116 * The frame rate of this format. This is the number of frames 117 * per second. 118 */ 119 protected float frameRate; 120 121 /** 122 * The number of bytes per frame in this format. 123 */ 124 protected int frameSize; 125 126 /** 127 * The number of samples per second. 128 */ 129 protected float sampleRate; 130 131 /** 132 * The number of bits in each sample. 133 */ 134 protected int sampleSizeInBits; 135 136 private Map<String, Object> properties; 137 138 /** 139 * Create a new audio format, given various attributes of it. 140 * The properties map for this format will be empty. 141 * 142 * @param encoding the encoding for this format 143 * @param sampleRate the sample rate 144 * @param sampleSizeInBits the sample size, in bits 145 * @param channels the number of channels 146 * @param frameSize the frame size, in bytes 147 * @param frameRate the frame rate, in frames per second 148 * @param bigEndian true if the data is stored big-endian 149 */ 150 public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits, 151 int channels, int frameSize, float frameRate, 152 boolean bigEndian) 153 { 154 this.encoding = encoding; 155 this.sampleRate = sampleRate; 156 this.sampleSizeInBits = sampleSizeInBits; 157 this.channels = channels; 158 this.frameSize = frameSize; 159 this.frameRate = frameRate; 160 this.bigEndian = bigEndian; 161 this.properties = Collections.<String, Object> emptyMap(); 162 } 163 164 /** 165 * Create a new audio format, given various attributes of it. 166 * The properties map is copied by this constructor, so changes 167 * to the argument Map will not affect the new object. 168 * 169 * @param encoding the encoding for this format 170 * @param sampleRate the sample rate 171 * @param sampleSizeInBits the sample size, in bits 172 * @param channels the number of channels 173 * @param frameSize the frame size, in bytes 174 * @param frameRate the frame rate, in frames per second 175 * @param bigEndian true if the data is stored big-endian 176 * @param properties a map describing properties of this format 177 */ 178 public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits, 179 int channels, int frameSize, float frameRate, 180 boolean bigEndian, Map<String, Object> properties) 181 { 182 this.encoding = encoding; 183 this.sampleRate = sampleRate; 184 this.sampleSizeInBits = sampleSizeInBits; 185 this.channels = channels; 186 this.frameSize = frameSize; 187 this.frameRate = frameRate; 188 this.bigEndian = bigEndian; 189 this.properties = Collections.unmodifiableMap(new HashMap<String, Object>(properties)); 190 } 191 192 /** 193 * Create a new PCM-based audio format, given various attributes of it. 194 * The encoding will either be Encoding#PCM_SIGNED or Encoding#PCM_UNSIGNED. 195 * The frame size for this format will be derived from the sample size in 196 * bits and the number of channels, unless one of those is 197 * AudioSystem#NOT_SPECIFIED. The frame rate will be the same as the sample 198 * rate, and the properties map will be empty. 199 * 200 * @param sampleRate the sample rate 201 * @param sampleSizeInBits the sample size, in bits 202 * @param channels the number of channels 203 * @param signed true if this is a signed encoding 204 * @param bigEndian true if the data is stored big-endian 205 */ 206 public AudioFormat(float sampleRate, int sampleSizeInBits, 207 int channels, boolean signed, boolean bigEndian) 208 { 209 this.encoding = signed ? Encoding.PCM_SIGNED : Encoding.PCM_UNSIGNED; 210 this.sampleRate = sampleRate; 211 this.sampleSizeInBits = sampleSizeInBits; 212 this.channels = channels; 213 // It isn't clear whether channels can be NOT_SPECIFIED. 214 if (sampleSizeInBits == AudioSystem.NOT_SPECIFIED 215 || channels == AudioSystem.NOT_SPECIFIED) 216 this.frameSize = AudioSystem.NOT_SPECIFIED; 217 else 218 this.frameSize = (sampleSizeInBits + 7) / 8 * channels; 219 this.frameRate = sampleRate; 220 this.bigEndian = bigEndian; 221 this.properties = Collections.<String, Object> emptyMap(); 222 } 223 224 /** 225 * Return the number of channels in this format. 226 */ 227 public int getChannels() 228 { 229 return channels; 230 } 231 232 /** 233 * Return the encoding of this format. 234 */ 235 public Encoding getEncoding() 236 { 237 return encoding; 238 } 239 240 /** 241 * Return the frame rate of this format. 242 */ 243 public float getFrameRate() 244 { 245 return frameRate; 246 } 247 248 /** 249 * Return the frame size of this format. 250 */ 251 public int getFrameSize() 252 { 253 return frameSize; 254 } 255 256 /** 257 * Given a key, return a property associated with this format; 258 * or null if this property is not set. 259 * @param key the name of the property 260 * @return the value of the property, or null if the property is not set 261 */ 262 public Object getProperty(String key) 263 { 264 return properties.get(key); 265 } 266 267 /** 268 * Return the sample rate of this format. 269 */ 270 public float getSampleRate() 271 { 272 return sampleRate; 273 } 274 275 /** 276 * Return the sample size of this format, in bits. 277 */ 278 public int getSampleSizeInBits() 279 { 280 return sampleSizeInBits; 281 } 282 283 /** 284 * Return true if this format is big endian, false otherwise. 285 * This only matters for formats whose sample size is greater than 286 * one byte. 287 */ 288 public boolean isBigEndian() 289 { 290 return bigEndian; 291 } 292 293 /** 294 * Return true if this audio format matches another. 295 * @param fmt the format to match against 296 * @return true if they match, false otherwise 297 */ 298 public boolean matches(AudioFormat fmt) 299 { 300 if (! encoding.equals(fmt.encoding) 301 || channels != fmt.channels 302 || sampleSizeInBits != fmt.sampleSizeInBits 303 || frameSize != fmt.frameSize) 304 return false; 305 if (sampleRate != AudioSystem.NOT_SPECIFIED 306 && fmt.sampleRate != AudioSystem.NOT_SPECIFIED 307 && sampleRate != fmt.sampleRate) 308 return false; 309 if (frameRate != AudioSystem.NOT_SPECIFIED 310 && fmt.frameRate != AudioSystem.NOT_SPECIFIED 311 && frameRate != fmt.frameRate) 312 return false; 313 if (sampleSizeInBits > 8) 314 return bigEndian == fmt.bigEndian; 315 return true; 316 } 317 318 /** 319 * Return a read-only Map holding the properties associated with 320 * this format. 321 */ 322 public Map<String, Object> properties() 323 { 324 return properties; 325 } 326 327 /** 328 * Return a description of this format. 329 */ 330 public String toString() 331 { 332 StringBuffer result = new StringBuffer(); 333 334 // usually at least encoding should be somewhat specified 335 result.append(encoding); 336 337 if (sampleRate != AudioSystem.NOT_SPECIFIED) 338 { 339 result.append(" "); 340 result.append(sampleRate); 341 result.append(" Hz"); 342 } 343 344 if (sampleSizeInBits != AudioSystem.NOT_SPECIFIED) 345 { 346 result.append(" "); 347 result.append(sampleSizeInBits); 348 result.append(" bits"); 349 } 350 351 if (channels != AudioSystem.NOT_SPECIFIED) 352 { 353 result.append(" "); 354 result.append(channels); 355 result.append(" channel"); 356 if (channels > 1) result.append("s"); 357 } 358 359 if (sampleSizeInBits > 8) 360 result.append(bigEndian ? " big endian" : " little endian"); 361 362 return result.toString(); 363 } 364 }