Debian Codegraph @

extern/rtmidi/doc/doxygen/tutorial.txt

raw
1 /*! \mainpage The RtMidi Tutorial
2
3 <CENTER>\ref intro &nbsp;&nbsp; \ref download &nbsp;&nbsp; \ref start &nbsp;&nbsp; \ref error &nbsp;&nbsp; \ref probing &nbsp;&nbsp; \ref output &nbsp;&nbsp; \ref input &nbsp;&nbsp; \ref virtual &nbsp;&nbsp; \ref compiling &nbsp;&nbsp; \ref debug &nbsp;&nbsp; \ref multi &nbsp;&nbsp; \ref apinotes &nbsp;&nbsp; \ref acknowledge &nbsp;&nbsp; \ref license</CENTER>
4
5 \section intro Introduction
6
7 RtMidi is a set of C++ classes (RtMidiIn, RtMidiOut and API-specific classes) that provides a common API (Application Programming Interface) for realtime MIDI input/output across Linux (ALSA & JACK), Macintosh OS X (CoreMIDI & JACK), and Windows (Multimedia Library) operating systems. RtMidi significantly simplifies the process of interacting with computer MIDI hardware and software. It was designed with the following goals:
8
9 - object oriented C++ design
10 - simple, common API across all supported platforms
11 - only one header and one source file for easy inclusion in programming projects
12 - MIDI device enumeration
13
14 Where applicable, multiple API support can be compiled and a particular API specified when creating an RtAudio instance.
15
16 MIDI input and output functionality are separated into two classes, RtMidiIn and RtMidiOut. Each class instance supports only a single MIDI connection. RtMidi does not provide timing functionality (i.e., output messages are sent immediately). Input messages are timestamped with delta times in seconds (via a \c double floating point type). MIDI data is passed to the user as raw bytes using an std::vector<unsigned char>.
17
18 \section whatsnew What's New (Version 5.0.0)
19
20 The version number has been bumped to 5.0.0 because a new API (Web MIDI) was added, as well as at least one new function. Changes in this release include:
21
22 - see git history for complete list of changes
23 - new Web MIDI API
24 - iOS support
25 - new setBufferSize() function
26 - fixes for WinMM, Jack
27 - added C API test program
28 - now requiring C++11
29 - build system updates
30 - midiprobe probes all compiled APIs
31 - various build system updates and code efficiencies
32
33 \section download Download
34
35 Latest Release (16 November 2021): <A href="http://www.music.mcgill.ca/~gary/rtmidi/release/rtmidi-5.0.0.tar.gz">Version 5.0.0</A>
36
37 \section start Getting Started
38
39 The first thing that must be done when using RtMidi is to create an instance of the RtMidiIn or RtMidiOut subclasses. RtMidi is an abstract base class, which itself cannot be instantiated. Each default constructor attempts to establish any necessary "connections" with the underlying MIDI system. RtMidi uses C++ exceptions to report errors, necessitating try/catch blocks around many member functions. An RtMidiError can be thrown during instantiation in some circumstances. A warning message may also be reported if no MIDI devices are found during instantiation. The RtMidi classes have been designed to work with "hot pluggable" or virtual (software) MIDI devices, making it possible to connect to MIDI devices that may not have been present when the classes were instantiated. The following code example demonstrates default object construction and destruction:
40
41 \include getting_started.cpp
42
43 Obviously, this example doesn't demonstrate any of the real functionality of RtMidi. However, all uses of RtMidi must begin with construction and must end with class destruction. Further, it is necessary that all class methods that can throw a C++ exception be called within a try/catch block.
44
45
46 \section error Error Handling
47
48 RtMidi uses a C++ exception handler called RtMidiError, which is
49 declared and defined in RtMidi.h. The RtMidiError class is quite
50 simple but it does allow errors to be "caught" by RtMidiError::Type.
51 Many RtMidi methods can "throw" an RtMidiError, most typically if a
52 driver error occurs or an invalid function argument is specified.
53 There are a number of cases within RtMidi where warning messages may
54 be displayed but an exception is not thrown. A client error callback
55 function can be specified (via the RtMidi::setErrorCallback function)
56 that is invoked when an error occurs. By default, error messages are
57 not automatically displayed in RtMidi unless the preprocessor
58 definition __RTMIDI_DEBUG__ is defined during compilation. Messages
59 associated with caught exceptions can be displayed with, for example,
60 the RtMidiError::printMessage() function.
61
62
63 \section probing Probing Ports / Devices
64
65 A client generally must query the available MIDI ports before deciding which to use. The following example outlines how this can be done.
66
67 \code
68 // midiprobe.cpp
69
70 #include <iostream>
71 #include <cstdlib>
72 #include "RtMidi.h"
73
74 int main()
75 {
76 RtMidiIn *midiin = 0;
77 RtMidiOut *midiout = 0;
78
79 // RtMidiIn constructor
80 try {
81 midiin = new RtMidiIn();
82 }
83 catch ( RtMidiError &error ) {
84 error.printMessage();
85 exit( EXIT_FAILURE );
86 }
87
88 // Check inputs.
89 unsigned int nPorts = midiin->getPortCount();
90 std::cout << "\nThere are " << nPorts << " MIDI input sources available.\n";
91 std::string portName;
92 for ( unsigned int i=0; i<nPorts; i++ ) {
93 try {
94 portName = midiin->getPortName(i);
95 }
96 catch ( RtMidiError &error ) {
97 error.printMessage();
98 goto cleanup;
99 }
100 std::cout << " Input Port #" << i+1 << ": " << portName << '\n';
101 }
102
103 // RtMidiOut constructor
104 try {
105 midiout = new RtMidiOut();
106 }
107 catch ( RtMidiError &error ) {
108 error.printMessage();
109 exit( EXIT_FAILURE );
110 }
111
112 // Check outputs.
113 nPorts = midiout->getPortCount();
114 std::cout << "\nThere are " << nPorts << " MIDI output ports available.\n";
115 for ( unsigned int i=0; i<nPorts; i++ ) {
116 try {
117 portName = midiout->getPortName(i);
118 }
119 catch (RtMidiError &error) {
120 error.printMessage();
121 goto cleanup;
122 }
123 std::cout << " Output Port #" << i+1 << ": " << portName << '\n';
124 }
125 std::cout << '\n';
126
127 // Clean up
128 cleanup:
129 delete midiin;
130 delete midiout;
131
132 return 0;
133 }
134 \endcode
135
136 Note that the port enumeration is system specific and will change if any devices are unplugged or plugged (or a new virtual port opened or closed) by the user. Thus, the port numbers should be verified immediately before opening a port. As well, if a user unplugs a device (or closes a virtual port) while a port connection exists to that device/port, a MIDI system error will be generated.
137
138 \section output MIDI Output
139
140 The RtMidiOut class provides simple functionality to immediately send messages over a MIDI connection. No timing functionality is provided. Note that there is an overloaded RtMidiOut::sendMessage() function that does not use std::vectors.
141
142 In the following example, we omit necessary error checking and details regarding OS-dependent sleep functions. For a complete example, see the \c midiout.cpp program in the \c tests directory.
143
144 \code
145 // midiout.cpp
146
147 #include <iostream>
148 #include <cstdlib>
149 #include "RtMidi.h"
150
151 int main()
152 {
153 RtMidiOut *midiout = new RtMidiOut();
154 std::vector<unsigned char> message;
155
156 // Check available ports.
157 unsigned int nPorts = midiout->getPortCount();
158 if ( nPorts == 0 ) {
159 std::cout << "No ports available!\n";
160 goto cleanup;
161 }
162
163 // Open first available port.
164 midiout->openPort( 0 );
165
166 // Send out a series of MIDI messages.
167
168 // Program change: 192, 5
169 message.push_back( 192 );
170 message.push_back( 5 );
171 midiout->sendMessage( &message );
172
173 // Control Change: 176, 7, 100 (volume)
174 message[0] = 176;
175 message[1] = 7;
176 message.push_back( 100 );
177 midiout->sendMessage( &message );
178
179 // Note On: 144, 64, 90
180 message[0] = 144;
181 message[1] = 64;
182 message[2] = 90;
183 midiout->sendMessage( &message );
184
185 SLEEP( 500 ); // Platform-dependent ... see example in tests directory.
186
187 // Note Off: 128, 64, 40
188 message[0] = 128;
189 message[1] = 64;
190 message[2] = 40;
191 midiout->sendMessage( &message );
192
193 // Clean up
194 cleanup:
195 delete midiout;
196
197 return 0;
198 }
199 \endcode
200
201
202 \section input MIDI Input
203
204 The RtMidiIn class uses an internal callback function or thread to receive incoming MIDI messages from a port or device. These messages are then either queued and read by the user via calls to the RtMidiIn::getMessage() function or immediately passed to a user-specified callback function (which must be "registered" using the RtMidiIn::setCallback() function). Note that if you have multiple instances of RtMidiIn, each may have its own thread. We'll provide examples of both usages.
205
206 The RtMidiIn class provides the RtMidiIn::ignoreTypes() function to specify that certain MIDI message types be ignored. By default, system exclusive, timing, and active sensing messages are ignored.
207
208 \subsection qmidiin Queued MIDI Input
209
210 The RtMidiIn::getMessage() function does not block. If a MIDI message is available in the queue, it is copied to the user-provided \c std::vector<unsigned char> container. When no MIDI message is available, the function returns an empty container. The default maximum MIDI queue size is 1024 messages. This value may be modified with the RtMidiIn::setQueueSizeLimit() function. If the maximum queue size limit is reached, subsequent incoming MIDI messages are discarded until the queue size is reduced.
211
212 In the following example, we omit some necessary error checking and details regarding OS-dependent sleep functions. For a more complete example, see the \c qmidiin.cpp program in the \c tests directory.
213
214 \code
215 // qmidiin.cpp
216
217 #include <iostream>
218 #include <cstdlib>
219 #include <signal.h>
220 #include "RtMidi.h"
221
222 bool done;
223 static void finish(int ignore){ done = true; }
224
225 int main()
226 {
227 RtMidiIn *midiin = new RtMidiIn();
228 std::vector<unsigned char> message;
229 int nBytes, i;
230 double stamp;
231
232 // Check available ports.
233 unsigned int nPorts = midiin->getPortCount();
234 if ( nPorts == 0 ) {
235 std::cout << "No ports available!\n";
236 goto cleanup;
237 }
238 midiin->openPort( 0 );
239
240 // Don't ignore sysex, timing, or active sensing messages.
241 midiin->ignoreTypes( false, false, false );
242
243 // Install an interrupt handler function.
244 done = false;
245 (void) signal(SIGINT, finish);
246
247 // Periodically check input queue.
248 std::cout << "Reading MIDI from port ... quit with Ctrl-C.\n";
249 while ( !done ) {
250 stamp = midiin->getMessage( &message );
251 nBytes = message.size();
252 for ( i=0; i<nBytes; i++ )
253 std::cout << "Byte " << i << " = " << (int)message[i] << ", ";
254 if ( nBytes > 0 )
255 std::cout << "stamp = " << stamp << std::endl;
256
257 // Sleep for 10 milliseconds ... platform-dependent.
258 SLEEP( 10 );
259 }
260
261 // Clean up
262 cleanup:
263 delete midiin;
264
265 return 0;
266 }
267 \endcode
268
269 \subsection cmidiin MIDI Input with User Callback
270
271 When set, a user-provided callback function will be invoked after the input of a complete MIDI message. It is possible to provide a pointer to user data that can be accessed in the callback function (not shown here). It is necessary to set the callback function immediately after opening the port to avoid having incoming messages written to the queue (which is not emptied when a callback function is set). If you are worried about this happening, you can check the queue using the RtMidi::getMessage() function to verify it is empty (after the callback function is set).
272
273 In the following example, we omit some necessary error checking. For a more complete example, see the \c cmidiin.cpp program in the \c tests directory.
274
275 \code
276 // cmidiin.cpp
277
278 #include <iostream>
279 #include <cstdlib>
280 #include "RtMidi.h"
281
282 void mycallback( double deltatime, std::vector< unsigned char > *message, void *userData )
283 {
284 unsigned int nBytes = message->size();
285 for ( unsigned int i=0; i<nBytes; i++ )
286 std::cout << "Byte " << i << " = " << (int)message->at(i) << ", ";
287 if ( nBytes > 0 )
288 std::cout << "stamp = " << deltatime << std::endl;
289 }
290
291 int main()
292 {
293 RtMidiIn *midiin = new RtMidiIn();
294
295 // Check available ports.
296 unsigned int nPorts = midiin->getPortCount();
297 if ( nPorts == 0 ) {
298 std::cout << "No ports available!\n";
299 goto cleanup;
300 }
301
302 midiin->openPort( 0 );
303
304 // Set our callback function. This should be done immediately after
305 // opening the port to avoid having incoming messages written to the
306 // queue.
307 midiin->setCallback( &mycallback );
308
309 // Don't ignore sysex, timing, or active sensing messages.
310 midiin->ignoreTypes( false, false, false );
311
312 std::cout << "\nReading MIDI input ... press <enter> to quit.\n";
313 char input;
314 std::cin.get(input);
315
316 // Clean up
317 cleanup:
318 delete midiin;
319
320 return 0;
321 }
322 \endcode
323
324 \section virtual Virtual Ports
325
326 The Linux ALSA, Macintosh CoreMIDI and JACK APIs allow for the establishment of virtual input and output MIDI ports to which other software clients can connect. RtMidi incorporates this functionality with the RtMidiIn::openVirtualPort() and RtMidiOut::openVirtualPort() functions. Any messages sent with the RtMidiOut::sendMessage() function will also be transmitted through an open virtual output port. If a virtual input port is open and a user callback function is set, the callback function will be invoked when messages arrive via that port. If a callback function is not set, the user must poll the input queue to check whether messages have arrived. No notification is provided for the establishment of a client connection via a virtual port. The RtMidi::isPortOpen() function does not report the status of ports created with the RtMidi::openVirtualPort() function.
327
328 \section compiling Compiling
329
330 In order to compile RtMidi for a specific OS and API, it is necessary to supply the appropriate preprocessor definition and library within the compiler statement:
331 <P>
332
333 <TABLE BORDER=2 COLS=5 WIDTH="100%">
334 <TR BGCOLOR="beige">
335 <TD WIDTH="5%"><B>OS:</B></TD>
336 <TD WIDTH="5%"><B>MIDI API:</B></TD>
337 <TD WIDTH="5%"><B>Preprocessor Definition:</B></TD>
338 <TD WIDTH="5%"><B>Library or Framework:</B></TD>
339 <TD><B>Example Compiler Statement:</B></TD>
340 </TR>
341 <TR>
342 <TD>Linux</TD>
343 <TD>ALSA Sequencer</TD>
344 <TD>__LINUX_ALSA__</TD>
345 <TD><TT>asound, pthread</TT></TD>
346 <TD><TT>g++ -Wall -D__LINUX_ALSA__ -o midiprobe midiprobe.cpp RtMidi.cpp -lasound -lpthread</TT></TD>
347 </TR>
348 <TR>
349 <TD>Linux or Mac</TD>
350 <TD>JACK MIDI</TD>
351 <TD>__UNIX_JACK__</TD>
352 <TD><TT>jack</TT></TD>
353 <TD><TT>g++ -Wall -D__UNIX_JACK__ -o midiprobe midiprobe.cpp RtMidi.cpp -ljack</TT></TD>
354 </TR>
355 <TR>
356 <TD>Macintosh OS X</TD>
357 <TD>CoreMIDI</TD>
358 <TD>__MACOSX_CORE__</TD>
359 <TD><TT>CoreMIDI, CoreAudio, CoreFoundation</TT></TD>
360 <TD><TT>g++ -Wall -D__MACOSX_CORE__ -o midiprobe midiprobe.cpp RtMidi.cpp -framework CoreMIDI -framework CoreAudio -framework CoreFoundation</TT></TD>
361 </TR>
362 <TR>
363 <TD>Windows</TD>
364 <TD>Multimedia Library</TD>
365 <TD>__WINDOWS_MM__</TD>
366 <TD><TT>winmm.lib, multithreaded</TT></TD>
367 <TD><I>compiler specific</I></TD>
368 </TR>
369 </TABLE>
370 <P>
371
372 The example compiler statements above could be used to compile the <TT>midiprobe.cpp</TT> example file, assuming that <TT>midiprobe.cpp</TT>, <TT>RtMidi.h</TT> and <TT>RtMidi.cpp</TT> all exist in the same directory.
373
374 \section debug Debugging
375
376 If you are having problems getting RtMidi to run on your system, try passing the preprocessor definition <TT>__RTMIDI_DEBUG__</TT> to the compiler (or define it in RtMidi.h). A variety of warning messages will be displayed that may help in determining the problem. Also try using the programs included in the <tt>tests</tt> directory. The program <tt>midiprobe</tt> displays the queried capabilities of all MIDI ports found.
377
378 \section multi Using Simultaneous Multiple APIs
379
380 Support for each MIDI API is encapsulated in specific MidiInApi or MidiOutApi subclasses, making it possible to compile and instantiate multiple API-specific subclasses on a given operating system. For example, one can compile both CoreMIDI and JACK support on the OS-X operating system by providing the appropriate preprocessor definitions for each. In a run-time situation, one might first attempt to determine whether any JACK ports are available. This can be done by specifying the api argument RtMidi::UNIX_JACK when attempting to create an instance of RtMidiIn or RtMidiOut. If no available ports are found, then an instance of RtMidi with the api argument RtMidi::MACOSX_CORE can be created. Alternately, if no api argument is specified, RtMidi will first look for JACK ports and if none are found, then CoreMIDI ports (in linux, the search order is JACK and then ALSA. In theory, it should also be possible to have separate instances of RtMidi open at the same time with different underlying API support, though this has not been tested.
381
382 The static function RtMidi::getCompiledApi() is provided to determine the available compiled API support. The function RtMidi::getCurrentApi() indicates the API selected for a given RtMidi instance.
383
384 \section apinotes API Notes
385
386 RtMidi is designed to provide a common API across the various supported operating systems and audio libraries. Despite that, some issues should be mentioned with regard to each.
387
388 \subsection linux Linux:
389
390 RtMidi for Linux was developed using the Fedora distribution. Two different MIDI APIs are supported on Linux platforms: <A href="http://www.alsa-project.org/">ALSA</A> and <A href="http://jackit.sourceforge.net/">JACK</A>. A decision was made to not include support for the OSS API because the OSS API provides very limited functionality and because <A href="http://www.alsa-project.org/">ALSA</A> support is now incorporated in the Linux kernel. The ALSA sequencer and JACK APIs allows for virtual software input and output ports.
391
392 \subsection macosx Macintosh OS X (CoreAudio):
393
394 The Apple CoreMIDI API allows for the establishment of virtual input and output ports to which other software applications can connect.
395
396 The RtMidi JACK support can be compiled on Macintosh OS-X systems, as well as in Linux.
397
398 \subsection windowsds Windows (Multimedia Library):
399
400 The \c configure script provides support for the MinGW compiler.
401
402 The Windows Multimedia library MIDI calls used in RtMidi do not make use of streaming functionality. Incoming system exclusive messages read by RtMidiIn are limited to a length as defined by the preprocessor definition RT_SYSEX_BUFFER_SIZE (set in RtMidi.cpp). The default value is 1024. There is no such limit for outgoing sysex messages via RtMidiOut.
403
404 RtMidi was originally developed with Visual C++ version 6.0 but has been tested with Virtual Studio 2010.
405
406 \section acknowledge Development & Acknowledgements
407
408 RtMidi is on github (https://github.com/thestk/rtmidi). Many thanks to the developers that are helping to maintain and improve RtMidi.
409
410 In years past, the following people provided bug fixes and improvements:
411
412 - Stephen Sinclair (Git repo, code and build system)
413 - amosonn
414 - Christopher Arndt
415 - Atsushi Eno (C API)
416 - Sebastien Alaiwan (JACK memory leaks, Windows kernel streaming)
417 - Jean-Baptiste Berruchon (Windows sysex code)
418 - Pedro Lopez-Cabanillas (ALSA sequencer API, client naming)
419 - Jason Champion (MSW project file for library build)
420 - Chris Chronopoulos
421 - JP Cimalando
422 - Eduardo Coutinho (Windows device names)
423 - Mattes D
424 - Michael Dahl
425 - Paul Dean (increment optimization)
426 - Francisco Demartino
427 - Luc Deschenaux (sysex issues)
428 - John Dey (OS-X timestamps)
429 - Christoph Eckert (ALSA sysex fixes)
430 - Thiago Goulart
431 - Ashley Hedges
432 - Sam Hocevar
433 - Rorey Jaffe
434 - jgvictores
435 - Martin Koegler (various fixes)
436 - Immanuel Litzroth (OS-X sysex fix)
437 - Bartek Lukawski
438 - Andi McClure
439 - Jon McCormack (Snow Leopard updates)
440 - Phildo
441 - Lane Spangler
442 - Axel Schmidt (client naming)
443 - Ryan Schmidt
444 - Saga Musix
445 - Bart Spaans
446 - Alexander Svetalkin (JACK MIDI)
447 - Ben Swift
448 - Casey Tucker (OS-X driver information, sysex sending)
449 - Bastiaan Verreijt (Windows sysex multi-buffer code)
450 - Dan Wilcox
451 - Yuri
452 - Serge Zaitsev
453 - Iohannes Zm&ouml;lnig
454
455 \section license License
456
457 RtMidi: realtime MIDI i/o C++ classes<BR>
458 Copyright (c) 2003-2019 Gary P. Scavone
459
460 Permission is hereby granted, free of charge, to any person
461 obtaining a copy of this software and associated documentation files
462 (the "Software"), to deal in the Software without restriction,
463 including without limitation the rights to use, copy, modify, merge,
464 publish, distribute, sublicense, and/or sell copies of the Software,
465 and to permit persons to whom the Software is furnished to do so,
466 subject to the following conditions:
467
468 The above copyright notice and this permission notice shall be
469 included in all copies or substantial portions of the Software.
470
471 Any person wishing to distribute modifications to the Software is
472 asked to send the modifications to the original developer so that
473 they can be incorporated into the canonical version. This is,
474 however, not a binding provision of this license.
475
476 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
477 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
478 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
479 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
480 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
481 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
482 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
483
484 */