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 */ noteOn(int noteNumber, int velocity)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 */ noteOff(int noteNumber, int velocity)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 */ noteOff(int noteNumber)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 */ setPolyPressure(int noteNumber, int pressure)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 */ getPolyPressure(int noteNumber)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 */ setChannelPressure(int pressure)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 */ getChannelPressure()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 */ controlChange(int controller, int value)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 */ getController(int controller)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 */ programChange(int program)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 */ programChange(int bank, int program)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 */ getProgram()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 */ setPitchBend(int bend)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 */ getPitchBend()311 int getPitchBend(); 312 313 /** 314 * Resets all the implemented controllers to their default values. 315 * 316 * @see #controlChange(int, int) 317 */ resetAllControllers()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 */ allNotesOff()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 */ allSoundOff()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 */ localControl(boolean on)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 */ setMono(boolean on)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 */ getMono()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 */ setOmni(boolean on)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 */ getOmni()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 */ setMute(boolean mute)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 */ getMute()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 */ setSolo(boolean soloState)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 */ getSolo()473 boolean getSolo(); 474 } 475