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