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