1 /*
   2  * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sound.sampled;
  27 
  28 
  29 /**
  30  * A mixer is an audio device with one or more lines.  It need not be
  31  * designed for mixing audio signals.  A mixer that actually mixes audio
  32  * has multiple input (source) lines and at least one output (target) line.
  33  * The former are often instances of classes that implement
  34  * <code>{@link SourceDataLine}</code>,
  35  * and the latter, <code>{@link TargetDataLine}</code>.  <code>{@link Port}</code>
  36  * objects, too, are either source lines or target lines.
  37  * A mixer can accept prerecorded, loopable sound as input, by having
  38  * some of its source lines be instances of objects that implement the
  39  * <code>{@link Clip}</code> interface.
  40  * <p>
  41  * Through methods of the <code>Line</code> interface, which <code>Mixer</code> extends,
  42  * a mixer might provide a set of controls that are global to the mixer.  For example,
  43  * the mixer can have a master gain control.  These global controls are distinct
  44  * from the controls belonging to each of the mixer's individual lines.
  45  * <p>
  46  * Some mixers, especially
  47  * those with internal digital mixing capabilities, may provide
  48  * additional capabilities by implementing the <code>DataLine</code> interface.
  49  * <p>
  50  * A mixer can support synchronization of its lines.  When one line in
  51  * a synchronized group is started or stopped, the other lines in the group
  52  * automatically start or stop simultaneously with the explicitly affected one.
  53  *
  54  * @author Kara Kytle
  55  * @since 1.3
  56  */
  57 public interface Mixer extends Line {
  58 
  59     /**
  60      * Obtains information about this mixer, including the product's name,
  61      * version, vendor, etc.
  62      * @return a mixer info object that describes this mixer
  63      * @see Mixer.Info
  64      */
  65     public Info getMixerInfo();
  66 
  67 
  68     /**
  69      * Obtains information about the set of source lines supported
  70      * by this mixer.
  71      * Some source lines may only be available when this mixer is open.
  72      * @return array of <code>Line.Info</code> objects representing source lines
  73      * for this mixer.  If no source lines are supported,
  74      * an array of length 0 is returned.
  75      */
  76     public Line.Info[] getSourceLineInfo();
  77 
  78     /**
  79      * Obtains information about the set of target lines supported
  80      * by this mixer.
  81      * Some target lines may only be available when this mixer is open.
  82      * @return array of <code>Line.Info</code> objects representing target lines
  83      * for this mixer.  If no target lines are supported,
  84      * an array of length 0 is returned.
  85      */
  86     public Line.Info[] getTargetLineInfo();
  87 
  88 
  89     /**
  90      * Obtains information about source lines of a particular type supported
  91      * by the mixer.
  92      * Some source lines may only be available when this mixer is open.
  93      * @param info a <code>Line.Info</code> object describing lines about which information
  94      * is queried
  95      * @return an array of <code>Line.Info</code> objects describing source lines matching
  96      * the type requested.  If no matching source lines are supported, an array of length 0
  97      * is returned.
  98      */
  99     public Line.Info[] getSourceLineInfo(Line.Info info);
 100 
 101 
 102     /**
 103      * Obtains information about target lines of a particular type supported
 104      * by the mixer.
 105      * Some target lines may only be available when this mixer is open.
 106      * @param info a <code>Line.Info</code> object describing lines about which information
 107      * is queried
 108      * @return an array of <code>Line.Info</code> objects describing target lines matching
 109      * the type requested.  If no matching target lines are supported, an array of length 0
 110      * is returned.
 111      */
 112     public Line.Info[] getTargetLineInfo(Line.Info info);
 113 
 114 
 115     /**
 116      * Indicates whether the mixer supports a line (or lines) that match
 117      * the specified <code>Line.Info</code> object.
 118      * Some lines may only be supported when this mixer is open.
 119      * @param info describes the line for which support is queried
 120      * @return <code>true</code> if at least one matching line is
 121      * supported, <code>false</code> otherwise
 122      */
 123     public boolean isLineSupported(Line.Info info);
 124 
 125     /**
 126      * Obtains a line that is available for use and that matches the description
 127      * in the specified <code>Line.Info</code> object.
 128      *
 129      * <p>If a <code>DataLine</code> is requested, and <code>info</code>
 130      * is an instance of <code>DataLine.Info</code> specifying at
 131      * least one fully qualified audio format, the last one
 132      * will be used as the default format of the returned
 133      * <code>DataLine</code>.
 134      *
 135      * @param info describes the desired line
 136      * @throws LineUnavailableException if a matching line
 137      * is not available due to resource restrictions
 138      * @throws IllegalArgumentException if this mixer does
 139      * not support any lines matching the description
 140      * @throws SecurityException if a matching line
 141      * is not available due to security restrictions
 142      */
 143     public Line getLine(Line.Info info) throws LineUnavailableException;
 144 
 145     //$$fb 2002-04-12: fix for 4667258: behavior of Mixer.getMaxLines(Line.Info) method doesn't match the spec
 146     /**
 147      * Obtains the approximate maximum number of lines of the requested type that can be open
 148      * simultaneously on the mixer.
 149      *
 150      * Certain types of mixers do not have a hard bound and may allow opening more lines.
 151      * Since certain lines are a shared resource, a mixer may not be able to open the maximum
 152      * number of lines if another process has opened lines of this mixer.
 153      *
 154      * The requested type is any line that matches the description in
 155      * the provided <code>Line.Info</code> object.  For example, if the info
 156      * object represents a speaker
 157      * port, and the mixer supports exactly one speaker port, this method
 158      * should return 1.  If the info object represents a source data line
 159      * and the mixer supports the use of 32 source data lines simultaneously,
 160      * the return value should be 32.
 161      * If there is no limit, this function returns <code>AudioSystem.NOT_SPECIFIED</code>.
 162      * @param info a <code>Line.Info</code> that describes the line for which
 163      * the number of supported instances is queried
 164      * @return the maximum number of matching lines supported, or <code>AudioSystem.NOT_SPECIFIED</code>
 165      */
 166     public int getMaxLines(Line.Info info);
 167 
 168 
 169     /**
 170      * Obtains the set of all source lines currently open to this mixer.
 171      *
 172      * @return the source lines currently open to the mixer.
 173      * If no source lines are currently open to this mixer,  an
 174      * array of length 0 is returned.
 175      * @throws SecurityException if the matching lines
 176      * are not available due to security restrictions
 177      */
 178     public Line[] getSourceLines();
 179 
 180     /**
 181      * Obtains the set of all target lines currently open from this mixer.
 182      *
 183      * @return target lines currently open from the mixer.
 184      * If no target lines are currently open from this mixer, an
 185      * array of length 0 is returned.
 186      * @throws SecurityException if the matching lines
 187      * are not available due to security restrictions
 188      */
 189     public Line[] getTargetLines();
 190 
 191     /**
 192      * Synchronizes two or more lines.  Any subsequent command that starts or stops
 193      * audio playback or capture for one of these lines will exert the
 194      * same effect on the other lines in the group, so that they start or stop playing or
 195      * capturing data simultaneously.
 196      *
 197      * @param lines the lines that should be synchronized
 198      * @param maintainSync <code>true</code> if the synchronization
 199      * must be precisely maintained (i.e., the synchronization must be sample-accurate)
 200      * at all times during operation of the lines , or <code>false</code>
 201      * if precise synchronization is required only during start and stop operations
 202      *
 203      * @throws IllegalArgumentException if the lines cannot be synchronized.
 204      * This may occur if the lines are of different types or have different
 205      * formats for which this mixer does not support synchronization, or if
 206      * all lines specified do not belong to this mixer.
 207      */
 208     public void synchronize(Line[] lines, boolean maintainSync);
 209 
 210     /**
 211      * Releases synchronization for the specified lines.  The array must
 212      * be identical to one for which synchronization has already been
 213      * established; otherwise an exception may be thrown.  However, <code>null</code>
 214      * may be specified, in which case all currently synchronized lines that belong
 215      * to this mixer are unsynchronized.
 216      * @param lines the synchronized lines for which synchronization should be
 217      * released, or <code>null</code> for all this mixer's synchronized lines
 218      *
 219      * @throws IllegalArgumentException if the lines cannot be unsynchronized.
 220      * This may occur if the argument specified does not exactly match a set
 221      * of lines for which synchronization has already been established.
 222      */
 223     public void unsynchronize(Line[] lines);
 224 
 225 
 226     /**
 227      * Reports whether this mixer supports synchronization of the specified set of lines.
 228      *
 229      * @param lines the set of lines for which synchronization support is queried
 230      * @param maintainSync <code>true</code> if the synchronization
 231      * must be precisely maintained (i.e., the synchronization must be sample-accurate)
 232      * at all times during operation of the lines , or <code>false</code>
 233      * if precise synchronization is required only during start and stop operations
 234      *
 235      * @return <code>true</code> if the lines can be synchronized, <code>false</code>
 236      * otherwise
 237      */
 238     public boolean isSynchronizationSupported(Line[] lines, boolean maintainSync);
 239 
 240 
 241     /**
 242      * The <code>Mixer.Info</code> class represents information about an audio mixer,
 243      * including the product's name, version, and vendor, along with a textual
 244      * description.  This information may be retrieved through the
 245      * {@link Mixer#getMixerInfo() getMixerInfo}
 246      * method of the <code>Mixer</code> interface.
 247      *
 248      * @author Kara Kytle
 249      * @since 1.3
 250      */
 251     public static class Info {
 252 
 253         /**
 254          * Mixer name.
 255          */
 256         private final String name;
 257 
 258         /**
 259          * Mixer vendor.
 260          */
 261         private final String vendor;
 262 
 263         /**
 264          * Mixer description.
 265          */
 266         private final String description;
 267 
 268         /**
 269          * Mixer version.
 270          */
 271         private final String version;
 272 
 273         /**
 274          * Constructs a mixer's info object, passing it the given
 275          * textual information.
 276          * @param name the name of the mixer
 277          * @param vendor the company who manufactures or creates the hardware
 278          * or software mixer
 279          * @param description descriptive text about the mixer
 280          * @param version version information for the mixer
 281          */
 282         protected Info(String name, String vendor, String description, String version) {
 283 
 284             this.name = name;
 285             this.vendor = vendor;
 286             this.description = description;
 287             this.version = version;
 288         }
 289 
 290 
 291         /**
 292          * Indicates whether two info objects are equal, returning <code>true</code> if
 293          * they are identical.
 294          * @param obj the reference object with which to compare this info
 295          * object
 296          * @return <code>true</code> if this info object is the same as the
 297          * <code>obj</code> argument; <code>false</code> otherwise
 298          */
 299         public final boolean equals(Object obj) {
 300             return super.equals(obj);
 301         }
 302 
 303         /**
 304          * Finalizes the hashcode method.
 305          *
 306          * @return the hashcode for this object
 307          */
 308         public final int hashCode() {
 309             return super.hashCode();
 310         }
 311 
 312         /**
 313          * Obtains the name of the mixer.
 314          * @return a string that names the mixer
 315          */
 316         public final String getName() {
 317             return name;
 318         }
 319 
 320         /**
 321          * Obtains the vendor of the mixer.
 322          * @return a string that names the mixer's vendor
 323          */
 324         public final String getVendor() {
 325             return vendor;
 326         }
 327 
 328         /**
 329          * Obtains the description of the mixer.
 330          * @return a textual description of the mixer
 331          */
 332         public final String getDescription() {
 333             return description;
 334         }
 335 
 336         /**
 337          * Obtains the version of the mixer.
 338          * @return textual version information for the mixer
 339          */
 340         public final String getVersion() {
 341             return version;
 342         }
 343 
 344         /**
 345          * Provides a string representation of the mixer info.
 346          * @return a string describing the info object
 347          */
 348         public final String toString() {
 349             return (name + ", version " + version);
 350         }
 351     } // class Info
 352 }