Documentation SunnYmidi (2019)

X Getting Started

Get SunnYmidi

Download the latest version of SunnYmidi here. 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. 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.

Play/Stop a Note

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

Irregular Arpeggio

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.

 #  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 and its ID, using an 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.

 put SunnYmidi.Get( "numberOfInstruments" )
 # -> 235
 #  SunnYmidi.Get( "instrument", index )
 put SunnYmidi.Get( "instrument", 33 )
 # -> 7929872,Santur

Instrument Name/ID

To play some notes with a specific instrument, you need to bind an instrument ID to a Midi channel where instrument_ID is an integer defined by the Apple DSL Synth. Be careful not to mix the instrument_ID and the index.

 put 2 into channel
 put SunnYmidi.Get( "instrument", 33 ) into instrument_ID
 SunnYmidi.Set channel, "instrument", instrument_ID

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 stuff

Notes Chart

MIDI Music Note Chart
Octave # 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

- Extras

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 !

Requirements

The current version of SunnYmidi runs on:

  • MacOS system from version 10.10 and up.
  • LiveCode IDE/engine from Version 8.0 and up.

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.

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

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! :)