/*

 * Copyright (c) 1999, 2015, 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.IOException;

import java.io.InputStream;

import java.io.OutputStream;

import java.net.URL;

import java.util.ArrayList;

import java.util.HashSet;

import java.util.List;

import java.util.Objects;

import java.util.Properties;

import java.util.Set;

import java.util.Vector;

import javax.sound.sampled.spi.AudioFileReader;

import javax.sound.sampled.spi.AudioFileWriter;

import javax.sound.sampled.spi.FormatConversionProvider;

import javax.sound.sampled.spi.MixerProvider;

import com.sun.media.sound.JDK13Services;

/* $fb TODO:

 * - consistent usage of (typed) collections

 */

/**

 * The {@code AudioSystem} class acts as the entry point to the sampled-audio

 * system resources. This class lets you query and access the mixers that are

 * installed on the system. {@code AudioSystem} includes a number of methods for

 * converting audio data between different formats, and for translating between

 * audio files and streams. It also provides a method for obtaining a

 * {@link Line} directly from the {@code AudioSystem} without dealing explicitly

 * with mixers.

 * <p>

 * Properties can be used to specify the default mixer for specific line types.

 * Both system properties and a properties file are considered. The

 * "sound.properties" properties file is read from an implementation-specific

 * location (typically it is the {@code conf} directory in the Java installation

 * directory). If a property exists both as a system property and in the

 * properties file, the system property takes precedence. If none is specified,

 * a suitable default is chosen among the available devices. The syntax of the

 * properties file is specified in

 * {@link Properties#load(InputStream) Properties.load}. The following table

 * lists the available property keys and which methods consider them:

 *

 * <table border=0>

 *  <caption>Audio System Property Keys</caption>

 *  <tr>

 *   <th>Property Key</th>

 *   <th>Interface</th>

 *   <th>Affected Method(s)</th>

 *  </tr>

 *  <tr>

 *   <td>{@code javax.sound.sampled.Clip}</td>

 *   <td>{@link Clip}</td>

 *   <td>{@link #getLine}, {@link #getClip}</td>

 *  </tr>

 *  <tr>

 *   <td>{@code javax.sound.sampled.Port}</td>

 *   <td>{@link Port}</td>

 *   <td>{@link #getLine}</td>

 *  </tr>

 *  <tr>

 *   <td>{@code javax.sound.sampled.SourceDataLine}</td>

 *   <td>{@link SourceDataLine}</td>

 *   <td>{@link #getLine}, {@link #getSourceDataLine}</td>

 *  </tr>

 *  <tr>

 *   <td>{@code javax.sound.sampled.TargetDataLine}</td>

 *   <td>{@link TargetDataLine}</td>

 *   <td>{@link #getLine}, {@link #getTargetDataLine}</td>

 *  </tr>

 * </table>

 *

 * The property value consists of the provider class name and the mixer name,

 * separated by the hash mark ("#"). The provider class name is the

 * fully-qualified name of a concrete {@link MixerProvider mixer provider}

 * class. The mixer name is matched against the {@code String} returned by the

 * {@code getName} method of {@code Mixer.Info}. Either the class name, or the

 * mixer name may be omitted. If only the class name is specified, the trailing

 * hash mark is optional.

 * <p>

 * If the provider class is specified, and it can be successfully retrieved from

 * the installed providers, the list of {@code Mixer.Info} objects is retrieved

 * from the provider. Otherwise, or when these mixers do not provide a

 * subsequent match, the list is retrieved from {@link #getMixerInfo} to contain

 * all available {@code Mixer.Info} objects.

 * <p>

 * If a mixer name is specified, the resulting list of {@code Mixer.Info}

 * objects is searched: the first one with a matching name, and whose

 * {@code Mixer} provides the respective line interface, will be returned. If no

 * matching {@code Mixer.Info} object is found, or the mixer name is not

 * specified, the first mixer from the resulting list, which provides the

 * respective line interface, will be returned.

 *

 * For example, the property {@code javax.sound.sampled.Clip} with a value

 * {@code "com.sun.media.sound.MixerProvider#SunClip"}

 * will have the following consequences when {@code getLine} is called

 * requesting a {@code Clip} instance: if the class

 * {@code com.sun.media.sound.MixerProvider} exists in the list of installed

 * mixer providers, the first {@code Clip} from the first mixer with name

 * {@code "SunClip"} will be returned. If it cannot be found, the

 * first {@code Clip} from the first mixer of the specified provider will be

 * returned, regardless of name. If there is none, the first {@code Clip} from

 * the first {@code Mixer} with name {@code "SunClip"} in the list of

 * all mixers (as returned by {@code getMixerInfo}) will be returned, or, if not

 * found, the first {@code Clip} of the first {@code Mixer} that can be found in

 * the list of all mixers is returned. If that fails, too, an

 * {@code IllegalArgumentException} is thrown.

 *

 * @author Kara Kytle

 * @author Florian Bomers

 * @author Matthias Pfisterer

 * @author Kevin P. Smith

 * @see AudioFormat

 * @see AudioInputStream

 * @see Mixer

 * @see Line

 * @see Line.Info

 * @since 1.3

 */

