View Javadoc
1   /*
2    * Copyright (c) 2007, 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  package com.sun.media.sound;
26  
27  import java.util.Map;
28  import javax.sound.midi.MidiUnavailableException;
29  import javax.sound.midi.Synthesizer;
30  import javax.sound.sampled.AudioFormat;
31  import javax.sound.sampled.AudioInputStream;
32  import javax.sound.sampled.SourceDataLine;
33  
34  /**
35   * <code>AudioSynthesizer</code> is a <code>Synthesizer</code>
36   * which renders it's output audio into <code>SourceDataLine</code>
37   * or <code>AudioInputStream</code>.
38   *
39   * @see MidiSystem#getSynthesizer
40   * @see Synthesizer
41   *
42   * @author Karl Helgason
43   */
44  public interface AudioSynthesizer extends Synthesizer {
45  
46      /**
47       * Obtains the current format (encoding, sample rate, number of channels,
48       * etc.) of the synthesizer audio data.
49       *
50       * <p>If the synthesizer is not open and has never been opened, it returns
51       * the default format.
52       *
53       * @return current audio data format
54       * @see AudioFormat
55       */
56      public AudioFormat getFormat();
57  
58      /**
59       * Gets information about the possible properties for the synthesizer.
60       *
61       * @param info a proposed list of tag/value pairs that will be sent on open.
62       * @return an array of <code>AudioSynthesizerPropertyInfo</code> objects
63       * describing possible properties. This array may be an empty array if
64       * no properties are required.
65       */
66      public AudioSynthesizerPropertyInfo[] getPropertyInfo(
67              Map<String, Object> info);
68  
69      /**
70       * Opens the synthesizer and starts rendering audio into
71       * <code>SourceDataLine</code>.
72       *
73       * <p>An application opening a synthesizer explicitly with this call
74       * has to close the synthesizer by calling {@link #close}. This is
75       * necessary to release system resources and allow applications to
76       * exit cleanly.
77       *
78       * <p>Note that some synthesizers, once closed, cannot be reopened.
79       * Attempts to reopen such a synthesizer will always result in
80       * a <code>MidiUnavailableException</code>.
81       *
82       * @param line which <code>AudioSynthesizer</code> writes output audio into.
83       * If <code>line</code> is null, then line from system default mixer is used.
84       * @param info a <code>Map<String,Object></code> object containing
85       * properties for additional configuration supported by synthesizer.
86       * If <code>info</code> is null then default settings are used.
87       *
88       * @throws MidiUnavailableException thrown if the synthesizer cannot be
89       * opened due to resource restrictions.
90       * @throws SecurityException thrown if the synthesizer cannot be
91       * opened due to security restrictions.
92       *
93       * @see #close
94       * @see #isOpen
95       */
96      public void open(SourceDataLine line, Map<String, Object> info)
97              throws MidiUnavailableException;
98  
99      /**
100      * Opens the synthesizer and renders audio into returned
101      * <code>AudioInputStream</code>.
102      *
103      * <p>An application opening a synthesizer explicitly with this call
104      * has to close the synthesizer by calling {@link #close}. This is
105      * necessary to release system resources and allow applications to
106      * exit cleanly.
107      *
108      * <p>Note that some synthesizers, once closed, cannot be reopened.
109      * Attempts to reopen such a synthesizer will always result in
110      * a <code>MidiUnavailableException<code>.
111      *
112      * @param targetFormat specifies the <code>AudioFormat</code>
113      * used in returned <code>AudioInputStream</code>.
114      * @param info a <code>Map<String,Object></code> object containing
115      * properties for additional configuration supported by synthesizer.
116      * If <code>info</code> is null then default settings are used.
117      *
118      * @throws MidiUnavailableException thrown if the synthesizer cannot be
119      * opened due to resource restrictions.
120      * @throws SecurityException thrown if the synthesizer cannot be
121      * opened due to security restrictions.
122      *
123      * @see #close
124      * @see #isOpen
125      */
126     public AudioInputStream openStream(AudioFormat targetFormat,
127             Map<String, Object> info) throws MidiUnavailableException;
128 }