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 } --- EOF ---