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