/*
* @(#)AudioFileFormat.java 1.23 03/12/19
*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
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 AudioFileFormat
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.
*
* The {@link AudioSystem}
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.
*
*
An AudioFileFormat
object can
* include a set of properties. A property is a pair of key and value:
* the key is of type String
, 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.
*
*
The following table lists some common properties that should * be used in implementations: * *
Property key | *Value type | *Description | *
---|---|---|
"duration" | *{@link java.lang.Long Long} | *playback duration of the file in microseconds | *
"author" | *{@link java.lang.String String} | *name of the author of this file | *
"title" | *{@link java.lang.String String} | *title of this file | *
"copyright" | *{@link java.lang.String String} | *copyright message | *
"date" | *{@link java.util.Date Date} | *date of the recording or release | *
"comment" | *{@link java.lang.String String} | *an arbitrary text | *
AudioSystem.NOT_SPECIFIED
* @param format the format of the audio data contained in the file
* @param frameLength the audio data length in sample frames, or AudioSystem.NOT_SPECIFIED
*
* @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 AudioSystem.NOT_SPECIFIED
*/
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
* AudioSystem.NOT_SPECIFIED
* @param properties a Map<String,Object>
object
* with properties
*
* @since 1.5
*/
public AudioFileFormat(Type type, AudioFormat format,
int frameLength, MapWAVE
or AU
.
* @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 Map<String,Object>
object containing
* all properties. If no properties are recognized, an empty map is
* returned.
*
* @see #getProperty(String)
* @since 1.5
*/
public MapIf the specified property is not defined for a
* particular file format, this method returns
* null
.
*
* @param key the key of the desired property
* @return the value of the property with the specified key,
* or null
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 Type
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 String
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