Mixer


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