/*

 * Copyright 1998-2003 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.sound.midi;

import java.net.URL;

/**

 * A <code>Soundbank</code> contains a set of <code>Instruments</code>

 * that can be loaded into a <code>Synthesizer</code>.

 * Note that a Java Sound <code>Soundbank</code> is different from a MIDI bank.

 * MIDI permits up to 16383 banks, each containing up to 128 instruments

 * (also sometimes called programs, patches, or timbres).

 * However, a <code>Soundbank</code> can contain 16383 times 128 instruments,

 * because the instruments within a <code>Soundbank</code> are indexed by both

 * a MIDI program number and a MIDI bank number (via a <code>Patch</code>

 * object). Thus, a <code>Soundbank</code> can be thought of as a collection

 * of MIDI banks.

 * <p>

 * <code>Soundbank</code> includes methods that return <code>String</code>

 * objects containing the sound bank's name, manufacturer, version number, and

 * description.  The precise content and format of these strings is left

 * to the implementor.

 * <p>

 * Different synthesizers use a variety of synthesis techniques.  A common

 * one is wavetable synthesis, in which a segment of recorded sound is

 * played back, often with looping and pitch change.  The Downloadable Sound

 * (DLS) format uses segments of recorded sound, as does the Headspace Engine.

 * <code>Soundbanks</code> and <code>Instruments</code> that are based on

 * wavetable synthesis (or other uses of stored sound recordings) should

 * typically implement the <code>getResources()</code>

 * method to provide access to these recorded segments.  This is optional,

 * however; the method can return an zero-length array if the synthesis technique

 * doesn't use sampled sound (FM synthesis and physical modeling are examples

 * of such techniques), or if it does but the implementor chooses not to make the

 * samples accessible.

 *

 * @see Synthesizer#getDefaultSoundbank

 * @see Synthesizer#isSoundbankSupported

 * @see Synthesizer#loadInstruments(Soundbank, Patch[])

 * @see Patch

 * @see Instrument

 * @see SoundbankResource

 *

 * @author David Rivas

 * @author Kara Kytle

 */

public interface Soundbank {

    /**

     * Obtains the name of the sound bank.

     * @return a <code>String</code> naming the sound bank

     */

    public String getName();

    /**

     * Obtains the version string for the sound bank.

     * @return a <code>String</code> that indicates the sound bank's version

     */

    public String getVersion();

    /**

     * Obtains a <code>string</code> naming the company that provides the

     * sound bank

     * @return the vendor string

     */

    public String getVendor();

    /**

     * Obtains a textual description of the sound bank, suitable for display.

     * @return a <code>String</code> that describes the sound bank

     */

    public String getDescription();

    /**

     * Extracts a list of non-Instrument resources contained in the sound bank.

     * @return an array of resources, exclusing instruments.  If the sound bank contains

     * no resources (other than instruments), returns an array of length 0.

     */

    public SoundbankResource[] getResources();

    /**

     * Obtains a list of instruments contained in this sound bank.

     * @return an array of the <code>Instruments</code> in this

     * <code>SoundBank</code>

     * If the sound bank contains no instruments, returns an array of length 0.

     *

     * @see Synthesizer#getLoadedInstruments

     * @see #getInstrument(Patch)

     */

    public Instrument[] getInstruments();

    /**

     * Obtains an <code>Instrument</code> from the given <code>Patch</code>.

     * @param patch a <code>Patch</code> object specifying the bank index

     * and program change number

     * @return the requested instrument, or <code>null</code> if the

     * sound bank doesn't contain that instrument

     *

     * @see #getInstruments

     * @see Synthesizer#loadInstruments(Soundbank, Patch[])

     */

    public Instrument getInstrument(Patch patch);

}