1 /*
   2  * Copyright (c) 1998, 2002, 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 /**
  30  * A <code>VoiceStatus</code> object contains information about the current
  31  * status of one of the voices produced by a {@link Synthesizer}.
  32  * <p>
  33  * MIDI synthesizers are generally capable of producing some maximum number of
  34  * simultaneous notes, also referred to as voices.  A voice is a stream
  35  * of successive single notes, and the process of assigning incoming MIDI notes to
  36  * specific voices is known as voice allocation.
  37  * However, the voice-allocation algorithm and the contents of each voice are
  38  * normally internal to a MIDI synthesizer and hidden from outside view.  One can, of
  39  * course, learn from MIDI messages which notes the synthesizer is playing, and
  40  * one might be able deduce something about the assignment of notes to voices.
  41  * But MIDI itself does not provide a means to report which notes a
  42  * synthesizer has assigned to which voice, nor even to report how many voices
  43  * the synthesizer is capable of synthesizing.
  44  * <p>
  45  * In Java Sound, however, a
  46  * <code>Synthesizer</code> class can expose the contents of its voices through its
  47  * {@link Synthesizer#getVoiceStatus() getVoiceStatus()} method.
  48  * This behavior is recommended but optional;
  49  * synthesizers that don't expose their voice allocation simply return a
  50  * zero-length array. A <code>Synthesizer</code> that does report its voice status
  51  * should maintain this information at
  52  * all times for all of its voices, whether they are currently sounding or
  53  * not.  In other words, a given type of <code>Synthesizer</code> always has a fixed
  54  * number of voices, equal to the maximum number of simultaneous notes it is
  55  * capable of sounding.
  56  * <p>
  57  * <A NAME="description_of_active"></A>
  58  * If the voice is not currently processing a MIDI note, it
  59  * is considered inactive.  A voice is inactive when it has
  60  * been given no note-on commands, or when every note-on command received has
  61  * been terminated by a corresponding note-off (or by an "all notes off"
  62  * message).  For example, this happens when a synthesizer capable of playing 16
  63  * simultaneous notes is told to play a four-note chord; only
  64  * four voices are active in this case (assuming no earlier notes are still playing).
  65  * Usually, a voice whose status is reported as active is producing audible sound, but this
  66  * is not always true; it depends on the details of the instrument (that
  67  * is, the synthesis algorithm) and how long the note has been going on.
  68  * For example, a voice may be synthesizing the sound of a single hand-clap.  Because
  69  * this sound dies away so quickly, it may become inaudible before a note-off
  70  * message is received.  In such a situation, the voice is still considered active
  71  * even though no sound is currently being produced.
  72  * <p>
  73  * Besides its active or inactive status, the <code>VoiceStatus</code> class
  74  * provides fields that reveal the voice's current MIDI channel, bank and
  75  * program number, MIDI note number, and MIDI volume.  All of these can
  76  * change during the course of a voice.  While the voice is inactive, each
  77  * of these fields has an unspecified value, so you should check the active
  78  * field first.
  79  *
  80  * @see Synthesizer#getMaxPolyphony
  81  * @see Synthesizer#getVoiceStatus
  82  *
  83  * @author David Rivas
  84  * @author Kara Kytle
  85  */
  86 
  87 public class VoiceStatus {
  88 
  89 
  90     /**
  91      * Indicates whether the voice is currently processing a MIDI note.
  92      * See the explanation of
  93      * <A HREF="#description_of_active">active and inactive voices</A>.
  94      */
  95     public boolean active = false;
  96 
  97 
  98     /**
  99      * The MIDI channel on which this voice is playing.  The value is a
 100      * zero-based channel number if the voice is active, or
 101      * unspecified if the voice is inactive.
 102      *
 103      * @see MidiChannel
 104      * @see #active
 105      */
 106     public int channel = 0;
 107 
 108 
 109     /**
 110      * The bank number of the instrument that this voice is currently using.
 111      * This is a number dictated by the MIDI bank-select message; it does not
 112      * refer to a <code>SoundBank</code> object.
 113      * The value ranges from 0 to 16383 if the voice is active, and is
 114      * unspecified if the voice is inactive.
 115      * @see Patch
 116      * @see Soundbank
 117      * @see #active
 118      * @see MidiChannel#programChange(int, int)
 119      */
 120     public int bank = 0;
 121 
 122 
 123     /**
 124      * The program number of the instrument that this voice is currently using.
 125      * The value ranges from 0 to 127 if the voice is active, and is
 126      * unspecified if the voice is inactive.
 127      *
 128      * @see MidiChannel#getProgram
 129      * @see Patch
 130      * @see #active
 131      */
 132     public int program = 0;
 133 
 134 
 135     /**
 136      * The MIDI note that this voice is playing.  The range for an active voice
 137      * is from 0 to 127 in semitones, with 60 referring to Middle C.
 138      * The value is unspecified if the voice is inactive.
 139      *
 140      * @see MidiChannel#noteOn
 141      * @see #active
 142      */
 143     public int note = 0;
 144 
 145 
 146     /**
 147      * The current MIDI volume level for the voice.
 148      * The value ranges from 0 to 127 if the voice is active, and is
 149      * unspecified if the voice is inactive.
 150      * <p>
 151      * Note that this value does not necessarily reflect
 152      * the instantaneous level of the sound produced by this
 153      * voice; that level is the result of  many contributing
 154      * factors, including the current instrument and the
 155      * shape of the amplitude envelope it produces.
 156      *
 157      * @see #active
 158      */
 159     public int volume = 0;
 160 }