| /* |
| * 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 {@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. |
| */ |
| private final Type type; |
| |
| /** |
| * File length in bytes. |
| */ |
| private final int byteLength; |
| |
| /** |
| * Format of the audio data contained in the file. |
| */ |
| private final AudioFormat format; |
| |
| /** |
| * Audio data length in sample frames. |
| */ |
| private final 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} |
| * @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. |
| * |
| * @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. |
| * |
| * @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 {@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). |
| * |
| * @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>} 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 {@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. |
| * |
| * @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 {@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. |
| */ |
| 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"); |
| |
| /** |
| * File type name. |
| */ |
| private final String name; |
| |
| /** |
| * File type extension. |
| */ |
| private final String extension; |
| |
| /** |
| * 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 {@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. |
| * |
| * @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 {@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. |
| * |
| * @return file type extension |
| */ |
| public String getExtension() { |
| return extension; |
| } |
| } |
| } |
