View Javadoc
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 }