Get ready...

To start using HyperMIDI, simply use the hmOpenMIDI command. You need to make this call once in your application before you can use other HyperMIDI commands. For instance, you'd place this command in your openStack handler in HyperCard, or your startMovie handler in Director.

  on OpenStack
    hmOpenMIDI
  end openStack

Similarly, you'll also use an hmCloseMIDI command when you're done using HyperMIDI (in HyperCard, you'd place it in a closeStack handler, for instance).

...Go!

Now you're ready to use the other HyperMIDI commands. To play a MIDI file sequence, for example, use the hmPlay command with the file name in any script:

  hmPlay "HD:Song folder:Earthshake"

When this command executes, the song starts playing, but doesn't tie up your computer. Script execution continues, and you can do anything you normally do—even edit and debug, or switch to another application—while the sequence plays "in the background".

You still have complete control of the sequence. You can transpose it while it's playing, scale the velocity and send controller messages to adjust the volume, send program changes to change its voicing, alter its tempo, and mute individual tracks. You can also stop it—for instance if the user makes a choice that should turn off or change the music. And you can ask HyperMIDI is the sequence is done playing, so you can move on in a presentation when the music finishes, for instance.

Or you can loop a song an endless (or specific) number of times, and stop it when the user does something to move on.

MIDI files, instruments, and algorithms

Sequences don't have to come from MIDI files. You can MIDI record directly from a MIDI device. Or, you can script any MIDI sequence, including timing. This script plays a chromatic scale:

  put 0 into time
  get hmClock("time",0)   -- set clock to 0
  repeat with note = 60 to 72
    hmWriteMIDI 1,time & ":" & 144 & note & 64 & time + 100 & 144 & note & 0,"timeMode abs"
    add 200 to time
  end repeat

Because HyperMIDI schedules the events to play at the requested time, the above script plays in perfect time, independent of how fast the script executes! Here's another example, which plays 40 random notes over a two octave range, with random velocity: 

  put 0 into time
  get hmClock("time",0)   -- set clock to 0
  repeat for 40
    put random(24) + 59 into note
    put random(127) into vel
    hmWriteMIDI 1,time & ":" & 144 & note & vel & time + 100 & 144 & note & 0,"timeMode abs"
    add 200 to time
  end repeat

Recording directly into HyperMIDI is simple because there is no record "mode"—HyperMIDI is always listening to MIDI input, time stamping and buffering it even when you are doing other things. This example captures all MIDI input that has come in since you last read (or cleared) the input: 

  put hmReadMIDI(1,-1,"track") into mySequence

To hear it back, in in the exact timing in which it was played: 

  hmWriteMIDI mySequence

To save it as MIDI file: 

  get hmMIDIFiler("write",mySequence,"Song Title")

return