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.