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 gnu.java.lang.CPStringBuilder; 042 043 import java.util.Collections; 044 import java.util.HashMap; 045 import java.util.Map; 046 047 /** 048 * This class describes an audio format, including its encoding, 049 * the number of channels, its frame rate, etc. 050 * @since 1.3 051 */ 052 public class AudioFormat 053 { 054 /** 055 * This describes a given audio format encoding. 056 * @since 1.3 057 */ 058 public static class Encoding 059 { 060 /** The ALAW encoding. */ 061 public static final Encoding ALAW = new Encoding("alaw"); 062 063 /** The signed PCM encoding. */ 064 public static final Encoding PCM_SIGNED = new Encoding("pcm_signed"); 065 066 /** The unsigned PCM encoding. */ 067 public static final Encoding PCM_UNSIGNED = new Encoding("pcm_unsigned"); 068 069 /** The ULAW encoding. */ 070 public static final Encoding ULAW = new Encoding("ulaw"); 071 072 private String name; 073 074 /** 075 * Create a new encoding descriptor, given its name. 076 * @param name the name 077 */ 078 public Encoding(String name) 079 { 080 this.name = name; 081 } 082 083 public final boolean equals(Object o) 084 { 085 return super.equals(o); 086 } 087 088 public final int hashCode() 089 { 090 return super.hashCode(); 091 } 092 093 /** 094 * Return the name of this encoding. 095 */ 096 public final String toString() 097 { 098 return name; 099 } 100 } 101 102 /** 103 * True if the audio data is stored big-endian. 104 */ 105 protected boolean bigEndian; 106 107 /** 108 * The number of channels of data in this format. 109 */ 110 protected int channels; 111 112 /** 113 * The encoding of this format. 114 */ 115 protected Encoding encoding; 116 117 /** 118 * The frame rate of this format. This is the number of frames 119 * per second. 120 */ 121 protected float frameRate; 122 123 /** 124 * The number of bytes per frame in this format. 125 */ 126 protected int frameSize; 127 128 /** 129 * The number of samples per second. 130 */ 131 protected float sampleRate; 132 133 /** 134 * The number of bits in each sample. 135 */ 136 protected int sampleSizeInBits; 137 138 private Map<String, Object> properties; 139 140 /** 141 * Create a new audio format, given various attributes of it. 142 * The properties map for this format will be empty. 143 * 144 * @param encoding the encoding for this format 145 * @param sampleRate the sample rate 146 * @param sampleSizeInBits the sample size, in bits 147 * @param channels the number of channels 148 * @param frameSize the frame size, in bytes 149 * @param frameRate the frame rate, in frames per second 150 * @param bigEndian true if the data is stored big-endian 151 */ 152 public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits, 153 int channels, int frameSize, float frameRate, 154 boolean bigEndian) 155 { 156 this.encoding = encoding; 157 this.sampleRate = sampleRate; 158 this.sampleSizeInBits = sampleSizeInBits; 159 this.channels = channels; 160 this.frameSize = frameSize; 161 this.frameRate = frameRate; 162 this.bigEndian = bigEndian; 163 this.properties = Collections.<String, Object> emptyMap(); 164 } 165 166 /** 167 * Create a new audio format, given various attributes of it. 168 * The properties map is copied by this constructor, so changes 169 * to the argument Map will not affect the new object. 170 * 171 * @param encoding the encoding for this format 172 * @param sampleRate the sample rate 173 * @param sampleSizeInBits the sample size, in bits 174 * @param channels the number of channels 175 * @param frameSize the frame size, in bytes 176 * @param frameRate the frame rate, in frames per second 177 * @param bigEndian true if the data is stored big-endian 178 * @param properties a map describing properties of this format 179 */ 180 public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits, 181 int channels, int frameSize, float frameRate, 182 boolean bigEndian, Map<String, Object> properties) 183 { 184 this.encoding = encoding; 185 this.sampleRate = sampleRate; 186 this.sampleSizeInBits = sampleSizeInBits; 187 this.channels = channels; 188 this.frameSize = frameSize; 189 this.frameRate = frameRate; 190 this.bigEndian = bigEndian; 191 this.properties = Collections.unmodifiableMap(new HashMap<String, Object>(properties)); 192 } 193 194 /** 195 * Create a new PCM-based audio format, given various attributes of it. 196 * The encoding will either be Encoding#PCM_SIGNED or Encoding#PCM_UNSIGNED. 197 * The frame size for this format will be derived from the sample size in 198 * bits and the number of channels, unless one of those is 199 * AudioSystem#NOT_SPECIFIED. The frame rate will be the same as the sample 200 * rate, and the properties map will be empty. 201 * 202 * @param sampleRate the sample rate 203 * @param sampleSizeInBits the sample size, in bits 204 * @param channels the number of channels 205 * @param signed true if this is a signed encoding 206 * @param bigEndian true if the data is stored big-endian 207 */ 208 public AudioFormat(float sampleRate, int sampleSizeInBits, 209 int channels, boolean signed, boolean bigEndian) 210 { 211 this.encoding = signed ? Encoding.PCM_SIGNED : Encoding.PCM_UNSIGNED; 212 this.sampleRate = sampleRate; 213 this.sampleSizeInBits = sampleSizeInBits; 214 this.channels = channels; 215 // It isn't clear whether channels can be NOT_SPECIFIED. 216 if (sampleSizeInBits == AudioSystem.NOT_SPECIFIED 217 || channels == AudioSystem.NOT_SPECIFIED) 218 this.frameSize = AudioSystem.NOT_SPECIFIED; 219 else 220 this.frameSize = (sampleSizeInBits + 7) / 8 * channels; 221 this.frameRate = sampleRate; 222 this.bigEndian = bigEndian; 223 this.properties = Collections.<String, Object> emptyMap(); 224 } 225 226 /** 227 * Return the number of channels in this format. 228 */ 229 public int getChannels() 230 { 231 return channels; 232 } 233 234 /** 235 * Return the encoding of this format. 236 */ 237 public Encoding getEncoding() 238 { 239 return encoding; 240 } 241 242 /** 243 * Return the frame rate of this format. 244 */ 245 public float getFrameRate() 246 { 247 return frameRate; 248 } 249 250 /** 251 * Return the frame size of this format. 252 */ 253 public int getFrameSize() 254 { 255 return frameSize; 256 } 257 258 /** 259 * Given a key, return a property associated with this format; 260 * or null if this property is not set. 261 * @param key the name of the property 262 * @return the value of the property, or null if the property is not set 263 */ 264 public Object getProperty(String key) 265 { 266 return properties.get(key); 267 } 268 269 /** 270 * Return the sample rate of this format. 271 */ 272 public float getSampleRate() 273 { 274 return sampleRate; 275 } 276 277 /** 278 * Return the sample size of this format, in bits. 279 */ 280 public int getSampleSizeInBits() 281 { 282 return sampleSizeInBits; 283 } 284 285 /** 286 * Return true if this format is big endian, false otherwise. 287 * This only matters for formats whose sample size is greater than 288 * one byte. 289 */ 290 public boolean isBigEndian() 291 { 292 return bigEndian; 293 } 294 295 /** 296 * Return true if this audio format matches another. 297 * @param fmt the format to match against 298 * @return true if they match, false otherwise 299 */ 300 public boolean matches(AudioFormat fmt) 301 { 302 if (! encoding.equals(fmt.encoding) 303 || channels != fmt.channels 304 || sampleSizeInBits != fmt.sampleSizeInBits 305 || frameSize != fmt.frameSize) 306 return false; 307 if (sampleRate != AudioSystem.NOT_SPECIFIED 308 && fmt.sampleRate != AudioSystem.NOT_SPECIFIED 309 && sampleRate != fmt.sampleRate) 310 return false; 311 if (frameRate != AudioSystem.NOT_SPECIFIED 312 && fmt.frameRate != AudioSystem.NOT_SPECIFIED 313 && frameRate != fmt.frameRate) 314 return false; 315 if (sampleSizeInBits > 8) 316 return bigEndian == fmt.bigEndian; 317 return true; 318 } 319 320 /** 321 * Return a read-only Map holding the properties associated with 322 * this format. 323 */ 324 public Map<String, Object> properties() 325 { 326 return properties; 327 } 328 329 /** 330 * Return a description of this format. 331 */ 332 public String toString() 333 { 334 CPStringBuilder result = new CPStringBuilder(); 335 336 // usually at least encoding should be somewhat specified 337 result.append(encoding); 338 339 if (sampleRate != AudioSystem.NOT_SPECIFIED) 340 { 341 result.append(" "); 342 result.append(sampleRate); 343 result.append(" Hz"); 344 } 345 346 if (sampleSizeInBits != AudioSystem.NOT_SPECIFIED) 347 { 348 result.append(" "); 349 result.append(sampleSizeInBits); 350 result.append(" bits"); 351 } 352 353 if (channels != AudioSystem.NOT_SPECIFIED) 354 { 355 result.append(" "); 356 result.append(channels); 357 result.append(" channel"); 358 if (channels > 1) result.append("s"); 359 } 360 361 if (sampleSizeInBits > 8) 362 result.append(bigEndian ? " big endian" : " little endian"); 363 364 return result.toString(); 365 } 366 }