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