AudioFileFormat


1   /*
2    * @(#)AudioFileFormat.java 1.23 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.sound.sampled;
9   
10  import java.io.File  ;
11  import java.io.OutputStream  ;
12  import java.io.IOException  ;
13  import java.util.Collections  ;
14  import java.util.HashMap  ;
15  import java.util.Map  ;
16  
17  
18  /**
19   * An instance of the <code>AudioFileFormat</code> class describes
20   * an audio file, including the file type, the file's length in bytes,
21   * the length in sample frames of the audio data contained in the file,
22   * and the format of the audio data.
23   * <p>
24   * The <code>{@link AudioSystem}</code> class includes methods for determining the format
25   * of an audio file, obtaining an audio input stream from an audio file, and
26   * writing an audio file from an audio input stream.
27   *
28   * <p>An <code>AudioFileFormat</code> object can
29   * include a set of properties. A property is a pair of key and value:
30   * the key is of type <code>String</code>, the associated property
31   * value is an arbitrary object.
32   * Properties specify additional informational
33   * meta data (like a author, copyright, or file duration).
34   * Properties are optional information, and file reader and file
35   * writer implementations are not required to provide or
36   * recognize properties.
37   *
38   * <p>The following table lists some common properties that should
39   * be used in implementations:
40   *
41   * <table border=1>
42   *  <tr>
43   *   <th>Property key</th>
44   *   <th>Value type</th>
45   *   <th>Description</th>
46   *  </tr>
47   *  <tr>
48   *   <td>&quot;duration&quot;</td>
49   *   <td>{@link java.lang.Long Long}</td>
50   *   <td>playback duration of the file in microseconds</td>
51   *  </tr>
52   *  <tr>
53   *   <td>&quot;author&quot;</td>
54   *   <td>{@link java.lang.String String}</td>
55   *   <td>name of the author of this file</td>
56   *  </tr>
57   *  <tr>
58   *   <td>&quot;title&quot;</td>
59   *   <td>{@link java.lang.String String}</td>
60   *   <td>title of this file</td>
61   *  </tr>
62   *  <tr>
63   *   <td>&quot;copyright&quot;</td>
64   *   <td>{@link java.lang.String String}</td>
65   *   <td>copyright message</td>
66   *  </tr>
67   *  <tr>
68   *   <td>&quot;date&quot;</td>
69   *   <td>{@link java.util.Date Date}</td>
70   *   <td>date of the recording or release</td>
71   *  </tr>
72   *  <tr>
73   *   <td>&quot;comment&quot;</td>
74   *   <td>{@link java.lang.String String}</td>
75   *   <td>an arbitrary text</td>
76   *  </tr>
77   * </table>
78   *
79   *
80   * @author David Rivas
81   * @author Kara Kytle
82   * @author Florian Bomers
83   * @version 1.23 03/12/19
84   * @see AudioInputStream
85   * @since 1.3
86   */
87  public class AudioFileFormat {
88  
89  
90      // INSTANCE VARIABLES
91  
92  
93      /**
94       * File type.
95       */
96      private Type type;
97  
98      /**
99       * File length in bytes
100      */
101     private int byteLength;
102 
103     /**
104      * Format of the audio data contained in the file.
105      */
106     private AudioFormat   format;
107 
108     /**
109      * Audio data length in sample frames
110      */
111     private int frameLength;
112 
113 
114     /** The set of properties */
115     private HashMap  <String  , Object  > properties;
116 
117 
118     /**
119      * Constructs an audio file format object.
120      * This protected constructor is intended for use by providers of file-reading
121      * services when returning information about an audio file or about supported audio file
122      * formats.
123      * @param type the type of the audio file
124      * @param byteLength the length of the file in bytes, or <code>AudioSystem.NOT_SPECIFIED</code>
125      * @param format the format of the audio data contained in the file
126      * @param frameLength the audio data length in sample frames, or <code>AudioSystem.NOT_SPECIFIED</code>
127      *
128      * @see #getType
129      */
130     protected AudioFileFormat(Type type, int byteLength, AudioFormat   format, int frameLength) {
131 
132     this.type = type;
133     this.byteLength = byteLength;
134     this.format = format;
135     this.frameLength = frameLength;
136     this.properties = null;
137     }
138 
139 
140     /**
141      * Constructs an audio file format object.
142      * This public constructor may be used by applications to describe the
143      * properties of a requested audio file.
144      * @param type the type of the audio file
145      * @param format the format of the audio data contained in the file
146      * @param frameLength the audio data length in sample frames, or <code>AudioSystem.NOT_SPECIFIED</code>
147      */
148     public AudioFileFormat(Type type, AudioFormat   format, int frameLength) {
149 
150 
151     this(type,AudioSystem.NOT_SPECIFIED,format,frameLength);
152     }
153 
154     /**
155      * Construct an audio file format object with a set of
156      * defined properties.
157      * This public constructor may be used by applications to describe the
158      * properties of a requested audio file. The properties map
159      * will be copied to prevent any changes to it.
160      *
161      * @param type        the type of the audio file
162      * @param format      the format of the audio data contained in the file
163      * @param frameLength the audio data length in sample frames, or
164      *                    <code>AudioSystem.NOT_SPECIFIED</code>
165      * @param properties  a <code>Map&lt;String,Object&gt;</code> object
166      *        with properties
167      *
168      * @since 1.5
169      */
170     public AudioFileFormat(Type type, AudioFormat   format,
171                int frameLength, Map  <String  , Object  > properties) {
172     this(type,AudioSystem.NOT_SPECIFIED,format,frameLength);
173     this.properties = new HashMap  <String  , Object  >(properties);
174     }
175 
176 
177     /**
178      * Obtains the audio file type, such as <code>WAVE</code> or <code>AU</code>.
179      * @return the audio file type
180      *
181      * @see Type#WAVE
182      * @see Type#AU
183      * @see Type#AIFF
184      * @see Type#AIFC
185      * @see Type#SND
186      */
187     public Type getType() {
188     return type;
189     }
190 
191     /**
192      * Obtains the size in bytes of the entire audio file (not just its audio data).
193      * @return the audio file length in bytes
194      * @see AudioSystem#NOT_SPECIFIED
195      */
196     public int getByteLength() {
197     return byteLength;
198     }
199 
200     /**
201      * Obtains the format of the audio data contained in the audio file.
202      * @return the audio data format
203      */
204     public AudioFormat   getFormat() {
205     return format;
206     }
207 
208     /**
209      * Obtains the length of the audio data contained in the file, expressed in sample frames.
210      * @return the number of sample frames of audio data in the file
211      * @see AudioSystem#NOT_SPECIFIED
212      */
213     public int getFrameLength() {
214     return frameLength;
215     }
216 
217     /**
218      * Obtain an unmodifiable map of properties.
219      * The concept of properties is further explained in
220      * the {@link AudioFileFormat class description}.
221      *
222      * @return a <code>Map&lt;String,Object&gt;</code> object containing
223      *         all properties. If no properties are recognized, an empty map is
224      *         returned.
225      *
226      * @see #getProperty(String)
227      * @since 1.5
228      */
229     public Map  <String  ,Object  > properties() {
230     Map  <String  ,Object  > ret;
231     if (properties == null) {
232         ret = new HashMap  <String  ,Object  >(0);
233     } else {
234         ret = (Map  <String  ,Object  >) (properties.clone());
235     }
236     return (Map  <String  ,Object  >) Collections.unmodifiableMap(ret);
237     }
238 
239 
240     /**
241      * Obtain the property value specified by the key.
242      * The concept of properties is further explained in
243      * the {@link AudioFileFormat class description}.
244      *
245      * <p>If the specified property is not defined for a
246      * particular file format, this method returns
247      * <code>null</code>.
248      *
249      * @param key the key of the desired property
250      * @return the value of the property with the specified key,
251      *         or <code>null</code> if the property does not exist.
252      *
253      * @see #properties
254      * @since 1.5
255      */
256     public Object   getProperty(String   key) {
257     if (properties == null) {
258         return null;
259     }
260     return properties.get(key);
261     }
262 
263 
264     /**
265      * Provides a string representation of the file format.
266      * @return the file format as a string
267      */
268     public String   toString() {
269 
270     StringBuffer   buf = new StringBuffer  ();
271 
272     //$$fb2002-11-01: fix for 4672864: AudioFileFormat.toString() throws unexpected NullPointerException
273     if (type != null) {
274         buf.append(type.toString() + " (." + type.getExtension() + ") file");
275     } else {
276         buf.append("unknown file format");
277     }
278 
279     if (byteLength != AudioSystem.NOT_SPECIFIED) {
280         buf.append(", byte length: " + byteLength);
281     }
282 
283     buf.append(", data format: " + format);
284 
285     if (frameLength != AudioSystem.NOT_SPECIFIED) {
286         buf.append(", frame length: " + frameLength);
287     }
288 
289     return new String  (buf);
290     }
291 
292 
293     /**
294      * An instance of the <code>Type</code> class represents one of the
295      * standard types of audio file.  Static instances are provided for the
296      * 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     // INSTANCE VARIABLES
329 
330     /**
331      * File type name.
332      */
333     private final String   name;
334 
335     /**
336      * File type extension.
337      */
338     private final String   extension;
339 
340 
341     // CONSTRUCTOR
342 
343     /**
344      * Constructs a file type.
345      * @param name the string that names the file type
346      * @param extension the string that commonly marks the file type
347      * without leading dot.
348      */
349     public Type(String   name, String   extension) {
350 
351         this.name = name;
352         this.extension = extension;
353     }
354 
355 
356     // METHODS
357 
358     /**
359      * Finalizes the equals method
360      */
361     public final boolean equals(Object   obj) {
362         if (toString() == null) {
363         return (obj != null) && (obj.toString() == null);
364         }
365         if (obj instanceof Type) {
366         return toString().equals(obj.toString());
367         }
368         return false;
369     }
370 
371     /**
372      * Finalizes the hashCode method
373      */
374     public final int hashCode() {
375         if (toString() == null) {
376         return 0;
377         }
378         return toString().hashCode();
379     }
380 
381     /**
382      * Provides the file type's name as the <code>String</code> representation
383      * of the file type.
384      * @return the file type's name
385      */
386     public final String   toString() {
387         return name;
388     }
389 
390     /**
391      * Obtains the common file name extension for this file type.
392      * @return file type extension
393      */
394     public String   getExtension() {
395         return extension;
396     }
397 
398     } // class Type
399 
400 } // class AudioFileFormat
401
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags