1 /*
2 * Copyright 1998-2004 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.sound.midi;
27
28
29 /**
30 * A <code>MidiChannel</code> object represents a single MIDI channel.
31 * Generally, each <code>MidiChannel</code> method processes a like-named MIDI
32 * "channel voice" or "channel mode" message as defined by the MIDI specification. However,
33 * <code>MidiChannel</code> adds some "get" methods that retrieve the value
34 * most recently set by one of the standard MIDI channel messages. Similarly,
35 * methods for per-channel solo and mute have been added.
36 * <p>
37 * A <code>{@link Synthesizer}</code> object has a collection
38 * of <code>MidiChannels</code>, usually one for each of the 16 channels
39 * prescribed by the MIDI 1.0 specification. The <code>Synthesizer</code>
40 * generates sound when its <code>MidiChannels</code> receive
41 * <code>noteOn</code> messages.
42 * <p>
43 * See the MIDI 1.0 Specification for more information about the prescribed
44 * behavior of the MIDI channel messages, which are not exhaustively
45 * documented here. The specification is titled <code>MIDI Reference:
46 * The Complete MIDI 1.0 Detailed Specification</code>, and is published by
47 * the MIDI Manufacturer's Association (<a href = http://www.midi.org>
48 * http://www.midi.org</a>).
49 * <p>
50 * MIDI was originally a protocol for reporting the gestures of a keyboard
51 * musician. This genesis is visible in the <code>MidiChannel</code> API, which
52 * preserves such MIDI concepts as key number, key velocity, and key pressure.
53 * It should be understood that the MIDI data does not necessarily originate
54 * with a keyboard player (the source could be a different kind of musician, or
55 * software). Some devices might generate constant values for velocity
56 * and pressure, regardless of how the note was performed.
57 * Also, the MIDI specification often leaves it up to the
58 * synthesizer to use the data in the way the implementor sees fit. For
59 * example, velocity data need not always be mapped to volume and/or brightness.
60 *
61 * @see Synthesizer#getChannels
62 *
63 * @author David Rivas
64 * @author Kara Kytle
65 */
66
67 public interface MidiChannel {
68
69 /**
70 * Starts the specified note sounding. The key-down velocity
71 * usually controls the note's volume and/or brightness.
72 * If <code>velocity</code> is zero, this method instead acts like
73 * {@link #noteOff(int)}, terminating the note.
74 *
75 * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C)
76 * @param velocity the speed with which the key was depressed
77 *
78 * @see #noteOff(int, int)
79 */
80 public void noteOn(int noteNumber, int velocity);
81
82 /**
83 * Turns the specified note off. The key-up velocity, if not ignored, can
84 * be used to affect how quickly the note decays.
85 * In any case, the note might not die away instantaneously; its decay
86 * rate is determined by the internals of the <code>Instrument</code>.
87 * If the Hold Pedal (a controller; see
88 * {@link #controlChange(int, int) controlChange})
89 * is down, the effect of this method is deferred until the pedal is
90 * released.
91 *
92 *
93 * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C)
94 * @param velocity the speed with which the key was released
95 *
96 * @see #noteOff(int)
97 * @see #noteOn
98 * @see #allNotesOff
99 * @see #allSoundOff
100 */
101 public void noteOff(int noteNumber, int velocity);
102
103 /**
104 * Turns the specified note off.
105 *
106 * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C)
107 *
108 * @see #noteOff(int, int)
109 */
110 public void noteOff(int noteNumber);
111
112 /**
113 * Reacts to a change in the specified note's key pressure.
114 * Polyphonic key pressure
115 * allows a keyboard player to press multiple keys simultaneously, each
116 * with a different amount of pressure. The pressure, if not ignored,
117 * is typically used to vary such features as the volume, brightness,
118 * or vibrato of the note.
119 *
120 * It is possible that the underlying synthesizer
121 * does not support this MIDI message. In order
122 * to verify that <code>setPolyPressure</code>
123 * was successful, use <code>getPolyPressure</code>.
124 *
125 * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C)
126 * @param pressure value for the specified key, from 0 to 127 (127 =
127 * maximum pressure)
128 *
129 * @see #getPolyPressure(int)
130 */
131 public void setPolyPressure(int noteNumber, int pressure);
132
133 /**
134 * Obtains the pressure with which the specified key is being depressed.
135 *
136 * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C)
137 *
138 * If the device does not support setting poly pressure,
139 * this method always returns 0. Calling
140 * <code>setPolyPressure</code> will have no effect then.
141 *
142 * @return the amount of pressure for that note, from 0 to 127
143 * (127 = maximum pressure)
144 *
145 * @see #setPolyPressure(int, int)
146 */
147 public int getPolyPressure(int noteNumber);
148
149 /**
150 * Reacts to a change in the keyboard pressure. Channel
151 * pressure indicates how hard the keyboard player is depressing
152 * the entire keyboard. This can be the maximum or
153 * average of the per-key pressure-sensor values, as set by
154 * <code>setPolyPressure</code>. More commonly, it is a measurement of
155 * a single sensor on a device that doesn't implement polyphonic key
156 * pressure. Pressure can be used to control various aspects of the sound,
157 * as described under {@link #setPolyPressure(int, int) setPolyPressure}.
158 *
159 * It is possible that the underlying synthesizer
160 * does not support this MIDI message. In order
161 * to verify that <code>setChannelPressure</code>
162 * was successful, use <code>getChannelPressure</code>.
163 *
164 * @param pressure the pressure with which the keyboard is being depressed,
165 * from 0 to 127 (127 = maximum pressure)
166 * @see #setPolyPressure(int, int)
167 * @see #getChannelPressure
168 */
169 public void setChannelPressure(int pressure);
170
171 /**
172 * Obtains the channel's keyboard pressure.
173 * If the device does not support setting channel pressure,
174 * this method always returns 0. Calling
175 * <code>setChannelPressure</code> will have no effect then.
176 *
177 * @return the amount of pressure for that note,
178 * from 0 to 127 (127 = maximum pressure)
179 *
180 * @see #setChannelPressure(int)
181 */
182 public int getChannelPressure();
183
184 /**
185 * Reacts to a change in the specified controller's value. A controller
186 * is some control other than a keyboard key, such as a
187 * switch, slider, pedal, wheel, or breath-pressure sensor.
188 * The MIDI 1.0 Specification provides standard numbers for typical
189 * controllers on MIDI devices, and describes the intended effect
190 * for some of the controllers.
191 * The way in which an
192 * <code>Instrument</code> reacts to a controller change may be
193 * specific to the <code>Instrument</code>.
194 * <p>
195 * The MIDI 1.0 Specification defines both 7-bit controllers
196 * and 14-bit controllers. Continuous controllers, such
197 * as wheels and sliders, typically have 14 bits (two MIDI bytes),
198 * while discrete controllers, such as switches, typically have 7 bits
199 * (one MIDI byte). Refer to the specification to see the
200 * expected resolution for each type of control.
201 * <p>
202 * Controllers 64 through 95 (0x40 - 0x5F) allow 7-bit precision.
203 * The value of a 7-bit controller is set completely by the
204 * <code>value</code> argument. An additional set of controllers
205 * provide 14-bit precision by using two controller numbers, one
206 * for the most significant 7 bits and another for the least significant
207 * 7 bits. Controller numbers 0 through 31 (0x00 - 0x1F) control the
208 * most significant 7 bits of 14-bit controllers; controller numbers
209 * 32 through 63 (0x20 - 0x3F) control the least significant 7 bits of
210 * these controllers. For example, controller number 7 (0x07) controls
211 * the upper 7 bits of the channel volume controller, and controller
212 * number 39 (0x27) controls the lower 7 bits.
213 * The value of a 14-bit controller is determined
214 * by the interaction of the two halves. When the most significant 7 bits
215 * of a controller are set (using controller numbers 0 through 31), the
216 * lower 7 bits are automatically set to 0. The corresponding controller
217 * number for the lower 7 bits may then be used to further modulate the
218 * controller value.
219 *
220 * It is possible that the underlying synthesizer
221 * does not support a specific controller message. In order
222 * to verify that a call to <code>controlChange</code>
223 * was successful, use <code>getController</code>.
224 *
225 * @param controller the controller number (0 to 127; see the MIDI
226 * 1.0 Specification for the interpretation)
227 * @param value the value to which the specified controller is changed (0 to 127)
228 *
229 * @see #getController(int)
230 */
231 public void controlChange(int controller, int value);
232
233 /**
234 * Obtains the current value of the specified controller. The return
235 * value is represented with 7 bits. For 14-bit controllers, the MSB and
236 * LSB controller value needs to be obtained separately. For example,
237 * the 14-bit value of the volume controller can be calculated by
238 * multiplying the value of controller 7 (0x07, channel volume MSB)
239 * with 128 and adding the
240 * value of controller 39 (0x27, channel volume LSB).
241 *
242 * If the device does not support setting a specific controller,
243 * this method returns 0 for that controller.
244 * Calling <code>controlChange</code> will have no effect then.
245 *
246 * @param controller the number of the controller whose value is desired.
247 * The allowed range is 0-127; see the MIDI
248 * 1.0 Specification for the interpretation.
249 *
250 * @return the current value of the specified controller (0 to 127)
251 *
252 * @see #controlChange(int, int)
253 */
254 public int getController(int controller);
255
256 /**
257 * Changes a program (patch). This selects a specific
258 * instrument from the currently selected bank of instruments.
259 * <p>
260 * The MIDI specification does not
261 * dictate whether notes that are already sounding should switch
262 * to the new instrument (timbre) or continue with their original timbre
263 * until terminated by a note-off.
264 * <p>
265 * The program number is zero-based (expressed from 0 to 127).
266 * Note that MIDI hardware displays and literature about MIDI
267 * typically use the range 1 to 128 instead.
268 *
269 * It is possible that the underlying synthesizer
270 * does not support a specific program. In order
271 * to verify that a call to <code>programChange</code>
272 * was successful, use <code>getProgram</code>.
273 *
274 * @param program the program number to switch to (0 to 127)
275 *
276 * @see #programChange(int, int)
277 * @see #getProgram()
278 */
279 public void programChange(int program);
280
281 /**
282 * Changes the program using bank and program (patch) numbers.
283 *
284 * It is possible that the underlying synthesizer
285 * does not support a specific bank, or program. In order
286 * to verify that a call to <code>programChange</code>
287 * was successful, use <code>getProgram</code> and
288 * <code>getController</code>.
289 * Since banks are changed by way of control changes,
290 * you can verify the current bank with the following
291 * statement:
292 * <pre>
293 * int bank = (getController(0) * 128)
294 * + getController(32);
295 * </pre>
296 *
297 * @param bank the bank number to switch to (0 to 16383)
298 * @param program the program (patch) to use in the specified bank (0 to 127)
299 * @see #programChange(int)
300 * @see #getProgram()
301 */
302 public void programChange(int bank, int program);
303
304 /**
305 * Obtains the current program number for this channel.
306 * @return the program number of the currently selected patch
307 * @see Patch#getProgram
308 * @see Synthesizer#loadInstrument
309 * @see #programChange(int)
310 */
311 public int getProgram();
312
313 /**
314 * Changes the pitch offset for all notes on this channel.
315 * This affects all currently sounding notes as well as subsequent ones.
316 * (For pitch bend to cease, the value needs to be reset to the
317 * center position.)
318 * <p> The MIDI specification
319 * stipulates that pitch bend be a 14-bit value, where zero
320 * is maximum downward bend, 16383 is maximum upward bend, and
321 * 8192 is the center (no pitch bend). The actual
322 * amount of pitch change is not specified; it can be changed by
323 * a pitch-bend sensitivity setting. However, the General MIDI
324 * specification says that the default range should be two semitones
325 * up and down from center.
326 *
327 * It is possible that the underlying synthesizer
328 * does not support this MIDI message. In order
329 * to verify that <code>setPitchBend</code>
330 * was successful, use <code>getPitchBend</code>.
331 *
332 * @param bend the amount of pitch change, as a nonnegative 14-bit value
333 * (8192 = no bend)
334 *
335 * @see #getPitchBend
336 */
337 public void setPitchBend(int bend);
338
339 /**
340 * Obtains the upward or downward pitch offset for this channel.
341 * If the device does not support setting pitch bend,
342 * this method always returns 8192. Calling
343 * <code>setPitchBend</code> will have no effect then.
344 *
345 * @return bend amount, as a nonnegative 14-bit value (8192 = no bend)
346 *
347 * @see #setPitchBend(int)
348 */
349 public int getPitchBend();
350
351 /**
352 * Resets all the implemented controllers to their default values.
353 *
354 * @see #controlChange(int, int)
355 */
356 public void resetAllControllers();
357
358 /**
359 * Turns off all notes that are currently sounding on this channel.
360 * The notes might not die away instantaneously; their decay
361 * rate is determined by the internals of the <code>Instrument</code>.
362 * If the Hold Pedal controller (see
363 * {@link #controlChange(int, int) controlChange})
364 * is down, the effect of this method is deferred until the pedal is
365 * released.
366 *
367 * @see #allSoundOff
368 * @see #noteOff(int)
369 */
370 public void allNotesOff();
371
372 /**
373 * Immediately turns off all sounding notes on this channel, ignoring the
374 * state of the Hold Pedal and the internal decay rate of the current
375 * <code>Instrument</code>.
376 *
377 * @see #allNotesOff
378 */
379 public void allSoundOff();
380
381 /**
382 * Turns local control on or off. The default is for local control
383 * to be on. The "on" setting means that if a device is capable
384 * of both synthesizing sound and transmitting MIDI messages,
385 * it will synthesize sound in response to the note-on and
386 * note-off messages that it itself transmits. It will also respond
387 * to messages received from other transmitting devices.
388 * The "off" setting means that the synthesizer will ignore its
389 * own transmitted MIDI messages, but not those received from other devices.
390 *
391 * It is possible that the underlying synthesizer
392 * does not support local control. In order
393 * to verify that a call to <code>localControl</code>
394 * was successful, check the return value.
395 *
396 * @param on <code>true</code> to turn local control on, <code>false</code>
397 * to turn local control off
398 * @return the new local-control value, or false
399 * if local control is not supported
400 *
401 */
402 public boolean localControl(boolean on);
403
404 /**
405 * Turns mono mode on or off. In mono mode, the channel synthesizes
406 * only one note at a time. In poly mode (identical to mono mode off),
407 * the channel can synthesize multiple notes simultaneously.
408 * The default is mono off (poly mode on).
409 * <p>
410 * "Mono" is short for the word "monophonic," which in this context
411 * is opposed to the word "polyphonic" and refers to a single synthesizer
412 * voice per MIDI channel. It
413 * has nothing to do with how many audio channels there might be
414 * (as in "monophonic" versus "stereophonic" recordings).
415 *
416 * It is possible that the underlying synthesizer
417 * does not support mono mode. In order
418 * to verify that a call to <code>setMono</code>
419 * was successful, use <code>getMono</code>.
420 *
421 * @param on <code>true</code> to turn mono mode on, <code>false</code> to
422 * turn it off (which means turning poly mode on).
423 *
424 * @see #getMono
425 * @see VoiceStatus
426 */
427 public void setMono(boolean on);
428
429 /**
430 * Obtains the current mono/poly mode.
431 * Synthesizers that do not allow changing mono/poly mode
432 * will always return the same value, regardless
433 * of calls to <code>setMono</code>.
434 * @return <code>true</code> if mono mode is on, otherwise
435 * <code>false</code> (meaning poly mode is on).
436 *
437 * @see #setMono(boolean)
438 */
439 public boolean getMono();
440
441 /**
442 * Turns omni mode on or off. In omni mode, the channel responds
443 * to messages sent on all channels. When omni is off, the channel
444 * responds only to messages sent on its channel number.
445 * The default is omni off.
446 *
447 * It is possible that the underlying synthesizer
448 * does not support omni mode. In order
449 * to verify that <code>setOmni</code>
450 * was successful, use <code>getOmni</code>.
451 *
452 * @param on <code>true</code> to turn omni mode on, <code>false</code> to
453 * turn it off.
454 *
455 * @see #getOmni
456 * @see VoiceStatus
457 */
458 public void setOmni(boolean on);
459
460 /**
461 * Obtains the current omni mode.
462 * Synthesizers that do not allow changing the omni mode
463 * will always return the same value, regardless
464 * of calls to <code>setOmni</code>.
465 * @return <code>true</code> if omni mode is on, otherwise
466 * <code>false</code> (meaning omni mode is off).
467 *
468 * @see #setOmni(boolean)
469 */
470 public boolean getOmni();
471
472 /**
473 * Sets the mute state for this channel. A value of
474 * <code>true</code> means the channel is to be muted, <code>false</code>
475 * means the channel can sound (if other channels are not soloed).
476 * <p>
477 * Unlike {@link #allSoundOff()}, this method
478 * applies to only a specific channel, not to all channels. Further, it
479 * silences not only currently sounding notes, but also subsequently
480 * received notes.
481 *
482 * It is possible that the underlying synthesizer
483 * does not support muting channels. In order
484 * to verify that a call to <code>setMute</code>
485 * was successful, use <code>getMute</code>.
486 *
487 * @param mute the new mute state
488 *
489 * @see #getMute
490 * @see #setSolo(boolean)
491 */
492 public void setMute(boolean mute);
493
494 /**
495 * Obtains the current mute state for this channel.
496 * If the underlying synthesizer does not support
497 * muting this channel, this method always returns
498 * <code>false</code>.
499 *
500 * @return <code>true</code> the channel is muted,
501 * or <code>false</code> if not
502 *
503 * @see #setMute(boolean)
504 */
505 public boolean getMute();
506
507 /**
508 * Sets the solo state for this channel.
509 * If <code>solo</code> is <code>true</code> only this channel
510 * and other soloed channels will sound. If <code>solo</code>
511 * is <code>false</code> then only other soloed channels will
512 * sound, unless no channels are soloed, in which case all
513 * unmuted channels will sound.
514 *
515 * It is possible that the underlying synthesizer
516 * does not support solo channels. In order
517 * to verify that a call to <code>setSolo</code>
518 * was successful, use <code>getSolo</code>.
519 *
520 * @param soloState new solo state for the channel
521 * @see #getSolo()
522 */
523 public void setSolo(boolean soloState);
524
525 /**
526 * Obtains the current solo state for this channel.
527 * If the underlying synthesizer does not support
528 * solo on this channel, this method always returns
529 * <code>false</code>.
530 *
531 * @return <code>true</code> the channel is solo,
532 * or <code>false</code> if not
533 *
534 * @see #setSolo(boolean)
535 */
536 public boolean getSolo();
537 }
Save This Page