public class AudioSystem {

    /**

     * An integer that stands for an unknown numeric value. This value is

     * appropriate only for signed quantities that do not normally take negative

     * values. Examples include file sizes, frame sizes, buffer sizes, and

     * sample rates. A number of Java Sound constructors accept a value of

     * {@code NOT_SPECIFIED} for such parameters. Other methods may also accept

     * or return this value, as documented.

     */

    public static final int NOT_SPECIFIED = -1;

    /**

     * Private no-args constructor for ensuring against instantiation.

     */

    private AudioSystem() {

    }

    /**

     * Obtains an array of mixer info objects that represents the set of audio

     * mixers that are currently installed on the system.

     *

     * @return an array of info objects for the currently installed mixers. If

     *         no mixers are available on the system, an array of length 0 is

     *         returned.

     * @see #getMixer

     */

    public static Mixer.Info[] getMixerInfo() {

        List<Mixer.Info> infos = getMixerInfoList();

        Mixer.Info[] allInfos = infos.toArray(new Mixer.Info[infos.size()]);

        return allInfos;

    }

    /**

     * Obtains the requested audio mixer.

     *

     * @param  info a {@code Mixer.Info} object representing the desired mixer,

     *         or {@code null} for the system default mixer

     * @return the requested mixer

     * @throws SecurityException if the requested mixer is unavailable because

     *         of security restrictions

     * @throws IllegalArgumentException if the info object does not represent a

     *         mixer installed on the system

     * @see #getMixerInfo

     */

    public static Mixer getMixer(final Mixer.Info info) {

        for (final MixerProvider provider : getMixerProviders()) {

            try {

                return provider.getMixer(info);

            } catch (IllegalArgumentException | NullPointerException ignored) {

                // The MixerProvider.getMixer(null) should return default Mixer,

                // This behaviour was assumed from the beginning, but strictly

                // specified only in the jdk9. Since the jdk1.1.5 we skipped

                // NPE for some reason and therefore skipped some

                // implementations of MixerProviders, which throw NPE. To keep

                // support of such implementations, we still ignore NPE.

            }

        }

        throw new IllegalArgumentException(

                String.format("Mixer not supported: %s", info));

    }

    //$$fb 2002-11-26: fix for 4757930: DOC: AudioSystem.getTarget/SourceLineInfo() is ambiguous

    /**

     * Obtains information about all source lines of a particular type that are

     * supported by the installed mixers.

     *

     * @param  info a {@code Line.Info} object that specifies the kind of lines

     *         about which information is requested

     * @return an array of {@code Line.Info} objects describing source lines

     *         matching the type requested. If no matching source lines are

     *         supported, an array of length 0 is returned.

     * @see Mixer#getSourceLineInfo(Line.Info)

     */

    public static Line.Info[] getSourceLineInfo(Line.Info info) {

        Vector<Line.Info> vector = new Vector<>();

        Line.Info[] currentInfoArray;

        Mixer mixer;

        Line.Info fullInfo = null;

        Mixer.Info[] infoArray = getMixerInfo();

        for (int i = 0; i < infoArray.length; i++) {

            mixer = getMixer(infoArray[i]);

            currentInfoArray = mixer.getSourceLineInfo(info);

            for (int j = 0; j < currentInfoArray.length; j++) {

                vector.addElement(currentInfoArray[j]);

            }

        }

        Line.Info[] returnedArray = new Line.Info[vector.size()];

        for (int i = 0; i < returnedArray.length; i++) {

            returnedArray[i] = vector.get(i);

        }

        return returnedArray;

    }

