| /* |
| * Copyright (c) 1999, 2007, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package javax.sound.sampled; |
| |
| import java.io.File; |
| import java.io.OutputStream; |
| import java.io.IOException; |
| import java.util.Collections; |
| import java.util.HashMap; |
| import java.util.Map; |
| |
| |
| /** |
| * An instance of the <code>AudioFileFormat</code> class describes |
| * an audio file, including the file type, the file's length in bytes, |
| * the length in sample frames of the audio data contained in the file, |
| * and the format of the audio data. |
| * <p> |
| * The <code>{@link AudioSystem}</code> class includes methods for determining the format |
| * of an audio file, obtaining an audio input stream from an audio file, and |
| * writing an audio file from an audio input stream. |
| * |
| * <p>An <code>AudioFileFormat</code> object can |
| * include a set of properties. A property is a pair of key and value: |
| * the key is of type <code>String</code>, the associated property |
| * value is an arbitrary object. |
| * Properties specify additional informational |
| * meta data (like a author, copyright, or file duration). |
| * Properties are optional information, and file reader and file |
| * writer implementations are not required to provide or |
| * recognize properties. |
| * |
| * <p>The following table lists some common properties that should |
| * be used in implementations: |
| * |
| * <table border=1> |
| * <tr> |
| * <th>Property key</th> |
| * <th>Value type</th> |
| * <th>Description</th> |
| * </tr> |
| * <tr> |
| * <td>"duration"</td> |
| * <td>{@link java.lang.Long Long}</td> |
| * <td>playback duration of the file in microseconds</td> |
| * </tr> |
| * <tr> |
| * <td>"author"</td> |
| * <td>{@link java.lang.String String}</td> |
| * <td>name of the author of this file</td> |
| * </tr> |
| * <tr> |
| * <td>"title"</td> |
| * <td>{@link java.lang.String String}</td> |
| * <td>title of this file</td> |
| * </tr> |
| * <tr> |
| * <td>"copyright"</td> |
| * <td>{@link java.lang.String String}</td> |
| * <td>copyright message</td> |
| * </tr> |
| * <tr> |
| * <td>"date"</td> |
| * <td>{@link java.util.Date Date}</td> |
| * <td>date of the recording or release</td> |
| * </tr> |
| * <tr> |
| * <td>"comment"</td> |
| * <td>{@link java.lang.String String}</td> |
| * <td>an arbitrary text</td> |
| * </tr> |
| * </table> |
| * |
| * |
| * @author David Rivas |
| * @author Kara Kytle |
| * @author Florian Bomers |
| * @see AudioInputStream |
| * @since 1.3 |
| */ |
| public class AudioFileFormat { |
| |
| |
| // INSTANCE VARIABLES |
| |
| |
| /** |
| * File type. |
| */ |
| private Type type; |
| |
| /** |
| * File length in bytes |
| */ |
| private int byteLength; |
| |
| /** |
| * Format of the audio data contained in the file. |
| */ |
| private AudioFormat format; |
| |
| /** |
| * Audio data length in sample frames |
| */ |
| private int frameLength; |
| |
| |
| /** The set of properties */ |
| private HashMap<String, Object> properties; |
| |
| |
| /** |
| * Constructs an audio file format object. |
| * This protected constructor is intended for use by providers of file-reading |
| * services when returning information about an audio file or about supported audio file |
| * formats. |
| * @param type the type of the audio file |
| * @param byteLength the length of the file in bytes, or <code>AudioSystem.NOT_SPECIFIED</code> |
| * @param format the format of the audio data contained in the file |
| * @param frameLength the audio data length in sample frames, or <code>AudioSystem.NOT_SPECIFIED</code> |
| * |
| * @see #getType |
| */ |
| protected AudioFileFormat(Type type, int byteLength, AudioFormat format, int frameLength) { |
| |
| this.type = type; |
| this.byteLength = byteLength; |
| this.format = format; |
| this.frameLength = frameLength; |
| this.properties = null; |
| } |
| |
| |
| /** |
| * Constructs an audio file format object. |
| * This public constructor may be used by applications to describe the |
| * properties of a requested audio file. |
| * @param type the type of the audio file |
| * @param format the format of the audio data contained in the file |
| * @param frameLength the audio data length in sample frames, or <code>AudioSystem.NOT_SPECIFIED</code> |
| */ |
| public AudioFileFormat(Type type, AudioFormat format, int frameLength) { |
| |
| |
| this(type,AudioSystem.NOT_SPECIFIED,format,frameLength); |
| } |
| |
| /** |
| * Construct an audio file format object with a set of |
| * defined properties. |
| * This public constructor may be used by applications to describe the |
| * properties of a requested audio file. The properties map |
| * will be copied to prevent any changes to it. |
| * |
| * @param type the type of the audio file |
| * @param format the format of the audio data contained in the file |
| * @param frameLength the audio data length in sample frames, or |
| * <code>AudioSystem.NOT_SPECIFIED</code> |
| * @param properties a <code>Map<String,Object></code> object |
| * with properties |
| * |
| * @since 1.5 |
| */ |
| public AudioFileFormat(Type type, AudioFormat format, |
| int frameLength, Map<String, Object> properties) { |
| this(type,AudioSystem.NOT_SPECIFIED,format,frameLength); |
| this.properties = new HashMap<String, Object>(properties); |
| } |
| |
| |
| /** |
| * Obtains the audio file type, such as <code>WAVE</code> or <code>AU</code>. |
| * @return the audio file type |
| * |
| * @see Type#WAVE |
| * @see Type#AU |
| * @see Type#AIFF |
| * @see Type#AIFC |
| * @see Type#SND |
| */ |
| public Type getType() { |
| return type; |
| } |
| |
| /** |
| * Obtains the size in bytes of the entire audio file (not just its audio data). |
| * @return the audio file length in bytes |
| * @see AudioSystem#NOT_SPECIFIED |
| */ |
| public int getByteLength() { |
| return byteLength; |
| } |
| |
| /** |
| * Obtains the format of the audio data contained in the audio file. |
| * @return the audio data format |
| */ |
| public AudioFormat getFormat() { |
| return format; |
| } |
| |
| /** |
| * Obtains the length of the audio data contained in the file, expressed in sample frames. |
| * @return the number of sample frames of audio data in the file |
| * @see AudioSystem#NOT_SPECIFIED |
| */ |
| public int getFrameLength() { |
| return frameLength; |
| } |
| |
| /** |
| * Obtain an unmodifiable map of properties. |
| * The concept of properties is further explained in |
| * the {@link AudioFileFormat class description}. |
| * |
| * @return a <code>Map<String,Object></code> object containing |
| * all properties. If no properties are recognized, an empty map is |
| * returned. |
| * |
| * @see #getProperty(String) |
| * @since 1.5 |
| */ |
| public Map<String,Object> properties() { |
| Map<String,Object> ret; |
| if (properties == null) { |
| ret = new HashMap<String,Object>(0); |
| } else { |
| ret = (Map<String,Object>) (properties.clone()); |
| } |
| return (Map<String,Object>) Collections.unmodifiableMap(ret); |
| } |
| |
| |
| /** |
| * Obtain the property value specified by the key. |
| * The concept of properties is further explained in |
| * the {@link AudioFileFormat class description}. |
| * |
| * <p>If the specified property is not defined for a |
| * particular file format, this method returns |
| * <code>null</code>. |
| * |
| * @param key the key of the desired property |
| * @return the value of the property with the specified key, |
| * or <code>null</code> if the property does not exist. |
| * |
| * @see #properties() |
| * @since 1.5 |
| */ |
| public Object getProperty(String key) { |
| if (properties == null) { |
| return null; |
| } |
| return properties.get(key); |
| } |
| |
| |
| /** |
| * Provides a string representation of the file format. |
| * @return the file format as a string |
| */ |
| public String toString() { |
| |
| StringBuffer buf = new StringBuffer(); |
| |
| //$$fb2002-11-01: fix for 4672864: AudioFileFormat.toString() throws unexpected NullPointerException |
| if (type != null) { |
| buf.append(type.toString() + " (." + type.getExtension() + ") file"); |
| } else { |
| buf.append("unknown file format"); |
| } |
| |
| if (byteLength != AudioSystem.NOT_SPECIFIED) { |
| buf.append(", byte length: " + byteLength); |
| } |
| |
| buf.append(", data format: " + format); |
| |
| if (frameLength != AudioSystem.NOT_SPECIFIED) { |
| buf.append(", frame length: " + frameLength); |
| } |
| |
| return new String(buf); |
| } |
| |
| |
| /** |
| * An instance of the <code>Type</code> class represents one of the |
| * standard types of audio file. Static instances are provided for the |
| * common types. |
| */ |
| public static class Type { |
| |
| // FILE FORMAT TYPE DEFINES |
| |
| /** |
| * Specifies a WAVE file. |
| */ |
| public static final Type WAVE = new Type("WAVE", "wav"); |
| |
| /** |
| * Specifies an AU file. |
| */ |
| public static final Type AU = new Type("AU", "au"); |
| |
| /** |
| * Specifies an AIFF file. |
| */ |
| public static final Type AIFF = new Type("AIFF", "aif"); |
| |
| /** |
| * Specifies an AIFF-C file. |
| */ |
| public static final Type AIFC = new Type("AIFF-C", "aifc"); |
| |
| /** |
| * Specifies a SND file. |
| */ |
| public static final Type SND = new Type("SND", "snd"); |
| |
| |
| // INSTANCE VARIABLES |
| |
| /** |
| * File type name. |
| */ |
| private final String name; |
| |
| /** |
| * File type extension. |
| */ |
| private final String extension; |
| |
| |
| // CONSTRUCTOR |
| |
| /** |
| * Constructs a file type. |
| * @param name the string that names the file type |
| * @param extension the string that commonly marks the file type |
| * without leading dot. |
| */ |
| public Type(String name, String extension) { |
| |
| this.name = name; |
| this.extension = extension; |
| } |
| |
| |
| // METHODS |
| |
| /** |
| * Finalizes the equals method |
| */ |
| public final boolean equals(Object obj) { |
| if (toString() == null) { |
| return (obj != null) && (obj.toString() == null); |
| } |
| if (obj instanceof Type) { |
| return toString().equals(obj.toString()); |
| } |
| return false; |
| } |
| |
| /** |
| * Finalizes the hashCode method |
| */ |
| public final int hashCode() { |
| if (toString() == null) { |
| return 0; |
| } |
| return toString().hashCode(); |
| } |
| |
| /** |
| * Provides the file type's name as the <code>String</code> representation |
| * of the file type. |
| * @return the file type's name |
| */ |
| public final String toString() { |
| return name; |
| } |
| |
| /** |
| * Obtains the common file name extension for this file type. |
| * @return file type extension |
| */ |
| public String getExtension() { |
| return extension; |
| } |
| |
| } // class Type |
| |
| } // class AudioFileFormat |