KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > sound > midi > VoiceStatus


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