1 /* 2 * Copyright (c) 1999, 2020, 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 * Returns a string representation of the audio file format. 266 * 267 * @return a string representation of the audio file format 268 */ 269 @Override 270 public String toString() { 271 String str = "Unknown file format"; 272 //$$fb2002-11-01: fix for 4672864: AudioFileFormat.toString() throws unexpected NullPointerException 273 if (getType() != null) { 274 str = getType() + " (." + getType().getExtension() + ") file"; 275 } 276 if (getByteLength() != AudioSystem.NOT_SPECIFIED) { 277 str += ", byte length: " + getByteLength(); 278 } 279 str += ", data format: " + getFormat(); 280 if (getFrameLength() != AudioSystem.NOT_SPECIFIED) { 281 str += ", frame length: " + getFrameLength(); 282 } 283 return str; 284 } 285 286 /** 287 * An instance of the {@code Type} class represents one of the standard 288 * types of audio file. Static instances are provided for the common types. 289 */ 290 public static class Type { 291 292 // FILE FORMAT TYPE DEFINES 293 294 /** 295 * Specifies a WAVE file. 296 */ 297 public static final Type WAVE = new Type("WAVE", "wav"); 298 299 /** 300 * Specifies an AU file. 301 */ 302 public static final Type AU = new Type("AU", "au"); 303 304 /** 305 * Specifies an AIFF file. 306 */ 307 public static final Type AIFF = new Type("AIFF", "aif"); 308 309 /** 310 * Specifies an AIFF-C file. 311 */ 312 public static final Type AIFC = new Type("AIFF-C", "aifc"); 313 314 /** 315 * Specifies a SND file. 316 */ 317 public static final Type SND = new Type("SND", "snd"); 318 319 /** 320 * File type name. 321 */ 322 private final String name; 323 324 /** 325 * File type extension. 326 */ 327 private final String extension; 328 329 /** 330 * Constructs a file type. 331 * 332 * @param name the string that names the file type 333 * @param extension the string that commonly marks the file type 334 * without leading dot 335 */ 336 public Type(final String name, final String extension) { 337 this.name = name; 338 this.extension = extension; 339 } 340 341 /** 342 * Indicates whether the specified object is equal to this file type, 343 * returning {@code true} if the objects are equal. 344 * 345 * @param obj the reference object with which to compare 346 * @return {@code true} if the specified object is equal to this file 347 * type; {@code false} otherwise 348 */ 349 @Override 350 public final boolean equals(final Object obj) { 351 if (this == obj) { 352 return true; 353 } 354 if (!(obj instanceof Type)) { 355 return false; 356 } 357 return Objects.equals(name, ((Type) obj).name); 358 } 359 360 /** 361 * Returns a hash code value for this file type. 362 * 363 * @return a hash code value for this file type 364 */ 365 @Override 366 public final int hashCode() { 367 return name != null ? name.hashCode() : 0; 368 } 369 370 /** 371 * Returns type's name as the string representation of the file type. 372 * 373 * @return a string representation of the file type 374 */ 375 @Override 376 public final String toString() { 377 return name; 378 } 379 380 /** 381 * Obtains the common file name extension for this file type. 382 * 383 * @return file type extension 384 */ 385 public String getExtension() { 386 return extension; 387 } 388 } 389 }