Getting Started

Get sunnYmidi

Download the latest version of sunnYmidi. For more detailed aspects of the external integration, please read the READMEinstall.txt.
 # Check what version of sunnYmidi you are using:
 put sunnYmidi.Version()

Start sunnYmidi

When shipping sunnYmidi, you'll receive an ID and a KEY which are mandatory to initialize sunnYmidi. For the trial/demo version, you don't need them.
First, you need to initialize sunnYmidi, the external, most probably in a preopenStack, or a preopenCard handler, but really it's up to you to choose where to put it.
 # call this once at each LiveCode session.
 sunnYmidi.Start   USER_ID,  USER_KEY
 # best practice: always check for errors.
 if the result is not empty then
	-- your code for errors
 end if

Stop sunnYmidi

When you don't want to use sunnYmidi anymore, just do this to clean up and free all resources used by sunnYmidi.
 # stop the external
 sunnYmidi.Stop

 Playing sounds

Play a Note

To play a music note, create a LiveCode script anywhere you like and write the following script line into it:
 # channel:	1 .. 16		(Midi Channel)
 # duration:	1 .. MaxInt	(in milliseconds)
 # velocity:	1 .. 128	(1 is inaudible, 128 is the higher)
 # note:	0 .. 127	(see Midi Documentation)

 sunnYmidi.Play  channel, duration, velocity, note
This command sends a Midi Event to the CoreMidi System with 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 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.
It's possible to play a note forever by setting the duration parameter to -1, but then you have to stop it on your own.
 sunnYmidi.Play channel, -1, velocity, note
 # later, stop the note this way:
 sunnYmidi.Play channel,  0,  velocity, note
 # or stop this way:
 sunnYmidi.Play channel,  duration,  0, note
 # or this way:
 sunnYmidi.Play channel,  0,  0, note

Chord

You can play from 1 to 7 notes which are played simultaneously with the same duration and velocity. This command returns instantly, whatever the whole duration of the arpeggio.
 #  you can pass 1 to 7 notes.
 sunnYmidi.Play channel, duration, velocity, note1, note2, .. , noteN

Arpeggio

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.
 #  you can pass 2 to 7 notes.
 sunnYmidi.Arpege channel, duration, velocity, delay, note1, note2, .. noteN
You can also play an irregular arpeggio 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.
 #  you can pass 2 to 7 notes.
 sunnYmidi.Arpege channel, duration, velocity, -1, note1, delay2, note2, .., delayN, noteN

Instrument

To know how many instruments are at your disposal, ask for "numberOfInstruments". Then you can ask for an instrument name using an index. Index is a value between 1 and the number of instruments. This function returns the name as defined by Apple.
 put sunnYmidi.Get( "numberOfInstruments" )
 # -> 235
 #  sunnYmidi.Get( "instrument", index )
 put sunnYmidi.Get( "instrument", 33 )
 # -> Santur
To play some notes with a specific instrument, you need to bind an instrument ID to a Midi channel where IndexInstrument is an integer with a value of 1 up to the number of instruments (see above)
 put 2 into channel
 put sunnYmidi.Get( "instrument", 33 ) into IndexInstrument
 sunnYmidi.Set channel, "instrument", IndexInstrument

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

Trying to limit the number of errors, I choose to correct some of them automatically.
In all the commands of sunnYmidi, if any note value is negative, then the value is set to 0. If any value is more than 127, the value is set to 127. There is no error report.
In all the commands of sunnYmidi, any channel value which is not in the range 1 to 16, the value 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.

A la Hypercard

