/*
 * @(#)MidiChannel.java	1.44 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.sound.midi;


/**
 * A <code>MidiChannel</code> object represents a single MIDI channel.
 * Generally, each <code>MidiChannel</code> method processes a like-named MIDI
 * "channel voice" or "channel mode" message as defined by the MIDI specification. However,
 * <code>MidiChannel</code> adds some "get" methods  that retrieve the value
 * most recently set by one of the standard MIDI channel messages.  Similarly,
 * methods for per-channel solo and mute have been added.
 * <p>
 * A <code>{@link Synthesizer}</code> object has a collection
 * of <code>MidiChannels</code>, usually one for each of the 16 channels
 * prescribed by the MIDI 1.0 specification.  The <code>Synthesizer</code>
 * generates sound when its <code>MidiChannels</code> receive
 * <code>noteOn</code> messages.
 * <p>
 * See the MIDI 1.0 Specification for more information about the prescribed
 * behavior of the MIDI channel messages, which are not exhaustively
 * documented here.  The specification is titled <code>MIDI Reference:
 * The Complete MIDI 1.0 Detailed Specification</code>, and is published by
 * the MIDI Manufacturer's Association (<a href = http://www.midi.org>
 * http://www.midi.org</a>).
 * <p>
 * MIDI was originally a protocol for reporting the gestures of a keyboard
 * musician.  This genesis is visible in the <code>MidiChannel</code> API, which
 * preserves such MIDI concepts as key number, key velocity, and key pressure.
 * It should be understood that the MIDI data does not necessarily originate
 * with a keyboard player (the source could be a different kind of musician, or
 * software).  Some devices might generate constant values for velocity
 * and pressure, regardless of how the note was performed.
 * Also, the MIDI specification often leaves it up to the
 * synthesizer to use the data in the way the implementor sees fit.  For
 * example, velocity data need not always be mapped to volume and/or brightness.
 *
 * @see Synthesizer#getChannels
 *
 * @version 1.44, 11/17/05
 * @author David Rivas
 * @author Kara Kytle
 */

public interface MidiChannel {

    /**
     * Starts the specified note sounding.  The key-down velocity
     * usually controls the note's volume and/or brightness.
     * If <code>velocity</code> is zero, this method instead acts like
     * {@link #noteOff(int)}, terminating the note.
     *
     * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C)
     * @param velocity the speed with which the key was depressed
     *
     * @see #noteOff(int, int)
     */
    public void noteOn(int noteNumber, int velocity);

    /**
     * Turns the specified note off.  The key-up velocity, if not ignored, can
     * be used to affect how quickly the note decays.
     * In any case, the note might not die away instantaneously; its decay
     * rate is determined by the internals of the <code>Instrument</code>.
     * If the Hold Pedal (a controller; see
     * {@link #controlChange(int, int) controlChange})
     * is down, the effect of this method is deferred until the pedal is
     * released.
     *
     *
     * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C)
     * @param velocity the speed with which the key was released
     *
     * @see #noteOff(int)
     * @see #noteOn
     * @see #allNotesOff
     * @see #allSoundOff
     */
    public void noteOff(int noteNumber, int velocity);

    /**
     * Turns the specified note off.
     *
     * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C)
     *
     * @see #noteOff(int, int)
     */
    public void noteOff(int noteNumber);

    /**
     * Reacts to a change in the specified note's key pressure.
     * Polyphonic key pressure
     * allows a keyboard player to press multiple keys simultaneously, each
     * with a different amount of pressure.  The pressure, if not ignored,
     * is typically used to vary such features as the volume, brightness,