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