1 /* 2 * Copyright (c) 1998, 2014, 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.midi; 27 28 /** 29 * A {@code Soundbank} contains a set of {@code Instruments} that can be loaded 30 * into a {@code Synthesizer}. Note that a Java Sound {@code Soundbank} is 31 * different from a MIDI bank. MIDI permits up to 16383 banks, each containing 32 * up to 128 instruments (also sometimes called programs, patches, or timbres). 33 * However, a {@code Soundbank} can contain 16383 times 128 instruments, because 34 * the instruments within a {@code Soundbank} are indexed by both a MIDI program 35 * number and a MIDI bank number (via a {@code Patch} object). Thus, a 36 * {@code Soundbank} can be thought of as a collection of MIDI banks. 37 * <p> 38 * {@code Soundbank} includes methods that return {@code String} objects 39 * containing the sound bank's name, manufacturer, version number, and 40 * description. The precise content and format of these strings is left to the 41 * implementor. 42 * <p> 43 * Different synthesizers use a variety of synthesis techniques. A common one is 44 * wavetable synthesis, in which a segment of recorded sound is played back, 45 * often with looping and pitch change. The Downloadable Sound (DLS) format uses 46 * segments of recorded sound, as does the Headspace Engine. {@code Soundbanks} 47 * and {@code Instruments} that are based on wavetable synthesis (or other uses 48 * of stored sound recordings) should typically implement the 49 * {@code getResources()} method to provide access to these recorded segments. 50 * This is optional, however; the method can return an zero-length array if the 51 * synthesis technique doesn't use sampled sound (FM synthesis and physical 52 * modeling are examples of such techniques), or if it does but the implementor 53 * chooses not to make the samples accessible. 54 * 55 * @author David Rivas 56 * @author Kara Kytle 57 * @see Synthesizer#getDefaultSoundbank 58 * @see Synthesizer#isSoundbankSupported 59 * @see Synthesizer#loadInstruments(Soundbank, Patch[]) 60 * @see Patch 61 * @see Instrument 62 * @see SoundbankResource 63 */ 64 public interface Soundbank { 65 66 /** 67 * Obtains the name of the sound bank. 68 * 69 * @return a {@code String} naming the sound bank 70 */ 71 String getName(); 72 73 /** 74 * Obtains the version string for the sound bank. 75 * 76 * @return a {@code String} that indicates the sound bank's version 77 */ 78 String getVersion(); 79 80 /** 81 * Obtains a {@code string} naming the company that provides the sound bank. 82 * 83 * @return the vendor string 84 */ 85 String getVendor(); 86 87 /** 88 * Obtains a textual description of the sound bank, suitable for display. 89 * 90 * @return a {@code String} that describes the sound bank 91 */ 92 String getDescription(); 93 94 /** 95 * Extracts a list of non-Instrument resources contained in the sound bank. 96 * 97 * @return an array of resources, excluding instruments. If the sound bank 98 * contains no resources (other than instruments), returns an array 99 * of length 0. 100 */ 101 SoundbankResource[] getResources(); 102 103 /** 104 * Obtains a list of instruments contained in this sound bank. 105 * 106 * @return an array of the {@code Instruments} in this {@code SoundBank}. If 107 * the sound bank contains no instruments, returns an array of 108 * length 0. 109 * @see Synthesizer#getLoadedInstruments 110 * @see #getInstrument(Patch) 111 */ 112 Instrument[] getInstruments(); 113 114 /** 115 * Obtains an {@code Instrument} from the given {@code Patch}. 116 * 117 * @param patch a {@code Patch} object specifying the bank index and 118 * program change number 119 * @return the requested instrument, or {@code null} if the sound bank 120 * doesn't contain that instrument 121 * @see #getInstruments 122 * @see Synthesizer#loadInstruments(Soundbank, Patch[]) 123 */ 124 Instrument getInstrument(Patch patch); 125 }