Menu Close

Version 1.0 – 9 May 2011
Version 2.0 – 3 Oct 2012

Download today the trial tutorial stack of sunnYmidi. Updated the 1st of October 2012.

Download the latest version of sunnYmidi from .
For more detailed aspects of installation, please read the READMEinstall.txt documentation.
You can check what version of SunnYmidi you have installed:

        put sunnYmidi.Version()

Starting sunnYmidi

First, you need to initialize sunnYmidi, most probably in a preopenStack, or a preopenCard handler, but really it’s up to you to choose where to put it.

        sunnYmidi.Start   user, key

user and key are datas you received when ordering sunnYmidi.

After this command, and for all others commands as well, better check the result:

        if the result is not empty then
             -- your code for errors
        end if

Stopping sunnYmidi

When you don’t want to use sunnYmidi anymore, you can do:

        sunnYmidi.Stop

This cleans up and frees all resources used by sunnYmidi.

Playing a Midi Note

To play a music note, create a LiveCode script anywhere you like and write the following script line into it:

        sunnYmidi.Play  channel, Duration, Velocity, Note

        channel:        1 .. 16         ( Midi Channel )
        Duration:       1 .. MaxInt     ( in milliseconds )
        Velocity:       1 .. 128        ( 1 is inaudible, 128 is the higher intensity )
        Note:           0 .. 127        ( See Midi Documentation )

This command sends a Midi Event to the CoreMidi System. This is going very fast, with almost no latency. If the result of this command is empty then everything went fine, otherwise you get some information about what’s wrong.
This command is non-blocking, whatever the Duration of a note, this command returns instantly. This implies that calling 2 times this command one after the other will play 2 notes almost at the same time.

Playing and Stopping a Midi Note

It’s possible to play and stop a note on your own. First, you ask to play a note forever by setting the Duration parameter to -1:

        SunnYmidi.Play channel, -1, Velocity, Note

To stop the note, call again our Play command with a Velocity or a Duration of 0.
Three similar ways to stop the note:

        SunnYmidi.Play channel,  0,  velocity, Note
        SunnYmidi.Play channel,  duration,  0, Note
        SunnYmidi.Play channel,  0,  0, Note

Playing few Midi Notes at once

To play a chord

        sunnYmidi.Play channel, Duration, Velocity, Note1, Note2, .. , NoteN

You can play from 1 to 7 notes. All notes are played simultaneously with the same Duration and velocity.

This command returns instantly, whatever the whole Duration of the arpeggio.

To play an Arpeggio

        sunnYmidi.Arpege channel, Duration, Velocity, Delay, Note1, Note2, .. NoteN

You can play from 2 to 7 notes. Note1 is played immediately, Note2 after *Delay* milliseconds, and so on. Every Note is played with the same Duration and Velocity.

This command returns instantly, whatever the whole Duration of the arpeggio.

To play an irregular Arpeggio

        sunnYmidi.Arpege channel, Duration, Velocity, -1, Note1, Delay2, Note2, .., DelayN, NoteN

You can play from 2 to 7 notes. Note1 is played immediately, Note2 after *Delay2* milliseconds and so on. Every Note is played with the same Duration and Velocity.

This command returns instantly, whatever the whole Duration of the arpeggio.

Getting an Instrument Name and ID

First you have to know how many instruments are at your disposal :

        sunnYmidi.Get( "numberOfInstruments" )

Then you can ask for an instrument name and his corresponding ID :

        sunnYmidi.Get( "instrument", index )

index is a value between 1 and the number of instruments.
This function returns a couple of items, the first being the ID, the second the name.

Setting an Instrument

In Midi, you can associate an instrument to a Midi channel :

        sunnYmidi.Set channel, "instrument", instrument_ID

where instrument_ID is an integer defined by the Apple DSL Synth.
The instrument_ID is one the value returned by sunnYmidi.Get( “instrument”, index ) explained above.

Setting a Midi effect

you have at your disposal some Midi events to change some note’s properties.
Any effect’s name must be in small letters and only the 3 first characters are significatives.

Panoramic ( pan )

        sunnYmidi.Set channel, "panoramic", value
        sunnYmidi.Set channel, "pan", value

Value is an integer from 1 to 128. 1 is for left speaker, 128 for right speaker, then you can adjust it at your will to the whole range of values.

Reverberation ( rev )

        sunnYmidi.Set channel, "reverberation", value
        sunnYmidi.Set channel, "rev", value

Value is an integer from 1 to 128, with 1 setting it off, and 128 being the max reverb.

