https://openjdk.java.net/ 
/*
 * Copyright (c) 1999, 2017, 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.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;


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} 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 {@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.
 * <p>
 * An {@code AudioFileFormat} object can include a set of properties. A property
 * is a pair of key and value: the key is of type {@code 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.
 * <p>
 * The following table lists some common properties that should be used in
 * implementations:
 *
 * <table class="striped">
 * <caption>Audio File Format Properties</caption>
 * <thead>
 *   <tr>
 *     <th scope="col">Property key
 *     <th scope="col">Value type
 *     <th scope="col">Description
 * </thead>
 * <tbody>
 *   <tr>
 *     <th scope="row">"duration"
 *     <td>{@link Long Long}
 *     <td>playback duration of the file in microseconds
 *   <tr>
 *     <th scope="row">"author"
 *     <td>{@link String String}
 *     <td>name of the author of this file
 *   <tr>
 *     <th scope="row">"title"
 *     <td>{@link String String}
 *     <td>title of this file
 *   <tr>
 *     <th scope="row">"copyright"
 *     <td>{@link String String}
 *     <td>copyright message
 *   <tr>
 *     <th scope="row">"date"
 *     <td>{@link java.util.Date Date}
 *     <td>date of the recording or release
 *   <tr>
 *     <th scope="row">"comment"
 *     <td>{@link String String}
 *     <td>an arbitrary text
 * </tbody>
 * </table>
 *
 * @author David Rivas
 * @author Kara Kytle
 * @author Florian Bomers
 * @see AudioInputStream
 * @since 1.3
 */
public class AudioFileFormat {

    
File type.

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

    
File length in bytes.

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

    
Format of the audio data contained in the file.

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

    
Audio data length in sample frames.

/**
     * Audio data length in sample frames.
     */
    private final 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}
     * @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}
     * @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}
     */
    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}
     * @param  properties a {@code Map<String, Object>} 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<>(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} or {@code 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).

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<String, Object>} object containing all properties.
     *         If no properties are recognized, an empty map is returned.
     * @see #getProperty(String)
     * @since 1.5
     */
    @SuppressWarnings("unchecked") // Cast of result of clone
    public Map<String, Object> properties() {
        Map<String,Object> ret;
        if (properties == null) {
            ret = new HashMap<>(0);
        } else {
            ret = (Map<String,Object>) (properties.clone());
        }
        return 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}.
     *
     * @param  key the key of the desired property
     * @return the value of the property with the specified key, or {@code 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.

Returns:the file format as a string
/**
     * Provides a string representation of the file format.
     *
     * @return the file format as a string
     */
    @Override
    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} 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");

        
File type name.

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

        
File type extension.

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

        
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(final String name, final String extension) {
            this.name = name;
            this.extension = extension;
        }

        
Indicates whether the specified object is equal to this file type, returning true if the objects are equal. 
Params:
  • obj – the reference object with which to compare
Returns:true if the specified object is equal to this file type; false otherwise
/**
         * Indicates whether the specified object is equal to this file type,
         * returning {@code true} if the objects are equal.
         *
         * @param  obj the reference object with which to compare
         * @return {@code true} if the specified object is equal to this file
         *         type; {@code false} otherwise
         */
        @Override
        public final boolean equals(final Object obj) {
            if (this == obj) {
                return true;
            }
            if (!(obj instanceof Type)) {
                return false;
            }
            return Objects.equals(name, ((Type) obj).name);
        }

        
Returns a hash code value for this file type.

Returns:a hash code value for this file type
/**
         * Returns a hash code value for this file type.
         *
         * @return a hash code value for this file type
         */
        @Override
        public final int hashCode() {
            return name != null ? name.hashCode() : 0;
        }

        
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} representation of
         * the file type.
         *
         * @return the file type's name
         */
        @Override
        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;
        }
    }
}