1 /* 2 * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sound.sampled; 27 28 import java.util.Collections; 29 import java.util.HashMap; 30 import java.util.Map; 31 import java.util.Objects; 32 33 /** 34 * An instance of the {@code AudioFileFormat} class describes an audio file, 35 * including the file type, the file's length in bytes, the length in sample 36 * frames of the audio data contained in the file, and the format of the audio 37 * data. 38 * <p> 39 * The {@link AudioSystem} class includes methods for determining the format of 40 * an audio file, obtaining an audio input stream from an audio file, and 41 * writing an audio file from an audio input stream. 42 * <p> 43 * An {@code AudioFileFormat} object can include a set of properties. A property 44 * is a pair of key and value: the key is of type {@code String}, the associated 45 * property value is an arbitrary object. Properties specify additional 46 * informational meta data (like a author, copyright, or file duration). 47 * Properties are optional information, and file reader and file writer 48 * implementations are not required to provide or recognize properties. 49 * <p> 50 * The following table lists some common properties that should be used in 51 * implementations: 52 * 53 * <table class="striped"> 54 * <caption>Audio File Format Properties</caption> 55 * <thead> 56 * <tr> 57 * <th scope="col">Property key 58 * <th scope="col">Value type 59 * <th scope="col">Description 60 * </thead> 61 * <tbody> 62 * <tr> 63 * <th scope="row">"duration" 64 * <td>{@link Long Long} 65 * <td>playback duration of the file in microseconds 66 * <tr> 67 * <th scope="row">"author" 68 * <td>{@link String String} 69 * <td>name of the author of this file 70 * <tr> 71 * <th scope="row">"title" 72 * <td>{@link String String} 73 * <td>title of this file 74 * <tr> 75 * <th scope="row">"copyright" 76 * <td>{@link String String} 77 * <td>copyright message 78 * <tr> 79 * <th scope="row">"date" 80 * <td>{@link java.util.Date Date} 81 * <td>date of the recording or release 82 * <tr> 83 * <th scope="row">"comment" 84 * <td>{@link String String} 85 * <td>an arbitrary text 86 * </tbody> 87 * </table> 88 * 89 * @author David Rivas 90 * @author Kara Kytle 91 * @author Florian Bomers 92 * @see AudioInputStream 93 * @since 1.3 94 */ 95 public class AudioFileFormat { 96 97 /** 98 * File type. 99 */ 100 private final Type type; 101 102 /** 103 * File length in bytes. 104 */ 105 private final int byteLength; 106 107 /** 108 * Format of the audio data contained in the file. 109 */ 110 private final AudioFormat format; 111 112 /** 113 * Audio data length in sample frames. 114 */ 115 private final int frameLength; 116 117 /** 118 * The set of properties. 119 */ 120 private HashMap<String, Object> properties; 121 122 /** 123 * Constructs an audio file format object. This protected constructor is 124 * intended for use by providers of file-reading services when returning 125 * information about an audio file or about supported audio file formats. 126 * 127 * @param type the type of the audio file 128 * @param byteLength the length of the file in bytes, or 129 * {@code AudioSystem.NOT_SPECIFIED} 130 * @param format the format of the audio data contained in the file 131 * @param frameLength the audio data length in sample frames, or 132 * {@code AudioSystem.NOT_SPECIFIED} 133 * @see #getType 134 */ 135 protected AudioFileFormat(Type type, int byteLength, AudioFormat format, int frameLength) { 136 137 this.type = type; 138 this.byteLength = byteLength; 139 this.format = format; 140 this.frameLength = frameLength; 141 this.properties = null; 142 } 143 144 /** 145 * Constructs an audio file format object. This public constructor may be 146 * used by applications to describe the properties of a requested audio 147 * file. 148 * 149 * @param type the type of the audio file 150 * @param format the format of the audio data contained in the file 151 * @param frameLength the audio data length in sample frames, or 152 * {@code AudioSystem.NOT_SPECIFIED} 153 */ 154 public AudioFileFormat(Type type, AudioFormat format, int frameLength) { 155 156 157 this(type,AudioSystem.NOT_SPECIFIED,format,frameLength); 158 } 159 160 /** 161 * Construct an audio file format object with a set of defined properties. 162 * This public constructor may be used by applications to describe the 163 * properties of a requested audio file. The properties map will be copied 164 * to prevent any changes to it. 165 * 166 * @param type the type of the audio file 167 * @param format the format of the audio data contained in the file 168 * @param frameLength the audio data length in sample frames, or 169 * {@code AudioSystem.NOT_SPECIFIED} 170 * @param properties a {@code Map<String, Object>} object with properties 171 * @since 1.5 172 */ 173 public AudioFileFormat(Type type, AudioFormat format, 174 int frameLength, Map<String, Object> properties) { 175 this(type,AudioSystem.NOT_SPECIFIED,format,frameLength); 176 this.properties = new HashMap<>(properties); 177 } 178 179 /** 180 * Obtains the audio file type, such as {@code WAVE} or {@code AU}. 181 * 182 * @return the audio file type 183 * @see Type#WAVE 184 * @see Type#AU 185 * @see Type#AIFF 186 * @see Type#AIFC 187 * @see Type#SND 188 */ 189 public Type getType() { 190 return type; 191 } 192 193 /** 194 * Obtains the size in bytes of the entire audio file (not just its audio 195 * data). 196 * 197 * @return the audio file length in bytes 198 * @see AudioSystem#NOT_SPECIFIED 199 */ 200 public int getByteLength() { 201 return byteLength; 202 } 203 204 /** 205 * Obtains the format of the audio data contained in the audio file. 206 * 207 * @return the audio data format 208 */ 209 public AudioFormat getFormat() { 210 return format; 211 } 212 213 /** 214 * Obtains the length of the audio data contained in the file, expressed in 215 * sample frames. 216 * 217 * @return the number of sample frames of audio data in the file 218 * @see AudioSystem#NOT_SPECIFIED 219 */ 220 public int getFrameLength() { 221 return frameLength; 222 } 223 224 /** 225 * Obtain an unmodifiable map of properties. The concept of properties is 226 * further explained in the {@link AudioFileFormat class description}. 227 * 228 * @return a {@code Map<String, Object>} object containing all properties. 229 * If no properties are recognized, an empty map is returned. 230 * @see #getProperty(String) 231 * @since 1.5 232 */ 233 @SuppressWarnings("unchecked") // Cast of result of clone 234 public Map<String, Object> properties() { 235 Map<String,Object> ret; 236 if (properties == null) { 237 ret = new HashMap<>(0); 238 } else { 239 ret = (Map<String,Object>) (properties.clone()); 240 } 241 return Collections.unmodifiableMap(ret); 242 } 243 244 /** 245 * Obtain the property value specified by the key. The concept of properties 246 * is further explained in the {@link AudioFileFormat class description}. 247 * <p> 248 * If the specified property is not defined for a particular file format, 249 * this method returns {@code null}. 250 * 251 * @param key the key of the desired property 252 * @return the value of the property with the specified key, or {@code null} 253 * if the property does not exist 254 * @see #properties() 255 * @since 1.5 256 */ 257 public Object getProperty(String key) { 258 if (properties == null) { 259 return null; 260 } 261 return properties.get(key); 262 } 263 264 /** 265 * Provides a string representation of the file format. 266 * 267 * @return the file format as a string 268 */ 269 @Override 270 public String toString() { 271 272 StringBuffer buf = new StringBuffer(); 273 274 //$$fb2002-11-01: fix for 4672864: AudioFileFormat.toString() throws unexpected NullPointerException 275 if (type != null) { 276 buf.append(type.toString() + " (." + type.getExtension() + ") file"); 277 } else { 278 buf.append("unknown file format"); 279 } 280 281 if (byteLength != AudioSystem.NOT_SPECIFIED) { 282 buf.append(", byte length: " + byteLength); 283 } 284 285 buf.append(", data format: " + format); 286 287 if (frameLength != AudioSystem.NOT_SPECIFIED) { 288 buf.append(", frame length: " + frameLength); 289 } 290 291 return new String(buf); 292 } 293 294 /** 295 * An instance of the {@code Type} class represents one of the standard 296 * types of audio file. Static instances are provided for the common types. 297 */ 298 public static class Type { 299 300 // FILE FORMAT TYPE DEFINES 301 302 /** 303 * Specifies a WAVE file. 304 */ 305 public static final Type WAVE = new Type("WAVE", "wav"); 306 307 /** 308 * Specifies an AU file. 309 */ 310 public static final Type AU = new Type("AU", "au"); 311 312 /** 313 * Specifies an AIFF file. 314 */ 315 public static final Type AIFF = new Type("AIFF", "aif"); 316 317 /** 318 * Specifies an AIFF-C file. 319 */ 320 public static final Type AIFC = new Type("AIFF-C", "aifc"); 321 322 /** 323 * Specifies a SND file. 324 */ 325 public static final Type SND = new Type("SND", "snd"); 326 327 /** 328 * File type name. 329 */ 330 private final String name; 331 332 /** 333 * File type extension. 334 */ 335 private final String extension; 336 337 /** 338 * Constructs a file type. 339 * 340 * @param name the string that names the file type 341 * @param extension the string that commonly marks the file type 342 * without leading dot 343 */ 344 public Type(final String name, final String extension) { 345 this.name = name; 346 this.extension = extension; 347 } 348 349 /** 350 * Indicates whether the specified object is equal to this file type, 351 * returning {@code true} if the objects are equal. 352 * 353 * @param obj the reference object with which to compare 354 * @return {@code true} if the specified object is equal to this file 355 * type; {@code false} otherwise 356 */ 357 @Override 358 public final boolean equals(final Object obj) { 359 if (this == obj) { 360 return true; 361 } 362 if (!(obj instanceof Type)) { 363 return false; 364 } 365 return Objects.equals(name, ((Type) obj).name); 366 } 367 368 /** 369 * Returns a hash code value for this file type. 370 * 371 * @return a hash code value for this file type 372 */ 373 @Override 374 public final int hashCode() { 375 return name != null ? name.hashCode() : 0; 376 } 377 378 /** 379 * Provides the file type's name as the {@code String} representation of 380 * the file type. 381 * 382 * @return the file type's name 383 */ 384 @Override 385 public final String toString() { 386 return name; 387 } 388 389 /** 390 * Obtains the common file name extension for this file type. 391 * 392 * @return file type extension 393 */ 394 public String getExtension() { 395 return extension; 396 } 397 } 398 }