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