    /**

     * Obtains information about all target lines of a particular type that are

     * supported by the installed mixers.

     *

     * @param  info a {@code Line.Info} object that specifies the kind of lines

     *         about which information is requested

     * @return an array of {@code Line.Info} objects describing target lines

     *         matching the type requested. If no matching target lines are

     *         supported, an array of length 0 is returned.

     * @see Mixer#getTargetLineInfo(Line.Info)

     */

    public static Line.Info[] getTargetLineInfo(Line.Info info) {

        Vector<Line.Info> vector = new Vector<>();

        Line.Info[] currentInfoArray;

        Mixer mixer;

        Line.Info fullInfo = null;

        Mixer.Info[] infoArray = getMixerInfo();

        for (int i = 0; i < infoArray.length; i++) {

            mixer = getMixer(infoArray[i]);

            currentInfoArray = mixer.getTargetLineInfo(info);

            for (int j = 0; j < currentInfoArray.length; j++) {

                vector.addElement(currentInfoArray[j]);

            }

        }

        Line.Info[] returnedArray = new Line.Info[vector.size()];

        for (int i = 0; i < returnedArray.length; i++) {

            returnedArray[i] = vector.get(i);

        }

        return returnedArray;

    }

    /**

     * Indicates whether the system supports any lines that match the specified

     * {@code Line.Info} object. A line is supported if any installed mixer

     * supports it.

     *

     * @param  info a {@code Line.Info} object describing the line for which

     *         support is queried

     * @return {@code true} if at least one matching line is supported,

     *         otherwise {@code false}

     * @see Mixer#isLineSupported(Line.Info)

     */

    public static boolean isLineSupported(Line.Info info) {

        Mixer mixer;

        Mixer.Info[] infoArray = getMixerInfo();

        for (int i = 0; i < infoArray.length; i++) {

            if( infoArray[i] != null ) {

                mixer = getMixer(infoArray[i]);

                if (mixer.isLineSupported(info)) {

                    return true;

                }

            }

        }

        return false;

    }

    /**

     * Obtains a line that matches the description in the specified

     * {@code Line.Info} object.

     * <p>

     * If a {@code DataLine} is requested, and {@code info} is an instance of

     * {@code DataLine.Info} specifying at least one fully qualified audio

     * format, the last one will be used as the default format of the returned

     * {@code DataLine}.

     * <p>

     * If system properties

     * {@code javax.sound.sampled.Clip},

     * {@code javax.sound.sampled.Port},

     * {@code javax.sound.sampled.SourceDataLine} and

     * {@code javax.sound.sampled.TargetDataLine} are defined or they are

     * defined in the file "sound.properties", they are used to retrieve default

     * lines. For details, refer to the {@link AudioSystem class description}.

     *

     * If the respective property is not set, or the mixer requested in the

     * property is not installed or does not provide the requested line, all

     * installed mixers are queried for the requested line type. A Line will be

     * returned from the first mixer providing the requested line type.

     *

     * @param  info a {@code Line.Info} object describing the desired kind of

     *         line

     * @return a line of the requested kind

     * @throws LineUnavailableException if a matching line is not available due

     *         to resource restrictions

     * @throws SecurityException if a matching line is not available due to

     *         security restrictions

     * @throws IllegalArgumentException if the system does not support at least

     *         one line matching the specified {@code Line.Info} object through

     *         any installed mixer

     */