From the old days of Hypercard... This command is actually not part of the external but comes as a free LiveCode script which needs sunnYmidi to work. You can find it in the tutorial-demo stack script.
 sunnYmidi.HCplay channel,  120,  "c3w d3h e3q f3e g3s a3t b3e"
 sunnYmidi.HCplay channel,        "c3w dh eq fe gs at be"

 Midi In-Out Devices

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 using the Midi Connection and Disconnection commands.
repeat with idx = 1 to sunnYmidi.Get( "numberOfDestinations")
      	get sunnYmidi.Get( "destination", 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( "destination",idx,"dump" )
put idx & ": " & IT

Connect 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

Disconnect 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

Set on Destination

SunYmidi.Set command is invalid for all channel associated with a Midi destination device. 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( "numberOfSources")
		get sunnYmidi.Get( "source",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( "source",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. 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. 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 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

 Midi stuff

Notes Chart

MIDI Music Note Chart
CC#DD#EFF# GG#AA#B
0 0 12345 67891011
1 1213141516 17181920212223
2 2425262728 29303132333435
3 3637383940 41424344454647
4 4849505152 53545556575859
5 6061626364 65666768697071
6 7273747576 77787980818283
6 8485868788 89909192939495
7 96979899100 101102103104105106107
8 108109110111112 113114115116117118119
9 120121122123124 125126127  

Drum Map

GMDrumpMap Image

GM Patches


GM Patches
Prog#InstrumentProg#Instrument
PIANO CHROMATIC PERCUSSION
1Acoustic Grand9Celesta
2Bright Acoustic10Glockenspiel
3Electric Grand11Music Box
4Honky-Tonk12Vibraphone
5Electric Piano 113Marimba
6Electric Piano 214Xylophone
7Harpsichord15Tubular Bells
8Clavinet16Dulcimer
ORGAN GUITAR
17Drawbar Organ25Nylon String Guitar
18Percussive Organ26Steel String Guitar
19Rock Organ27Electric Jazz Guitar
20Church Organ28Electric Clean Guitar
21Reed Organ29Electric Muted Guita
22Accoridan30Overdriven Guitar
23Harmonica31Distortion Guitar
24Tango Accordian32 Guitar Harmonics
BASS SOLO STRINGS
33Acoustic Bass41Violin
34Electric Bass(finger)42Viola
35Electric Bass(pick)43Cello
36Fretless Bass44Contrabass
37Slap Bass 145Tremolo Strings
38Slap Bass 246Pizzicato Strings
39Synth Bass 147Orchestral Strings
40Synth Bass 248Timpani
ENSEMBLE BRASS
49String Ensemble 157Trumpet
50String Ensemble 258Trombone
51SynthStrings 159Tuba
52SynthStrings 260Muted Trumpet
53Choir Aahs61French Horn
54Voice Oohs62Brass Section
55Synth Voice63SynthBrass 1
56Orchestra Hit64SynthBrass 2
REED PIPE
65Soprano Sax73Piccolo
66Alto Sax74Flute
67Tenor Sax75Recorder
68Baritone Sax76Pan Flute
69Oboe77Blown Bottle
70English Horn78Skakuhachi
71Bassoon79Whistle
72Clarinet80Ocarina
SYNTH LEAD SYNTH PAD
81Lead 1 (square)89Pad 1 (new age)
82Lead 2 (sawtooth)90Pad 2 (warm)
83Lead 3 (calliope)91Pad 3 (polysynth)
84Lead 4 (chiff)92Pad 4 (choir)
85Lead 5 (charang)93Pad 5 (bowed)
86Lead 6 (voice)94Pad 6 (metallic)
87Lead 7 (fifths)95Pad 7 (halo)
88Lead 8 (bass+lead)96Pad 8 (sweep)
SYNTH EFFECTS ETHNIC
97FX1(rain)105Sitar
98FX2(soundtrack)106Banjo
99FX3(crystal)107Shamisen
100FX4(atmosphere)108Koto
101FX5(brightness)109Kalimba
102FX6(goblins)110Bagpipe
103FX7(echoes)111Fiddle
104FX8(sci-fi)112Shanai
PERCUSSIVE SOUND EFFECTS
113TinkleBell121GuitarFretNoise
114Agogo122BreathNoise
115SteelDrums123Seashore
116Woodblock124BirdTweet
117TaikoDrum125TelephoneRing
118MelodicTom126Helicopter
119SynthDrum127Applause
120ReverseCymbal128Gunshot

 Infos

Miscellaneous...

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 !

Requirements

The current version of sunnYmidi runs on:
  • MacOS system from version 10.12 and up.
  • LiveCode IDE/engine from Version 8.0 and up.
  • Since 2019, this external has been built for 64 bits only.

For DJ's 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.

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.

This documentation is provided by Thierry Douez. You can download and use this demo only within the LiveCode IDE. If you have used this liveCode external, please pay the developer's effort by Tweeting, sharing on Facebook, social mention or with a linkback. Enjoy! :)