1@c --------------------------------------------------- 2@node MIDI Device Interface 3@section MIDI Device Interface 4@cindex MIDI Device Interface 5@c MIDI Device Interface mididevice 6@c ----------------------------------------- 7@subsection mididevice 8@cindex mididevice 9 @deftypefn {} {@var{dev} =} mididevice (@var{mididev}) 10 @deftypefnx {} {@var{dev} =} mididevice (@var{mididir}, @var{mididev}) 11 @deftypefnx {} {@var{dev} =} mididevice ("input", @var{midiindev}, "output", @var{midioutdev}) 12 Create a midi device using the input parameters. 13 14 When a single device name or id is provided, attempt to create the midi device using the same name for both input and output. 15 16 Otherwise, use the name or device id for the given input or output direction. 17 18 @subsubheading Inputs 19 @var{mididev} - name or id of device to load.@* 20 @var{mididir} - midi direction of "input" or "output"@* 21 @var{midiindev} - midi input name or id@* 22 @var{midioutdev} - midi output name or id 23 24 @subsubheading Outputs 25 @var{dev} - octave_midi class for opened device 26 27 @subsubheading Properties 28 @var{Input} - Input device name (read only).@* 29 @var{Output} - Output device name (read only).@* 30 @var{InputID} - Input device id (read only).@* 31 @var{OutputID} - Output device id (read only).@* 32 33 @subsubheading Examples 34 Open midi device with ID of 0. 35 @example 36 @command{>} dev = mididevice(0); 37 38 mididevice connected to 39 input: "SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0" (1) 40 output: "SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0" (0) 41 @end example 42 43 Open a named midi device: 44 @example 45 @command{>} dev = mididevice("SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0"); 46 47 mididevice connected to 48 input: "SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0" (1) 49 output: "SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0" (0) 50 @end example 51 52 @xseealso{mididevinfo} 53 @end deftypefn 54@c MIDI Device Interface mididevinfo 55@c ----------------------------------------- 56@subsection mididevinfo 57@cindex mididevinfo 58 @deftypefn {} {@var{devlist} =} mididevinfo () 59 @deftypefnx {} {} mididevinfo () 60 Retrieve the midi devices detected within the system. 61 62 The list will be stored with variable @var{devlist} as either a input or output device. 63 If no output variable is provided, the devices will be displayed. 64 65 @subsubheading Inputs 66 None 67 68 @subsubheading Outputs 69 @var{devlist} - a structure containing the midi device information 70 71 @subsubheading Examples 72 Display the known devices of the system. 73 @example 74 @code { 75 @command{>} mididevinfo 76 77 MIDI devices available 78 ID Direction Interface Name 79 0 output Alsa Midi Through:Midi Through Port-0 14:0 80 1 output Alsa Ensoniq AudioPCI:ES1371 16:0 81 2 output Alsa SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0 82 3 input Alsa Midi Through:Midi Through Port-0 14:0 83 4 input Alsa Ensoniq AudioPCI:ES1371 16:0 84 5 input Alsa SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0 85 } 86 @end example 87 88 Assign variable @var{mididevices} with the values from the known devices 89 @example 90 @code { 91 @command{>} mididevices = mididevinfo 92 93 mididevices = 94 scalar structure containing the fields: 95 input = 96 @{ 97 [1,1] = 98 scalar structure containing the fields: 99 Name = SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0 100 Interface = Alsa 101 ID = 0 102 @} 103 output = 104 @{ 105 [1,1] = 106 scalar structure containing the fields: 107 Name = SparkFun Pro Micro:SparkFun Pro Micro MIDI 1 20:0 108 Interface = Alsa 109 ID = 1 110 @} 111 } 112 @end example 113 114 @xseealso{mididevice} 115 @end deftypefn 116@c MIDI Device Interface midimsg 117@c ----------------------------------------- 118@subsection midimsg 119@cindex midimsg 120 @deftypefn {} {@var{msg} =} midimsg (0) 121 @deftypefnx {} {@var{msg} =} midimsg (@var{type} ....) 122 @deftypefnx {} {@var{msg} =} midimsg ("note", @var{channel}, @var{note}, @var{velocity}, @var{duration}, @var{timestamp}) 123 @deftypefnx {} {@var{msg} =} midimsg ("noteon", @var{channel}, @var{note}, @var{velocity}, @var{timestamp}) 124 @deftypefnx {} {@var{msg} =} midimsg ("noteoff", @var{channel}, @var{note}, @var{velocity}, @var{timestamp}) 125 @deftypefnx {} {@var{msg} =} midimsg ("programchange", @var{channel}, @var{prog}, @var{timestamp}) 126 @deftypefnx {} {@var{msg} =} midimsg ("controlchange", @var{channel}, @var{ccnum}, @var{ccval}, @var{timestamp}) 127 @deftypefnx {} {@var{msg} =} midimsg ("polykeypressure", @var{channel}, @var{note}, @var{keypressure}, @var{timestamp}) 128 @deftypefnx {} {@var{msg} =} midimsg ("channelpressure", @var{channel}, @var{chanpressure}, @var{timestamp}) 129 @deftypefnx {} {@var{msg} =} midimsg ("localcontrol", @var{channel}, @var{localcontrol}, @var{timestamp}) 130 @deftypefnx {} {@var{msg} =} midimsg ("pitchbend", @var{channel}, @var{pitchchange}, @var{timestamp}) 131 @deftypefnx {} {@var{msg} =} midimsg ("polyon", @var{channel}, @var{timestamp}) 132 @deftypefnx {} {@var{msg} =} midimsg ("monoon", @var{channel}, @var{monochannels}, @var{timestamp}) 133 @deftypefnx {} {@var{msg} =} midimsg ("omnion", @var{channel}, @var{timestamp}) 134 @deftypefnx {} {@var{msg} =} midimsg ("omnioff", @var{channel}, @var{timestamp}) 135 @deftypefnx {} {@var{msg} =} midimsg ("allsoundoff", @var{channel}, @var{timestamp}) 136 @deftypefnx {} {@var{msg} =} midimsg ("allnotesoff", @var{channel}, @var{timestamp}) 137 @deftypefnx {} {@var{msg} =} midimsg ("resetallcontrollers", @var{channel}, @var{timestamp}) 138 @deftypefnx {} {@var{msg} =} midimsg ("start", @var{timestamp}) 139 @deftypefnx {} {@var{msg} =} midimsg ("stop", @var{timestamp}) 140 @deftypefnx {} {@var{msg} =} midimsg ("continue", @var{timestamp}) 141 @deftypefnx {} {@var{msg} =} midimsg ("systemreset", @var{timestamp}) 142 @deftypefnx {} {@var{msg} =} midimsg ("activesensing", @var{timestamp}) 143 @deftypefnx {} {@var{msg} =} midimsg ("timingclock", @var{timestamp}) 144 @deftypefnx {} {@var{msg} =} midimsg ("systemexclusive", @var{timestamp}) 145 @deftypefnx {} {@var{msg} =} midimsg ("systemexclusive", @var{bytes}, @var{timestamp}) 146 @deftypefnx {} {@var{msg} =} midimsg ("eox", @var{timestamp}) 147 @deftypefnx {} {@var{msg} =} midimsg ("data", @var{bytes}, @var{timestamp}) 148 @deftypefnx {} {@var{msg} =} midimsg ("songselect", @var{song}, @var{timestamp}) 149 @deftypefnx {} {@var{msg} =} midimsg ("songpositionpointer", @var{songposition}, @var{timestamp}) 150 @deftypefnx {} {@var{msg} =} midimsg ("tunerequest", @var{timestamp}) 151 @deftypefnx {} {@var{msg} =} midimsg ("miditimecodequarterframe", @var{timeseq}, @var{timevalue}, @var{timestamp}) 152 Create a midimsg object 153 154 If the input parameter is 0, create an empty midi message object 155 Otherwise the first variable is the type of message to create, followed by the additional 156 parameters for the message. 157 158 For each message type, the timestamp value is optional. 159 160 @subsubheading Inputs 161 @var{type} - string message type or a midimsgtype.@* 162 @var{timestamp} - optional seconds time stamp for the event@* 163 @var{channel} - the channel to use for the message (1..16)@* 164 @var{note} - the value of the note to play/stop@* 165 @var{velocity} - the velocity value for a note on/off, with 0 stopping a note from sounding.@* 166 @var{duration} - seconds between starting and stopping a note when created a 'note' message.@* 167 @var{prog} - program number when doing a program change message.@* 168 @var{ccnum} - control change control number.@* 169 @var{ccval} - control change control value.@* 170 @var{keypressure} - key pressure value when creating a key pressure message.@* 171 @var{chanpressure} - channel pressure value when creating a channelpressure message.@* 172 @var{pitchchange} - pitch change value when creating a pitch bend message.@* 173 @var{localcontrol} - boolean value when creating a localcontrol message.@* 174 @var{monochannels} - channels specified for a mono on message.@* 175 @var{bytes} - array of data in range of 0 to 127 specified as part of a data message or 176 system exclusive message.@* 177 @var{song} - song selection number for a song selection message.@* 178 @var{songposition} - song position value for a song position message.@* 179 @var{timeseq} - timecode sequence number for a miditimecodequarterframe message.@* 180 @var{timevalue} - timecode value number for a miditimecodequarterframe message.@* 181 182 @subsubheading Outputs 183 @var{msg} - a midimsg object containing the midi data of the message 184 185 @subsubheading Properties 186 @var{timestamp} - timestamp of the message, or an array or timestamps if the the message is a 187 compound message.@* 188 @var{msgbytes} - the raw message bytes that make up the MIDI message.@* 189 @var{nummsgbytes} - the number of message bytes that make up the MIDI message.@* 190 @var{type} - string or midimsgtype that represents the message type.@* 191 @var{channel} - the channel number for message.@* 192 @var{note} - the note value for message (Only valid for noteon/off and polykeypressure).@* 193 @var{velocity} - the velocity value for message (Only valid for noteon/off).@* 194 @var{keypressure} - the keypressure value for message (Only valid for polykeypressure).@* 195 @var{channelpressure} - the chanpressure value for message (Only valid for channelpressure).@* 196 @var{localcontrol} - the localcontrol value for message (Only valid for localcontrol messages).@* 197 @var{monochannels} - channels specified for a mono on message.@* 198 @var{program} - program number specified for a program change message.@* 199 @var{ccnumber} - control change number specified for a control change message.@* 200 @var{ccvalue} - control change value specified for a control change message.@* 201 @var{song} - song number for a song selection message.@* 202 @var{songposition} - song position value for a song position message.@* 203 @var{pitchchange} - pitch change value for a pitch bend message.@* 204 @var{timecodesequence} - timecode sequence number for a miditimecodequarterframe message.@* 205 @var{timecodevalue} - timecode value number for a miditimecodequarterframe message.@* 206 207 @subsubheading Examples 208 Create a note on/off pair with a duration of 1.5 seconds 209 @example 210 @code { 211 msg = midimsg('note', 1, 60, 100, 1.5) 212 } 213 @end example 214 215 Create a separate note on/off pair with a time between them of 1.5 seconds 216 @example 217 @code { 218 msg = [midimsg('noteon', 1, 60, 100, 0), midimsg('noteoff', 1, 60, 0, 1.5)] 219 } 220 @end example 221 222 Create a system reset message 223 @example 224 @code { 225 msg = midimsg('systemreset') 226 } 227 @end example 228 229 @xseealso{midifileread, midisend, midireceive, midimsgtype} 230 @end deftypefn 231@c MIDI Device Interface midireceive 232@c ----------------------------------------- 233@subsection midireceive 234@cindex midireceive 235 @deftypefn {} {@var{midimsg} =} midireceive (@var{dev}) 236 @deftypefnx {} {@var{midimsg} =} midireceive (@var{dev}, @var{maxmsg}) 237 Attempt to receive midi messages from a midi device. 238 239 @subsubheading Inputs 240 @var{dev} - a octave midi device opened using mididevice.@* 241 @var{maxmsg} - Maximum number of messages to retrieve. If not specified, the function will attempt to get all pending.@* 242 243 @subsubheading Outputs 244 @var{midimsg} - a midimsg containing the messages retrieved from the device.@* 245 If no messages are available, @var{midimsg} will be empty. 246 247 @subsubheading Examples 248 Open device 0, and poll and display read messages 249 @example 250 @code { 251 dev = mididevice(0); 252 while true 253 mx = midireceive(dev); 254 if !isempty(mx) 255 % display message 256 mx 257 endif 258 endwhile 259 } 260 @end example 261 262 @xseealso{mididevice, midisend} 263 @end deftypefn 264@c MIDI Device Interface midisend 265@c ----------------------------------------- 266@subsection midisend 267@cindex midisend 268 @deftypefn {} {} midisend (@var{dev}, @var{msg}) 269 @deftypefnx {} {} midisend (@var{dev}, ...) 270 Send a midimsg to a midi device 271 272 @subsubheading Inputs 273 @var{dev} - midi device opened using mididevice@* 274 @var{msg} - a midi message class with messages to send to the midi device@* 275 If the msg isn't a midimsg class, the input data is expected to be in same format as the inputs to a midimsg object. 276 277 @subsubheading Outputs 278 None 279 280 @subsubheading Examples 281 Send a note on/off command to a opened midi device @var{dev} 282 @example 283 @code { 284 midisend(dev, midimsg("note", 1, 60, 100, 2.0)); 285 } 286 @end example 287 288 @xseealso{midimsg, mididevice, midireceive} 289 @end deftypefn 290@c --------------------------------------------------- 291@node MIDI Controller Interface 292@section MIDI Controller Interface 293@cindex MIDI Controller Interface 294@c MIDI Controller Interface midicontrols 295@c ----------------------------------------- 296@subsection midicontrols 297@cindex midicontrols 298 @deftypefn {} {@var{obj} =} midicontrols () 299 @deftypefnx {} {@var{obj} =} midicontrols (@var{ctrlid}) 300 @deftypefnx {} {@var{obj} =} midicontrols (@var{ctrlid}, @var{initialvalues}) 301 @deftypefnx {} {@var{obj} =} midicontrols (__, @var{propertyname}, @var{propertyvalue}) 302 Create a midi controls object 303 304 @subsubheading Inputs 305 @var{ctrlid} - single control id or array of control ids to monitor, or [] to use any controller.@* 306 @var{initialvalues} - initial values to use for controls. It should be the same size as @var{ctrlid}@* 307 @var{propertyname}, @var{propertyvalue} - properties to set on the controller. If a device is not specified 308 the value from getpref("midi", "DefaultDevice", 0) will be used.@* 309 310 311 Known properties are: 312 @table @asis 313 @item mididevice 314 name of the mididevice to monitor. 315 @item outputmode 316 the scaling mode for values: 'rawmidi' will return values between 0 .. 127, 317 'normalized' will use values between 0 .. 1. 318 @end table 319 320 @subsubheading Outputs 321 @var{obj} - returns a midicontrols object 322 323 @subsubheading Examples 324 Create a midicontrols object monitoring control id 2001 on the default midi device 325 @example 326 @code { 327 ctrl = midicontrols(2001) 328 } 329 @end example 330 331 Create a midicontrols object monitoring control id 2001 on a a non default device 332 @example 333 @code { 334 ctrl = midicontrols(2001, 'mididevice', 1) 335 } 336 @end example 337 338 @xseealso{midiread, midisync} 339 @end deftypefn 340@c MIDI Controller Interface midiid 341@c ----------------------------------------- 342@subsection midiid 343@cindex midiid 344 @deftypefn {} {[@var{ctrlid}, @var{dev}] =} midiid () 345 Scan for control messages from midi devices to get the id of the device 346 347 Function will display a prompt for the user to move the midi control and return when 348 a control messages is detected or ctrl-C is pressed. 349 350 @subsubheading Inputs 351 None 352 353 @subsubheading Outputs 354 @var{ctrlid} - control id made from the controller channel * 1000 + controller number.@* 355 @var{dev} = name of the midi device the controller was detected on. 356 357 @subsubheading Examples 358 Monitor midi devices for first moving controller 359 @example 360 @code { 361 [ctrlid, devname] = midiid() 362 } 363 @end example 364 365 @xseealso{mididevinfo, midicontrols} 366 @end deftypefn 367@c MIDI Controller Interface midiread 368@c ----------------------------------------- 369@subsection midiread 370@cindex midiread 371 @deftypefn {} {@var{val} =} midiread (@var{midicontrolsObj}) 372 Read current values of midi controls 373 374 @subsubheading Inputs 375 @var{midicontrolObj} - control object created using midicontrols@* 376 377 @subsubheading Outputs 378 @var{val} single value or array of current values from the midi device. 379 380 @subsubheading Examples 381 Read current value of midicontrols with a ctrlid 2001 on the default midi device. 382 @example 383 @code { 384 ctrl = midicontrols(2001) 385 val = midiread(ctrl); 386 } 387 @end example 388 389 Read current value of midicontrols with a ctrlid 2001 on a non default midi device. 390 @example 391 @code { 392 ctrl = midicontrols(2001, 'mididevice', 1) 393 val = midiread(ctrl); 394 } 395 @end example 396 397 @xseealso{midicontrols, midisync} 398 @end deftypefn 399@c MIDI Controller Interface midisync 400@c ----------------------------------------- 401@subsection midisync 402@cindex midisync 403 @deftypefn {} {} midisync (@var{midicontrolsObj}) 404 @deftypefnx {} {} midisync (@var{midicontrolsObj}, @var{ctrlvalues}) 405 Send the values of control object to the control, using @var{ctrlvalues} values 406 if specified instead 407 408 @subsubheading Inputs 409 @var{midicontrolObj} - control object created using midicontrols@* 410 @var{ctrlvalues} - values to send to the controls instead of initial values 411 412 @subsubheading Outputs 413 None 414 415 @subsubheading Examples 416 Send sync command to a midicontrols with a ctrlid 2001 to set a value of 1 417 @example 418 @code { 419 ctrl = midicontrols(2001) 420 midisync(ctrl, 1); 421 } 422 @end example 423 424 @xseealso{midicontrols} 425 @end deftypefn 426@c --------------------------------------------------- 427@node MIDI File I/O 428@section MIDI File I/O 429@cindex MIDI File I/O 430@c MIDI File I/O ismidifile 431@c ----------------------------------------- 432@subsection ismidifile 433@cindex ismidifile 434 @deftypefn {} {@var{ismidi} =} ismidifile (@var{filename}) 435 Check if @var{filename} is a midi file. 436 437 The function only checks whether it is an existing file and the 438 file starts with a valid 'MThd' header. 439 440 Non existing files, or files that do not meet the header criteria will return false. 441 442 @subsubheading Inputs 443 @var{filename} - filename of file to check.@* 444 445 @subsubheading Outputs 446 @var{ismidi} - true if it is a midi file, false otherwise 447 448 @xseealso{midifileread, midifilewrite} 449 @end deftypefn 450@c MIDI File I/O midifileinfo 451@c ----------------------------------------- 452@subsection midifileinfo 453@cindex midifileinfo 454 @deftypefn {} {@var{info} =} midifileinfo (@var{filename}) 455 Read MIDI file and display information about the tracks and data 456 457 @subsubheading Inputs 458 @var{filename} - filename of file to open.@* 459 460 @subsubheading Outputs 461 @var{info} - structure of the midi file data 462 with the following fields:@* 463 @table @asis 464 @item filename 465 the name of the file 466 @item header 467 The header block information 468 @item track 469 An array of tracks read from the file 470 @item other 471 An array of non-track midi blocks read from the file 472 @end table 473 @xseealso{midifileread} 474 @end deftypefn 475@c MIDI File I/O midifileread 476@c ----------------------------------------- 477@subsection midifileread 478@cindex midifileread 479 @deftypefn {} {@var{msg} =} midifileread (@var{filename}, [propertyname, propertyvalue @dots{}]) 480 Read MIDI file into a midimsg 481 482 @subsubheading Inputs 483 @var{filename} - filename of file to open.@* 484 @var {propertyname}, @var{properyvalue} - optional propertyname/value pairs.@* 485 486 Known property values are: 487 @table @asis 488 @item includemetaevents 489 A True/False value to include MetaEvents in the out message list. 490 @end table 491 492 @subsubheading Outputs 493 @var{msg} - a midimsg struct containing the messages read from the file@* 494 @xseealso{midifileinfo, midimsg} 495 @end deftypefn 496@c MIDI File I/O midifilewrite 497@c ----------------------------------------- 498@subsection midifilewrite 499@cindex midifilewrite 500 @deftypefn {} {} midifilewrite (@var{filename}, @var{msgs}) 501 @deftypefnx {} {} midifilewrite (@var{filename}, @var{msgs}, @var{optionname}, @var{optionvalue}) 502 Write a midifile 503 504 @subsubheading Inputs 505 @var{filename} - filename of file to open.@* 506 @var{msg} - a midimsg struct or a cell array of midimsg containing data to write to file@* 507 @var{optionname}, @var{optionvalue} - option value/name pairs@* 508 509 Known options are: 510 @table @asis 511 @item format 512 MIDI file format number. (0 (default), 1, 2) 513 @end table 514 515 Where format is 0, if a cell array is passed to midifilewrite, the midimsg values will 516 be concatenated together before saving. 517 518 Were format is not 0, the cell array is treated as tracks of misimsg. 519 520 @subsubheading Outputs 521 None 522 @xseealso{midifileread, midimsg} 523 @end deftypefn 524@c --------------------------------------------------- 525@node Enumerations 526@section Enumerations 527@cindex Enumerations 528@c Enumerations midimsgtype 529@c ----------------------------------------- 530@subsection midimsgtype 531@cindex midimsgtype 532 @deftypefn {} {} midimsgtype 533 A midimsg type enumeration for values of the midimsg type. 534 535 Enumeration values are: 536 @multitable @columnfractions .2 .4 .3 537 @item Data @tab Stop @tab SongPositionPointer 538 @item PolyOn @tab PolyKeyPressure @tab NoteOff 539 @item EOX @tab ActiveSensing @tab SongSelect 540 @item MonoOn @tab ChannelPressure @tab ControlChange 541 @item TimingClock @tab SystemReset @tab AllSoundOff 542 @item OmniOn @tab PitchBend @tab ProgramChange 543 @item Start @tab TuneRequest @tab ResetAllControllers 544 @item OmniOff @tab Undefined @tab SystemExclusive 545 @item Continue @tab MIDITimeCodeQuarterFrame @tab LocalControl 546 @item AllNotesOff @tab MetaEvent @tab 547 @end multitable 548 549 550 The enumeration value can be used instead of a string in midimsg creation. 551 552 @subsubheading Examples 553 Use both a string and a midimsgtype for the type parameter of a midimsg. 554 @example 555 @code { 556 # both statements are equivalent 557 msg = midimsg('NoteOn', 1, 60, 100); 558 msg = midimsg(midimsgtype.NoteOn, 1, 60, 100); 559 } 560 @end example 561 562 @xseealso{midimsg} 563 @end deftypefn 564