Vibrato ( vib )

        sunnYmidi.Set channel, "vibrato", value
        sunnYmidi.Set channel, "vib", value

Value is an integer from 1 to 128, with 1 setting it off, and 128 being the max effect.

Sustain ( sus )

        sunnYmidi.Set channel, "sustain", value
        sunnYmidi.Set channel, "sus", value

Value is an integer whith 0 or 1 for off, all other values for on.

Expression ( exp )

        sunnYmidi.Set channel, "expression", value
        sunnYmidi.Set channel, "exp", value

Value is an integer from 1 to 128, with 1 setting it off, and 128 being the max volume.

Volume ( vol )

        sunnYmidi.Set channel, "volume", value
        sunnYmidi.Set channel, "vol", value

Value is an integer from 1 to 128, with 1 setting it off, and 128 being the max volume.

Reset all effects ( res )

        sunnYmidi.Set channel, "reset", value
        sunnYmidi.Set channel, "res", value

Value is 1 to 128, but not used in the current version.

Common Errors

As I wanted SunnYmidi to be reactive, I choose to correct some errors automatically. For Notes value in all the commands of SunnYmidi, if any value is negative ( < 0 ), then the Note is set to 0. If any value is more than 127, the Note is set to 127. There is no error report. For Channel value in all the commands of SunnYmidi, any value which is not in the range 1 to 16, the value of the channel is set to 1. There is no error report.

For some errors, which you can read in LiveCode with the result , you’ll get only “Wrong.”.

Please, check this documentation to see what parameter you missed or probably you forget to initialize sunnYmidi with the Start command.

Playing Notes a la Hypercard

        sunnYmidi.HCplay channel,  120,  "c3w d3h e3q f3e g3s a3t b3e"
        sunnYmidi.HCplay channel,        "c3w dh eq fe gs at be"

See “playing sounds a la Hypercard” documentation for further details.
This command is actually not part of the external. It comes as a free LiveCode script which needs SunnYmidi to work. You can download it for free from my web site.

Music Notes Chart

MIDI Music Note Chart
Octave # C C# D D# E F F# G G# A A# B
0 0 1 2 3 4 5 6 7 8 9 10 11
1 12 13 14 15 16 17 18 19 20 21 22 23
2 24 25 26 27 28 29 30 31 32 33 34 35
3 36 37 38 39 40 41 42 43 44 45 46 47
4 48 49 50 51 52 53 54 55 56 57 58 59
5 60 61 62 63 64 65 66 67 68 69 70 71
6 72 73 74 75 76 77 78 79 80 81 82 83
6 84 85 86 87 88 89 90 91 92 93 94 95
7 96 97 98 99 100 101 102 103 104 105 106 107
8 108 109 110 111 112 113 114 115 116 117 118 119
9 120 121 122 123 124 125 126 127  

Music Drum Map – channel 10

GM Patches or Instruments

 Prog# Instrument Prog# Instrument PIANO CHROMATIC PERCUSSION
