DxMidi Tutorial - MidiModule project - chapter 2
To follow this tutorial you need :

• RealBasic 2
• DxMidi plugin
• OMS (Opcode Music Studio)
• Download example 2
(chap02.rbp)

BACK TO SUMMARY


Project 2 - signing to OMS studio and send notes

First, open the midi02.rbp project. It is the OMS connection program.
The simplest as we could write with DxMidi.

- Verify that OMS is active (report to the OMS installation guide included in this manual),
- test the OMS Midi connection with the test function (in the OMS application).
- put "DxMidi plugin in the "plugins" folder of the Realbasic application, if it don't exists, create it and put DxMidi plugin into.

Project window

Open the project and examine the items :

Menu item :
We don't need to change it for this program.

App : Application :
This module is useful to sign in and out to the Midi driver for a program-duration scope.

Midi :
Just a module to keep specific Midi code and maintain global variables reserved for Midi. A clear way to write a good program.

Win:
Unlike the first project, here, we do something with the program : play notes.
This window is able to let you push a button to play the notes.

Application Midi client scope

Because most of Midi applications needs to sign to Midi at start, and sign out at end, we need to do the same with an "Application" module wich is specific to RealBasic system. it permits to open the program without opening first a window. There will be times when you want just to start application without opening a window !
Keep in mind that if you close the window, you don't know when you will sign out for Midi driver, and Midi Manager don't like that a client forget to sign out ! and sign in twice after that !

Make like this to maintain good client relation with the Midi driver, and force application to sign out at the end.


This is typically the way to sign IN and OUT to the Midi driver !
When the application starts, "Open" event executes your Midi SIGN IN code, and "Close" event executes your Midi SIGN OUT when the application close.
(if the application crashes, there will be always a Midi sign out missing !).
We will see how to prevent from this problem later.

NOTE : OMS has a specific system to prevent crashes because of sign out missing. It lets you reconnect to Midi even after a program crash.

Application : "Open" event

This procedure executes two methods :

Connect_midi is a custom method to connect DxMidi to the driver
win.show opens the "miditest" window and shows its contents.

Application : "Close" event

When close is executed, at the end of the program, disconnect_midi, examines Midi connection and sign out to the driver if the connection was active. By this, you are shure that the client has sign out at the end, without any other code elsewhere.

Win (window) : Use


This window is used to let the user play notes. You will see later the "Play a note" button content.

 

Midi module

This module maintains ours connect_midi and disconnect_midi methods.
It maintains too the global variables for Midi usage.

Open the module (double-click on it). And see the code.

This is the connection code. Just to connect to OMS as a "client".

You can see also the global variables (properties of the "Midi" module).
channel_in : maintain the midi IN channel value
channel_out : maintain the midi OUT channel value
oms_connected : this value keeps the client state. if TRUE, then the application is client of the driver until you sign out with the driver.
in_nodes : maintain the number of Midi IN "ports"
out_nodes : maintain the number of Midi OUT "ports"
select_in_node : maintain the current Midi IN "port"
select_out_node : maintain the current Midi OUT "port"

 

Midi connection

This is the OMS_connect code :

Let's analyze this code :

avail = DxMidiOMSAvail()

This method let you know if OMS is ready to be used, or not. It is very important to start with this method because if OMS is not ready, any other method called to OMS interface could create an error in the program.

avail contains TRUE if OMS is active.

result = DxOMSConnect("dfmm", "spocky3")

This time, we try to connect to the OMS Midi port and sign in the studio. This is required to do something more with OMS.
"dfmm" is a unique OSType that could be the program creator code, and "spocky" would be the program title (this is just an example).

If DxOMSConnect is successful, the result contains 0, otherwise, result contains a DxMidi error code.

 

Get the nodes, and connect the IN and OUT ports

if oms_connected = true then

We can just get the nodes if oms_connected is true (to preserve from an OMS error in the program.

Initialize 2 values for counting the number of IN and OUT nodes

in_nodes = 0
out_nodes = 0

First, get the OUT nodes
result = DxOMSGetNodes(0)

The 0 values indicates to DxOMSGetNodes to get the OUT nodes ports
This method replies an integer : this is the number of nodes available.

At this time, you don't really know what is in each value between 1 and the number of nodes, but in this example we only use the first value found. If result is 0, then sorry but there is no OUT node connected in your studio.

select_out_node = 1

This is the choice we mad to connect. But be careful... this value is not the best way to select a node. We will see a better method in the next chapter.

result = DxOMSPlugOutNode(select_out_node)

This method is called to create a link between the external Node and your program interface. At this time, you are really connected and you can send events in the OUTput port.

Next, do the same thing with the INPUT nodes ports

' get the nodes IN list
result = DxOMSGetNodes(1)
if result > 0 then
in_nodes = result
select_in_node = 1
result = DxOMSPlugInNode(select_in_node)
else
in_nodes = 0
end if

NOTE : This time, DxOMSGetNodes uses 1 to select INput nodes.

 

Midi disconnection

This time, we just have to close the connection if it is active.
We have a global variable called oms_connected that maintains this information.

Just test this value and close the client session is it is TRUE.

if oms_connected = true then
result = DxOMSdisconnect()
oms_connected =
false
end if

You don't have to set anymore oms_connected after DxOMSdisconnect() but just do it for clearity of the program.

Next step : test the program, with OMS, play the notes in the "win" window

Open the "Win" window edit window

"Win" is opened just after the Midi connection. To prevent any problem, this window only appears if your program successfully connects to OMS studio.

If you don't do that, you really create problems in your program !

The Win window contains 2 buttons.

With the second one, you quit the app... ok !

But the first let you play notes on the channel 1, and to the first node of the list...
In the worst case, you can just play notes with QuickTime components !! not so bad !

With DxDurNote, you tell the output to send synchronously note events to the OUT port of your program, and with the specific duration (1/60th of a second) by value.

parameters :

1 = channel one
i = this variable set the note pitch (by MIDI semitone, see reference tables)
64 = the velocity (from 0 to 127, 64 is the mf, mezzo-forte value)
4 = the duration (=4/60th sec.)


NOW, RUN the program and test your button....

You ear music ?

No ? verify your synth, the midi junction, test again your studio in OMS setup app

No more ? change the note channel, change the node number (within the node count).

No more music ?... hum! do you ear your cat in the kitchen... it's very hungry no, Mr Beethoven ???!!

 

EXERCISES :

1/ Create a combo box in the Win Window to let the user selecting an output node

2/ Create a combo box in the Win Window to let the user selecting a midi channel

3/ Create seven buttons of bevels, calls them C,D,E,F,G,A,B, in the Win Window to let the user play music

 

In the chapter 3,
we will see how to receive notes in MM and OMS programs.

(c)1999 - RealVision software

BACK TO SUMMARY