    public static Line getLine(Line.Info info) throws LineUnavailableException {

        LineUnavailableException lue = null;

        List<MixerProvider> providers = getMixerProviders();

        // 1: try from default mixer for this line class

        try {

            Mixer mixer = getDefaultMixer(providers, info);

            if (mixer != null && mixer.isLineSupported(info)) {

                return mixer.getLine(info);

            }

        } catch (LineUnavailableException e) {

            lue = e;

        } catch (IllegalArgumentException iae) {

            // must not happen... but better to catch it here,

            // if plug-ins are badly written

        }

        // 2: if that doesn't work, try to find any mixing mixer

        for(int i = 0; i < providers.size(); i++) {

            MixerProvider provider = providers.get(i);

            Mixer.Info[] infos = provider.getMixerInfo();

            for (int j = 0; j < infos.length; j++) {

                try {

                    Mixer mixer = provider.getMixer(infos[j]);

                    // see if this is an appropriate mixer which can mix

                    if (isAppropriateMixer(mixer, info, true)) {

                        return mixer.getLine(info);

                    }

                } catch (LineUnavailableException e) {

                    lue = e;

                } catch (IllegalArgumentException iae) {

                    // must not happen... but better to catch it here,

                    // if plug-ins are badly written

                }

            }

        }

        // 3: if that didn't work, try to find any non-mixing mixer

        for(int i = 0; i < providers.size(); i++) {

            MixerProvider provider = providers.get(i);

            Mixer.Info[] infos = provider.getMixerInfo();

            for (int j = 0; j < infos.length; j++) {

                try {

                    Mixer mixer = provider.getMixer(infos[j]);

                    // see if this is an appropriate mixer which can mix

                    if (isAppropriateMixer(mixer, info, false)) {

                        return mixer.getLine(info);

                    }

                } catch (LineUnavailableException e) {

                    lue = e;

                } catch (IllegalArgumentException iae) {

                    // must not happen... but better to catch it here,

                    // if plug-ins are badly written

                }

            }

        }

        // if this line was supported but was not available, throw the last

        // LineUnavailableException we got (??).

        if (lue != null) {

            throw lue;

        }

        // otherwise, the requested line was not supported, so throw

        // an Illegal argument exception

        throw new IllegalArgumentException("No line matching " +

                                           info.toString() + " is supported.");

    }

    /**

     * Obtains a clip that can be used for playing back an audio file or an

     * audio stream. The returned clip will be provided by the default system

     * mixer, or, if not possible, by any other mixer installed in the system

     * that supports a {@code Clip} object.

     * <p>

     * The returned clip must be opened with the {@code open(AudioFormat)} or

     * {@code open(AudioInputStream)} method.

     * <p>

     * This is a high-level method that uses {@code getMixer} and

     * {@code getLine} internally.

     * <p>

     * If the system property {@code javax.sound.sampled.Clip} is defined or it

     * is defined in the file "sound.properties", it is used to retrieve the

     * default clip. For details, refer to the

     * {@link AudioSystem class description}.

     *

     * @return the desired clip object

     * @throws LineUnavailableException if a clip object is not available due to

     *         resource restrictions

     * @throws SecurityException if a clip object is not available due to

     *         security restrictions

     * @throws IllegalArgumentException if the system does not support at least

     *         one clip instance through any installed mixer

     * @see #getClip(Mixer.Info)

     * @since 1.5

     */

    public static Clip getClip() throws LineUnavailableException{

        AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED,

                                             AudioSystem.NOT_SPECIFIED,

                                             16, 2, 4,

                                             AudioSystem.NOT_SPECIFIED, true);

        DataLine.Info info = new DataLine.Info(Clip.class, format);

        return (Clip) AudioSystem.getLine(info);

    }

    /**

     * Obtains a clip from the specified mixer that can be used for playing back

     * an audio file or an audio stream.

     * <p>

     * The returned clip must be opened with the {@code open(AudioFormat)} or

     * {@code open(AudioInputStream)} method.

     * <p>

     * This is a high-level method that uses {@code getMixer} and

     * {@code getLine} internally.

     *

     * @param  mixerInfo a {@code Mixer.Info} object representing the desired

     *         mixer, or {@code null} for the system default mixer

     * @return a clip object from the specified mixer

     *

     * @throws LineUnavailableException if a clip is not available from this

     *         mixer due to resource restrictions

     * @throws SecurityException if a clip is not available from this mixer due

     *         to security restrictions

     * @throws IllegalArgumentException if the system does not support at least

     *         one clip through the specified mixer

     * @see #getClip()

     * @since 1.5

     */

    public static Clip getClip(Mixer.Info mixerInfo) throws LineUnavailableException{

        AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED,

                                             AudioSystem.NOT_SPECIFIED,

                                             16, 2, 4,

                                             AudioSystem.NOT_SPECIFIED, true);

        DataLine.Info info = new DataLine.Info(Clip.class, format);

        Mixer mixer = AudioSystem.getMixer(mixerInfo);

        return (Clip) mixer.getLine(info);

    }

    /**

     * Obtains a source data line that can be used for playing back audio data

     * in the format specified by the {@code AudioFormat} object. The returned

     * line will be provided by the default system mixer, or, if not possible,

     * by any other mixer installed in the system that supports a matching

     * {@code SourceDataLine} object.

     * <p>

     * The returned line should be opened with the {@code open(AudioFormat)} or

     * {@code open(AudioFormat, int)} method.

     * <p>

     * This is a high-level method that uses {@code getMixer} and

     * {@code getLine} internally.