https://openjdk.java.net/ 
/*
 * Copyright (c) 1999, 2013, 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 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 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:


 Audio File Format Properties
 

  Property key
  Value type
  Description
 

 

  "duration"
  Long
  playback duration of the file in microseconds
 

 

  "author"
  String
  name of the author of this file
 

 

  "title"
  String
  title of this file
 

 

  "copyright"
  String
  copyright message
 

 

  "date"
  Date
  date of the recording or release
 

 

  "comment"
  String
  an arbitrary text
 




Author:David Rivas, Kara Kytle, Florian Bomers
See Also:
Since:1.3
/**
 * 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>
 *  <caption>Audio File Format Properties</caption>
 *  <tr>
 *   <th>Property key</th>
 *   <th>Value type</th>
 *   <th>Description</th>
 *  </tr>
 *  <tr>
 *   <td>&quot;duration&quot;</td>
 *   <td>{@link java.lang.Long Long}</td>
 *   <td>playback duration of the file in microseconds</td>
 *  </tr>
 *  <tr>
 *   <td>&quot;author&quot;</td>
 *   <td>{@link java.lang.String String}</td>
 *   <td>name of the author of this file</td>
 *  </tr>
 *  <tr>
 *   <td>&quot;title&quot;</td>
 *   <td>{@link java.lang.String String}</td>
 *   <td>title of this file</td>
 *  </tr>
 *  <tr>
 *   <td>&quot;copyright&quot;</td>
 *   <td>{@link java.lang.String String}</td>
 *   <td>copyright message</td>
 *  </tr>
 *  <tr>
 *   <td>&quot;date&quot;</td>
 *   <td>{@link java.util.Date Date}</td>
 *   <td>date of the recording or release</td>
 *  </tr>
 *  <tr>
 *   <td>&quot;comment&quot;</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.

/**
     * File type.
     */
    private Type type;

    
File length in bytes

/**
     * File length in bytes
     */
    private int byteLength;

    
Format of the audio data contained in the file.

/**
     * Format of the audio data contained in the file.
     */
    private AudioFormat format;

    
Audio data length in sample frames

/**
     * Audio data length in sample frames
     */
    private int frameLength;


    
The set of properties 
/** 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.

Params:
  • type – the type of the audio file
  • byteLength – the length of the file in bytes, or AudioSystem.NOT_SPECIFIED
  • format – the format of the audio data contained in the file
  • frameLength – the audio data length in sample frames, or AudioSystem.NOT_SPECIFIED
See Also:
/**
     * 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.

Params:
  • type – the type of the audio file
  • format – the format of the audio data contained in the file
  • frameLength – the audio data length in sample frames, or AudioSystem.NOT_SPECIFIED
/**
     * 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.

Params:
  • type –        the type of the audio file
  • format –      the format of the audio data contained in the file
  • frameLength – the audio data length in sample frames, or
                   AudioSystem.NOT_SPECIFIED
  • properties –  a Map<String,Object> object
       with properties
Since:1.5
/**
     * 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&lt;String,Object&gt;</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 WAVE or AU.

See Also:
Returns:the audio file type
/**
     * 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).

See Also:
Returns:the audio file length in bytes
/**
     * 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.

Returns:the audio data format
/**
     * 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.

See Also:
Returns:the number of sample frames of audio data in the file
/**
     * 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 class description. 
See Also:
Returns:a Map<String,Object> object containing
        all properties. If no properties are recognized, an empty map is
        returned.
Since:1.5
/**
     * Obtain an unmodifiable map of properties.
     * The concept of properties is further explained in
     * the {@link AudioFileFormat class description}.
     *
     * @return a <code>Map&lt;String,Object&gt;</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 class description. 
If the specified property is not defined for a
particular file format, this method returns
null.

Params:
  • key – the key of the desired property
See Also:
Returns:the value of the property with the specified key,
        or null if the property does not exist.
Since:1.5
/**
     * 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.

Returns:the file format as a string
/**
     * 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.

/**
     * 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.

/**
         * Specifies a WAVE file.
         */
        public static final Type WAVE = new Type("WAVE", "wav");

        
Specifies an AU file.

/**
         * Specifies an AU file.
         */
        public static final Type AU = new Type("AU", "au");

        
Specifies an AIFF file.

/**
         * Specifies an AIFF file.
         */
        public static final Type AIFF = new Type("AIFF", "aif");

        
Specifies an AIFF-C file.

/**
         * Specifies an AIFF-C file.
         */
        public static final Type AIFC = new Type("AIFF-C", "aifc");

        
Specifies a SND file.

/**
         * Specifies a SND file.
         */
        public static final Type SND = new Type("SND", "snd");


        // INSTANCE VARIABLES

        
File type name.

/**
         * File type name.
         */
        private final String name;

        
File type extension.

/**
         * File type extension.
         */
        private final String extension;


        // CONSTRUCTOR

        
Constructs a file type.

Params:
  • name – the string that names the file type
  • extension – the string that commonly marks the file type
without leading dot.
/**
         * 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

/**
         * 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

/**
         * 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.

Returns:the file type's name
/**
         * 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.

Returns:file type extension
/**
         * Obtains the common file name extension for this file type.
         * @return file type extension
         */
        public String getExtension() {
            return extension;
        }

    } // class Type

} // class AudioFileFormat