1 Acoustic Grand 9 Celesta
2 Bright Acoustic 10 Glockenspiel
3 Electric Grand 11 Music Box
4 Honky-Tonk 12 Vibraphone
5 Electric Piano 1 13 Marimba
6 Electric Piano 2 14 Xylophone
7 Harpsichord 15 Tubular Bells
8 Clavinet 16 Dulcimer ORGAN GUITAR
17 Drawbar Organ 25 Nylon String Guitar
18 Percussive Organ 26 Steel String Guitar
19 Rock Organ 27 Electric Jazz Guitar
20 Church Organ 28 Electric Clean Guitar
21 Reed Organ 29 Electric Muted Guitar
22 Accoridan 30 Overdriven Guitar
23 Harmonica 31 Distortion Guitar
24 Tango Accordian 32 Guitar Harmonics BASS SOLO STRINGS
33 Acoustic Bass 41 Violin
34 Electric Bass(finger) 42 Viola
35 Electric Bass(pick) 43 Cello
36 Fretless Bass 44 Contrabass
37 Slap Bass 1 45 Tremolo Strings
38 Slap Bass 2 46 Pizzicato Strings
39 Synth Bass 1 47 Orchestral Strings
40 Synth Bass 2 48 Timpani ENSEMBLE BRASS
49 String Ensemble 1 57 Trumpet
50 String Ensemble 2 58 Trombone
51 SynthStrings 1 59 Tuba
52 SynthStrings 2 60 Muted Trumpet
53 Choir Aahs 61 French Horn
54 Voice Oohs 62 Brass Section
55 Synth Voice 63 SynthBrass 1
56 Orchestra Hit 64 SynthBrass 2 REED PIPE
65 Soprano Sax 73 Piccolo
66 Alto Sax 74 Flute
67 Tenor Sax 75 Recorder
68 Baritone Sax 76 Pan Flute
69 Oboe 77 Blown Bottle
70 English Horn 78 Skakuhachi
71 Bassoon 79 Whistle
72 Clarinet 80 Ocarina SYNTH LEAD SYNTH PAD
81 Lead 1 (square) 89 Pad 1 (new age)
82 Lead 2 (sawtooth) 90 Pad 2 (warm)
83 Lead 3 (calliope) 91 Pad 3 (polysynth)
84 Lead 4 (chiff) 92 Pad 4 (choir)
85 Lead 5 (charang) 93 Pad 5 (bowed)
86 Lead 6 (voice) 94 Pad 6 (metallic)
87 Lead 7 (fifths) 95 Pad 7 (halo)
88 Lead 8 (bass+lead) 96 Pad 8 (sweep) SYNTH EFFECTS ETHNIC 97 FX 1 (rain) 105 Sitar 98 FX 2 (soundtrack) 106 Banjo 99 FX 3 (crystal) 107 Shamisen
100 FX 4 (atmosphere) 108 Koto
101 FX 5 (brightness) 109 Kalimba
102 FX 6 (goblins) 110 Bagpipe
103 FX 7 (echoes) 111 Fiddle
104 FX 8 (sci-fi) 112 Shanai PERCUSSIVE SOUND EFFECTS
113 Tinkle Bell 121 Guitar Fret Noise
114 Agogo 122 Breath Noise
115 Steel Drums 123 Seashore
116 Woodblock 124 Bird Tweet
117 Taiko Drum 125 Telephone Ring
118 Melodic Tom 126 Helicopter
119 Synth Drum 127 Applause
120 Reverse Cymbal 128   Gunshot

Limitation

The current version of SunnYmidi runs on:

        - INTEL Mac OS X systems from version 10.6 and up.
        - LiveCode IDE from Version 4.0 and up.

A note for DJs or MIDI experts

SunnYmidi is a simple tool, made to help LiveCode Users add sounds to their stacks in an easy but still in a powerful way. I’ve hidden all the complexity of the specifications of Midi. If you are looking for a tool like GarageBand or Cubase, please go elsewhere, or better still code it yourself on top of SunnYmidi; you’ll make some guys happy.

A note for QuickTime users

SunnYmidi has nothing to do with QuickTime! One question which keeps coming from LiveCode coders is how can I play music wthout any latency. SunnyMidi is the answer today! For technology lovers, SunnYmidi is built on top of the Apple CoreAudio Framework and uses by default the internal DSL synth available on all MacIntosh computers.

The challenge was to keep the distance from a LiveCode command to MacOS X internal sound system API as small as possible, which was successfully solved and it works beautifully.

Next Steps

This documentation is an overview of all commands and functions available. Download the fully functional SunnYmidi Tutorial Stack. Every card script is a LiveCode Lesson to help you use sunnYmidi in different contexts. I strongly suggest to have a closer look at this stack when you start scripting with sounds.

Have fun !

A bit of warnings

EXCEPT AS EXPRESSLY PROVIDED OTHERWISE IN AN AGREEMENT BETWEEN YOU AND THE AUTHOR, ALL INFORMATION AND SOFTWARE ON THIS WEB SITE ARE PROVIDED “AS IS” WITHOUT WARRANTY OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THE AUTHOR ASSUMES NO RESPONSIBILITY FOR ERRORS OR OMISSIONS IN THE INFORMATION OR SOFTWARE OR OTHER DOCUMENTS WHICH ARE REFERENCED BY OR LINKED TO THIS WEB SITE. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, THOSE RESULTING FROM: (1) RELIANCE ON THE MATERIALS PRESENTED, (2) COSTS OF REPLACEMENT GOODS, (3) LOSS OF USE, DATA OR PROFITS, (4) DELAYS OR BUSINESS INTERRUPTIONS, (5) AND ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION) WHETHER OR NOT THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE ABOVE LIMITATIONS OR EXCLUSIONS MAY NOT APPLY TO YOU. THIS WEB SITE COULD INCLUDE TECHNICAL OR OTHER INACCURACIES. CHANGES ARE PERIODICALLY MADE TO THE INFORMATION HEREIN. HOWEVER, THE AUTHOR MAKES NO COMMITMENT TO UPDATE MATERIALS ON THIS SITE