/*
 * @(#)Mixer.java	1.32 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.sound.sampled;


/**
 * A mixer is an audio device with one or more lines.  It need not be
 * designed for mixing audio signals.  A mixer that actually mixes audio
 * has multiple input (source) lines and at least one output (target) line.
 * The former are often instances of classes that implement
 * <code>{@link SourceDataLine}</code>,
 * and the latter, <code>{@link TargetDataLine}</code>.  <code>{@link Port}</code>
 * objects, too, are either source lines or target lines.
 * A mixer can accept prerecorded, loopable sound as input, by having
 * some of its source lines be instances of objects that implement the
 * <code>{@link Clip}</code> interface.
 * <p>
 * Through methods of the <code>Line</code> interface, which <code>Mixer</code> extends,
 * a mixer might provide a set of controls that are global to the mixer.  For example,
 * the mixer can have a master gain control.  These global controls are distinct
 * from the controls belonging to each of the mixer's individual lines.
 * <p>
 * Some mixers, especially
 * those with internal digital mixing capabilities, may provide
 * additional capabilities by implementing the <code>DataLine</code> interface.
 * <p>
 * A mixer can support synchronization of its lines.  When one line in
 * a synchronized group is started or stopped, the other lines in the group
 * automatically start or stop simultaneously with the explicitly affected one.
 *
 * @author Kara Kytle
 * @version 1.32, 05/11/17
 * @since 1.3
 */
public interface Mixer extends Line {

    /**
     * Obtains information about this mixer, including the product's name,
     * version, vendor, etc.
     * @return a mixer info object that describes this mixer
     * @see Mixer.Info
     */
    public Info getMixerInfo();


    /**
     * Obtains information about the set of source lines supported
     * by this mixer.
     * Some source lines may only be available when this mixer is open.
     * @return array of <code>Line.Info</code> objects representing source lines
     * for this mixer.  If no source lines are supported,
     * an array of length 0 is returned.
     */
    public Line.Info[] getSourceLineInfo();

    /**
     * Obtains information about the set of target lines supported
     * by this mixer.
     * Some target lines may only be available when this mixer is open.
     * @return array of <code>Line.Info</code> objects representing target lines
     * for this mixer.  If no target lines are supported,
     * an array of length 0 is returned.
     */
    public Line.Info[] getTargetLineInfo();


    /**
     * Obtains information about source lines of a particular type supported
     * by the mixer.
     * Some source lines may only be available when this mixer is open.
     * @param info a <code>Line.Info</code> object describing lines about which information
     * is queried
     * @return an array of <code>Line.Info</code> objects describing source lines matching
     * the type requested.  If no matching source lines are supported, an array of length 0
     * is returned.
     */
    public Line.Info[] getSourceLineInfo(Line.Info info);


    /**
     * Obtains information about target lines of a particular type supported
     * by the mixer.
     * Some target lines may only be available when this mixer is open.
     * @param info a <code>Line.Info</code> object describing lines about which information
     * is queried
     * @return an array of <code>Line.Info</code> objects describing target lines matching
     * the type requested.  If no matching target lines are supported, an array of length 0
     * is returned.
     */
    public Line.Info[] getTargetLineInfo(Line.Info info);


    /**
     * Indicates whether the mixer supports a line (or lines) that match
     * the specified <code>Line.Info</code> object.