Download today the trial tutorial stack of sunnYmidi. Was updated the 1st of October 2012.
New commands
This version adds the access to your Input and Output Midi devices. All your physical or virtual devices can be connected. You can connect your Destination (Midi Out) and Sources (Midi In) devices to LiveCode. LiveCode (I mean LiveCode scripts) accepts incoming midi notes,too. Connect LiveCode as a destination device for that. You can also scan existing connections and read midi notes. This version is fully compatible with Version 1.0.
Check the documentation of V1.0: Easy Fast Midi Player
Read the tutorial: Connecting Midi Devices
Download today the trial tutorial stack of sunnYmidi v2.0.
For more detailed aspects of installation, please read the READMEinstall.txt documentation you get with the download.
You can check what version of SunnYmidi you have installed:
put sunnYmidi.Version()
MIDI Destinations
There is not much to say, so use this simple script to get all your destinations. The variable idx is the index of the Device which you need when using the Midi Connection and Disconnect commands.
repeat with idx = 1 to sunnYmidi.Get("numberOfMidiDestinations") get sunnYmidi.Get("midiDestination", idx ) put idx & ": " & IT &cr after logMidi end repeat put logMidi
Adding the third parameter returns the state of the connection. This is useful to debug your own scripts.
get sunnYmidi.Get("midiDestination",idx,"dump" ) put idx & ": " & IT
Connect a Destination
A destination is any external Midi device or virtual device which you can connect to LiveCode. From LiveCode you emit Midi Notes using the command sunnYmidi.Play. All notes are sent to your destination device.
put 2 into indexDevice -- from 1 to Number Of Destinations put 3 into channel -- Use channel 3 sunnYmidi.Connect "destination", indexDevice, channel if the result is not empty then // Proceed with the error end if
If you have a device with the multi-timbre option, then you maybe would like to affect few channels to each timbre of your device. Simply add all the channels to the command, as you can see in this script.
-- all or a subset of the 16 channels are available sunnYmidi.Connect "destination", indexDevice, 1,2,3,4,5
LiveCode as a Destination
Use your scripts as a Midi player! Obviously, LiveCode won’t play any music but your handlers or functions can be triggered by incoming midi notes sent from any connected source. Check how LiveCode receives Midi Notes below. You can reconnect/disconnect as many as you like.
put 4 into indexDevice -- LiveCode dest index sunnYmidi.Connect "destination", indexDevice, 8,11,13
LiveCode spies existing connections
Use this option if you want to spy any channel used by an already made connection. All notes played on the channels you have selected from this command will be sent to LiveCode. Check how LiveCode receives Midi Notes below.
sunnYmidi.Connect "livecode", 6,7,8
LiveCode receives Midi Notes
Assuming you have enabled the connection to LiveCode, then simply call this function to read the Midi notes.
Check the tutorial to see how to manage efficiently Midi events in LiveCode. You need to use the send … in x milliseconds to avoid blocking your LiveCode application.
put sunnYmidi.Get("nextnote") into MidiNote -- in MidiNote you get: -- item 1: Channel number -- item 2: True if Note On,False otherwise -- item 3: Note number -- item 4: Velocity // Other cases -- MidiNote is empty: No notes available yet -- Only one item: This is an error message
DisConnect a Destination
If you stop sending notes to the already connected destination, the notes will be played on the Mac player. You can reconnect/disconnect as many as you like.
put 2 into indexDevice -- one already connected sunnYmidi.DisConnect "destination", indexDevice // Check the result value
Sysex Midi messages to Destination
With this command you can send raw datas to your device. Raw datas is a string of hexadecimal values. If you want to send a sysex message, start your string with 0xF0, end with 0xF7; all others datas are specific to your device; so better check your documentation.
sunnYmidi.Set channel, "sysex", "F0437332....F7" // Check the result value
There is a 4th optional parameter which accepts an integer telling how many milliseconds you want to wait before returning to LiveCode. This is interesting if your device needs some time in between two successives sysex messages.
sunnYmidi.Set channel, "sysex", "B00780", 1 -- which has the same effect as: sunnYmidi.Set channel, "sysex", "B00780" wait 1 milliseconds
SunYmidi.Set command is invalid for all channels associated with a Midi destination device except with the Sysex property. Check the result of SunnYmidi.Set if you’re not sure. Anyway, calling sunnYmidi.Set will do no nothing and no harm.
MIDI Sources
Reading your MIDI Sources
repeat with idx = 1 to sunnYmidi.Get("numberOfMidiSources") get sunnYmidi.Get("midiSource",idx ) put idx & ": " & IT &cr after logMidi end repeat put logMidi
Adding the third parameter returns the state of the connection. This is useful to debug your own scripts.
get sunnYmidi.Get("midisource",idx,"dump" ) put idx & ": " & IT
Connect a Source
A source is any external Midi device or virtual device which you can connect to LiveCode. From the Source you emit Midi Notes which will be played by sunnYmidi player (see sunnYmidi version 1.0). The remap2channel parameter lets you fix a specific channel for your Midi Source. If you don’t want to use this feature, set it to 0 or -1.
The volume parameter lets you modify the velocity of all notes from your Source.
There is 4 options: Add, Substract, Multiply or nothing. - Add 33 to each velocity note: "+33" - Substract 33 to each velocity note: "-33" - Multiply each velocity note by 3: "*3" - Do not change the velocity note: ""
put 2 into indexDevice -- from 1 to Number Of Sources put 10 into remap2channel -- remap to drums channel put "+42" into volume -- add 42 to velocity of notes sunnYmidi.Connect "source",indexDevice,remap2channel,volume // Check the result value
-- No remaping neither velocity transformation sunnYmidi.Connect "source", indexDevice // Check the result value
DisConnect a Source
Stop receiving notes from the already connected Source. You can reconnect/disconnect as many as you like.
put 2 into indexDevice -- one already connected sunnYmidi.DisConnect "source", indexDevice // Check the result value
Is something missing?
Thanks for your comments or suggestions.