001 /*
002 * Copyright 1999-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.sound.sampled;
027
028 import java.io.File;
029 import java.io.OutputStream;
030 import java.io.IOException;
031 import java.util.Collections;
032 import java.util.HashMap;
033 import java.util.Map;
034
035 /**
036 * An instance of the <code>AudioFileFormat</code> class describes
037 * an audio file, including the file type, the file's length in bytes,
038 * the length in sample frames of the audio data contained in the file,
039 * and the format of the audio data.
040 * <p>
041 * The <code>{@link AudioSystem}</code> class includes methods for determining the format
042 * of an audio file, obtaining an audio input stream from an audio file, and
043 * writing an audio file from an audio input stream.
044 *
045 * <p>An <code>AudioFileFormat</code> object can
046 * include a set of properties. A property is a pair of key and value:
047 * the key is of type <code>String</code>, the associated property
048 * value is an arbitrary object.
049 * Properties specify additional informational
050 * meta data (like a author, copyright, or file duration).
051 * Properties are optional information, and file reader and file
052 * writer implementations are not required to provide or
053 * recognize properties.
054 *
055 * <p>The following table lists some common properties that should
056 * be used in implementations:
057 *
058 * <table border=1>
059 * <tr>
060 * <th>Property key</th>
061 * <th>Value type</th>
062 * <th>Description</th>
063 * </tr>
064 * <tr>
065 * <td>"duration"</td>
066 * <td>{@link java.lang.Long Long}</td>
067 * <td>playback duration of the file in microseconds</td>
068 * </tr>
069 * <tr>
070 * <td>"author"</td>
071 * <td>{@link java.lang.String String}</td>
072 * <td>name of the author of this file</td>
073 * </tr>
074 * <tr>
075 * <td>"title"</td>
076 * <td>{@link java.lang.String String}</td>
077 * <td>title of this file</td>
078 * </tr>
079 * <tr>
080 * <td>"copyright"</td>
081 * <td>{@link java.lang.String String}</td>
082 * <td>copyright message</td>
083 * </tr>
084 * <tr>
085 * <td>"date"</td>
086 * <td>{@link java.util.Date Date}</td>
087 * <td>date of the recording or release</td>
088 * </tr>
089 * <tr>
090 * <td>"comment"</td>
091 * <td>{@link java.lang.String String}</td>
092 * <td>an arbitrary text</td>
093 * </tr>
094 * </table>
095 *
096 *
097 * @author David Rivas
098 * @author Kara Kytle
099 * @author Florian Bomers
100 * @version 1.29 07/05/05
101 * @see AudioInputStream
102 * @since 1.3
103 */
104 public class AudioFileFormat {
105
106 // INSTANCE VARIABLES
107
108 /**
109 * File type.
110 */
111 private Type type;
112
113 /**
114 * File length in bytes
115 */
116 private int byteLength;
117
118 /**
119 * Format of the audio data contained in the file.
120 */
121 private AudioFormat format;
122
123 /**
124 * Audio data length in sample frames
125 */
126 private int frameLength;
127
128 /** The set of properties */
129 private HashMap<String, Object> properties;
130
131 /**
132 * Constructs an audio file format object.
133 * This protected constructor is intended for use by providers of file-reading
134 * services when returning information about an audio file or about supported audio file
135 * formats.
136 * @param type the type of the audio file
137 * @param byteLength the length of the file in bytes, or <code>AudioSystem.NOT_SPECIFIED</code>
138 * @param format the format of the audio data contained in the file
139 * @param frameLength the audio data length in sample frames, or <code>AudioSystem.NOT_SPECIFIED</code>
140 *
141 * @see #getType
142 */
143 protected AudioFileFormat(Type type, int byteLength,
144 AudioFormat format, int frameLength) {
145
146 this .type = type;
147 this .byteLength = byteLength;
148 this .format = format;
149 this .frameLength = frameLength;
150 this .properties = null;
151 }
152
153 /**
154 * Constructs an audio file format object.
155 * This public constructor may be used by applications to describe the
156 * properties of a requested audio file.
157 * @param type the type of the audio file
158 * @param format the format of the audio data contained in the file
159 * @param frameLength the audio data length in sample frames, or <code>AudioSystem.NOT_SPECIFIED</code>
160 */
161 public AudioFileFormat(Type type, AudioFormat format,
162 int frameLength) {
163
164 this (type, AudioSystem.NOT_SPECIFIED, format, frameLength);
165 }
166
167 /**
168 * Construct an audio file format object with a set of
169 * defined properties.
170 * This public constructor may be used by applications to describe the
171 * properties of a requested audio file. The properties map
172 * will be copied to prevent any changes to it.
173 *
174 * @param type the type of the audio file
175 * @param format the format of the audio data contained in the file
176 * @param frameLength the audio data length in sample frames, or
177 * <code>AudioSystem.NOT_SPECIFIED</code>
178 * @param properties a <code>Map<String,Object></code> object
179 * with properties
180 *
181 * @since 1.5
182 */
183 public AudioFileFormat(Type type, AudioFormat format,
184 int frameLength, Map<String, Object> properties) {
185 this (type, AudioSystem.NOT_SPECIFIED, format, frameLength);
186 this .properties = new HashMap<String, Object>(properties);
187 }
188
189 /**
190 * Obtains the audio file type, such as <code>WAVE</code> or <code>AU</code>.
191 * @return the audio file type
192 *
193 * @see Type#WAVE
194 * @see Type#AU
195 * @see Type#AIFF
196 * @see Type#AIFC
197 * @see Type#SND
198 */
199 public Type getType() {
200 return type;
201 }
202
203 /**
204 * Obtains the size in bytes of the entire audio file (not just its audio data).
205 * @return the audio file length in bytes
206 * @see AudioSystem#NOT_SPECIFIED
207 */
208 public int getByteLength() {
209 return byteLength;
210 }
211
212 /**
213 * Obtains the format of the audio data contained in the audio file.
214 * @return the audio data format
215 */
216 public AudioFormat getFormat() {
217 return format;
218 }
219
220 /**
221 * Obtains the length of the audio data contained in the file, expressed in sample frames.
222 * @return the number of sample frames of audio data in the file
223 * @see AudioSystem#NOT_SPECIFIED
224 */
225 public int getFrameLength() {
226 return frameLength;
227 }
228
229 /**
230 * Obtain an unmodifiable map of properties.
231 * The concept of properties is further explained in
232 * the {@link AudioFileFormat class description}.
233 *
234 * @return a <code>Map<String,Object></code> object containing
235 * all properties. If no properties are recognized, an empty map is
236 * returned.
237 *
238 * @see #getProperty(String)
239 * @since 1.5
240 */
241 public Map<String, Object> properties() {
242 Map<String, Object> ret;
243 if (properties == null) {
244 ret = new HashMap<String, Object>(0);
245 } else {
246 ret = (Map<String, Object>) (properties.clone());
247 }
248 return (Map<String, Object>) Collections.unmodifiableMap(ret);
249 }
250
251 /**
252 * Obtain the property value specified by the key.
253 * The concept of properties is further explained in
254 * the {@link AudioFileFormat class description}.
255 *
256 * <p>If the specified property is not defined for a
257 * particular file format, this method returns
258 * <code>null</code>.
259 *
260 * @param key the key of the desired property
261 * @return the value of the property with the specified key,
262 * or <code>null</code> if the property does not exist.
263 *
264 * @see #properties()
265 * @since 1.5
266 */
267 public Object getProperty(String key) {
268 if (properties == null) {
269 return null;
270 }
271 return properties.get(key);
272 }
273
274 /**
275 * Provides a string representation of the file format.
276 * @return the file format as a string
277 */
278 public String toString() {
279
280 StringBuffer buf = new StringBuffer();
281
282 //$$fb2002-11-01: fix for 4672864: AudioFileFormat.toString() throws unexpected NullPointerException
283 if (type != null) {
284 buf.append(type.toString() + " (." + type.getExtension()
285 + ") file");
286 } else {
287 buf.append("unknown file format");
288 }
289
290 if (byteLength != AudioSystem.NOT_SPECIFIED) {
291 buf.append(", byte length: " + byteLength);
292 }
293
294 buf.append(", data format: " + format);
295
296 if (frameLength != AudioSystem.NOT_SPECIFIED) {
297 buf.append(", frame length: " + frameLength);
298 }
299
300 return new String(buf);
301 }
302
303 /**
304 * An instance of the <code>Type</code> class represents one of the
305 * standard types of audio file. Static instances are provided for the
306 * common types.
307 */
308 public static class Type {
309
310 // FILE FORMAT TYPE DEFINES
311
312 /**
313 * Specifies a WAVE file.
314 */
315 public static final Type WAVE = new Type("WAVE", "wav");
316
317 /**
318 * Specifies an AU file.
319 */
320 public static final Type AU = new Type("AU", "au");
321
322 /**
323 * Specifies an AIFF file.
324 */
325 public static final Type AIFF = new Type("AIFF", "aif");
326
327 /**
328 * Specifies an AIFF-C file.
329 */
330 public static final Type AIFC = new Type("AIFF-C", "aifc");
331
332 /**
333 * Specifies a SND file.
334 */
335 public static final Type SND = new Type("SND", "snd");
336
337 // INSTANCE VARIABLES
338
339 /**
340 * File type name.
341 */
342 private final String name;
343
344 /**
345 * File type extension.
346 */
347 private final String extension;
348
349 // CONSTRUCTOR
350
351 /**
352 * Constructs a file type.
353 * @param name the string that names the file type
354 * @param extension the string that commonly marks the file type
355 * without leading dot.
356 */
357 public Type(String name, String extension) {
358
359 this .name = name;
360 this .extension = extension;
361 }
362
363 // METHODS
364
365 /**
366 * Finalizes the equals method
367 */
368 public final boolean equals(Object obj) {
369 if (toString() == null) {
370 return (obj != null) && (obj.toString() == null);
371 }
372 if (obj instanceof Type) {
373 return toString().equals(obj.toString());
374 }
375 return false;
376 }
377
378 /**
379 * Finalizes the hashCode method
380 */
381 public final int hashCode() {
382 if (toString() == null) {
383 return 0;
384 }
385 return toString().hashCode();
386 }
387
388 /**
389 * Provides the file type's name as the <code>String</code> representation
390 * of the file type.
391 * @return the file type's name
392 */
393 public final String toString() {
394 return name;
395 }
396
397 /**
398 * Obtains the common file name extension for this file type.
399 * @return file type extension
400 */
401 public String getExtension() {
402 return extension;
403 }
404
405 } // class Type
406
407 } // class AudioFileFormat
|