Contents
1.Introduction/Purpose
2.Basic Usage
   2.1 Getting started
   2.3 Menu Commands
   2.2 Option Settings
3.Advanced Usage
   3.1 The different methods
   3.2 Delay and effect slides
   3.3 The Cut/Retrigger command
   3.4.Effects/MIDI controllers
   3.5 Some explanations about MIDI data
   3.6 NRP for AWE32/64
   3.7 Timing/synchronizing
4.History
5.Plans/Future/Missing Things
Contacting the author

1.Introduction/Purpose
This is a first implementation of a MidiOut Machine for BUZZ. It is to regard as beta and will maybe heavily changed in the future, although I already tried to prepare all needed parameters. I guess a MIDI out machine generally isn't that suited for distributed songs, because it will behave and sound different on every computer. The main purposes may be using BUZZ to make music with all your MIDI-equipment (and mixing all together by other means than BUZZ itself) and the possiblility to sync another device or programm with BUZZ.

Some remarks:
Synchronizing with a MIDI sequencer and external devices should work fine now, also it may be possible to share a DirectX wavedevice with softsynths like Rebirth. I doubt the Wavein machine already is adequate for the mixing task (to get any external sounds back into a final mix), but haven't tried it yet. I don't know how the VirtualAudioCable fits in yet, but Hubis MidiLoopback Device and MidiCable sure help a lot.
More exotic usages would be controlling BUZZ parameters via MIDI, either by the MidiOut machine itself or with a (synchronized) sequencer, the latter would finally allow to change parameters live and record this with the sequencer ;)
Concerning the MIDI conversion and merging options of m2buzz there is now a possibility to output a single starting MIDI note with BUZZ, record this with the sequencer together with any live played material, which should make synchronizing of the converted voice with the rest of the song much easier :) Since m2buzz v3e you can also just convert MIDI files for use with the MIDIout machine, although controllers and tempo changes aren't processed yet.

Some more remarks:
I was asked about MIDI recording for BUZZ machines. For BUZZ 1.0 I see no way to implement this for a machine, this should be dealt with in the main program. But I guess it is quite easy to implement (monophonic at least) MIDI playability for any generator, although I know in general this are more than my 2 lines of code for doing it in the MIDI machine ;)

2.Basic Usage
The machine is designed to be fit for everything else than SysEx, for all the missing things look below. To get it working, put it into the Gear/Generators directory and choose the devices you want to use in the BUZZ Preferences/Midioutput, they will be opened by BUZZ and stay this until you terminate BUZZ or uncheck them. Set the device for a vMidiOut machine in the options dialog, since version 1d you can just do this by name without remembering the device number (which will nonetheless be stored as normal BUZZ attribute of the machine). To adress several devices you need more MidiOut machines (since version 1b). You also have to connect every machine to the master and set a volume greater zero, although it doesn't produce any sound. Don't worry, CPU times seem to be very low.

I'm aware that this machine seems a bit complicated, but keep in mind that in difference to other generators it is used to control very different kinds of MIDI equipment, so it has to have this lot of parameters. And BUZZ 1 doesn't seem best adapted for MIDI integration, so I had to go around several corners to get some things done, but finally I really can use this machine. And if you just start with the simple things in the next chapter, you will be able to use this as well ;)

2.1 Getting Started
After you have set up the machine and BUZZ for using one of your MIDI devices, you can use the notes in the first column like you would do with other BUZZ generators. If you're using a General MIDI device (like intern synthesizers of most sound cards) chances are great that you're listening to some piano sounds. You can change these sounds in the 5th column (MIDI patch) or with the slider in the parameters window.

The second column (velocity) is what volume is for other generators, only that the range is from 0...127(0x7f) with default 64(0x40) instead of double these values, sorry for this, I just used the MIDI standard here.

If you only want to let BUZZ play some melody, you don't need to deal with the channel value in the 4th column. But for using several voices or effects this is necessary: MIDI associates most events with one of 16 (logical) channels: most effects apply to all notes on one channel, and every channel has always only one active instrument. This instrument can be switched with every note you play, but it is more convenient to use different channels for different instruments.

This can be handled very easy with vMidiOut by also using a different channel for every BUZZ track. In this case you have to put the values for the channel and the instrument (=MIDI patch or MIDI program) only once: at the start of your song.

With General MIDI the channel number 10 (0x0a) has a special function: it's the drum channel, and the notes you play on this channel don't change the pitch of one instrument but trigger different drums.

The most useful effects to start with are probably the MIDI controllers 0x000a (volume) and 0x0007 (pan) as the BUZZ sliders don't work for this machine :( The pitch wheel (0x0101) and modulation wheel (0x0001) come handy as well. Of the things I implemented additionally to the MIDI standard I'm most excited about the cut/retrigger command (0x0120), because you won't find this in any sequencer. But with this we are already in the advanced usage topics I'll deal with below. The same goes for the delay, effect slides and synchronizing.

2.2 Menu Commands
The menu just has some reset functions (where all note-off functions can also be configured to sent with the BUZZ pause button) and the option settings.

If you've got a lot of hanging notes (especially if working without checked "monophone tracks" option), you can kill them with the following commands:
All notes off just sends MIDI controller 123 to the device on channel 1, which is very fast but doesn't work with some devices,
Stop all notes really sends a Note-Off for all 128 notes on all 16 channels, this is the PANIC button, but may several secondes on some devices.
If neither this doesn't help, you could try to disable the nasty device for a short time in the BUZZ preferences.
Reset controllers sends MIDI controller 121 to the device. It depends on the MIDI device if it really resets everything.

2.3 Option settings
In the options dialog you can change the following parameters:

• MIDI device: as explained above
• MIDI delay: If the method attribute of the machine is set to 4 or 5 all MIDI output can be delayed in the range from 0 (no delay) to 255 (delay ca. 1Row). For method 5 you probably should leave this at zero, while for method 4 you can use this to correct the gap between MIDI and wave output
• sync+: Although I tried hard to match the timing of other programs with BUZZ with MIDI sync messages, I was only partial successful. I'm really sure to always send 6 syncs per 1 BUZZ row and if failing to do so for any reason, inserting the missing messages softly a bit later (and not all at once). So I added this extra finetune option: after a certain number of BUZZ rows (which you can set here) I'm inserting an additional sync message (if the number is positive) or omitting one (if negative). The number I choose here is about 50, this will vary from machine to machine. This finally gives some satisfying synchronisation over several minutes.
• monophone tracks: You can switch off the default behaviour of the machine, to send a note-off for every new note it finds on a track. In this case every note-off just cancels the last note sent on this track, all others have to be switched off explicitely with a velocity off zero, so you'll probably soon end with a lot of hanging notes ;)
• MIDI play/channel: not very useful for a MIDI machine, if checked the machine listens to the selected MIDI channel (0-15) of the device you choosed as BUZZ MIDI input and repeats every note on the output MIDI device with the same channel, note value and velocity. This is like MIDI through, but for note messages only.
• allow timer You should try the new sync command 0x0110 instead of the timer sync command 0x0113, it seems to be better and doesn't use an extra timer. You have to explicitely allow the usage of the old timer sync command 0x0113 for a machine with this option. Keep in mind that for every machine you use this command one of a limited numbered of timers is needed. Generally you should have this checked for maximal one machine in the song. The timer resolution of 5ms generally shouldn't be changed and is also the only of the parameters here, which isn't saved with the song.
  
• BUZZ pause options: You can configure the messages, the machine will send, if the BUZZ pause button is pressed. The "all note off message" would be controller 123 on channel 1, which is great for getting rid of the hanging notes, if your MIDI device supports it. If not, choose "all note-offs" here.
  The "sync stop message" depends on the device/program you want to sync with BUZZ. The sync messages (0xf8) will be stopped in every case, but some programs explicitely need the stop messages to stop their timer, while my sequencer already pauses completely without sync messages, but would leave the "extern MIDI sync mode" with a stop message.
  The BUZZ continue options apply only if you have stopped a running sync and it get's restarted by the "sync refresh" commands (0x0110 0x0000 or 0x0113 0x0000)

3.Advanced usage information
The machine allows 16 tracks, default for every track is MIDI channel 1 at startup. You can change the channels in the corresponding column of the track as you like, several tracks can access one MIDI channel, so it's possible to apply different controllers together. Drum channel generally is 10 (0x0a). This has to be set only once (at the start of the song) and will be remembered later.

If you choose an instrument number a program change message will be sent to the actual channel, so you also only should do this at the start of the song or if you want to change the actual patch. Now every note will be transmitted, default velocity is 64 (0x40), highest possible 127 (0x7f). If you use the default of "monophone tracks", an already running note will be canceled. If not and you only have one running note, a note-off or just a zero in the velocity column will stop it, otherwise only the last one stops and all other have to explicitely switched off with the note-number and a zero velocity.

To reduce the amount of typing into the BUZZ track columns, you have to set only one of the three effect columns. The others are replaced by the last value you've put in there or some defaults (for the effect-slide byte this is to do no sliding at all, and the sync commands generally behave different with or without data values). So if you're working with one effect per track only (during some rows or patters at least), you have to set the effect kind only once together with a starting value for the data. Later only set the data or just the "Slide-To value". After a slide this value will be used as default data instead of the last data value.

3.1 The different methods
Here is a summary of the advantages and disadvantages of the different methods you can use as attribute for the machine.

• method 0: simple timing
  +very few CPU usage
  +compatible, should work on every PC
  -not realtime, is a bit early (up to one row), especially no sync between MIDI and WAVE output
  -only timer sync
  -no delay, slide, retrigger
  
• method 3: event based timing
  +very few CPU usage
  +compatible, should work on every PC
  +sync between MIDI and WAVE output, (-) maybe disturbed by high CPU usage
  -(was?) a bit unstable, gave some crashes for me
  -only timer sync
  -no delay, slide, retrigger
  
• method 4: wave based timing
  +delay, slide, retrigger
  +new wave based sync without timer (but why is this incorrect again?)
  +sync between MIDI and WAVE output, (-) has to be adjusted with mididelay
  -not tested much yet (was just a step on the way to method 5, but may still have some advantages)
  -maybe dependent on system + driver + BPM settings settings (for me it works with 125 BPM and a latency of about 100 ms, but doesn't with <50ms or >110 ms)
  
• method 5: event+wave based timing
  +delay, slide, retrigger
  +new wave based sync
  +sync between MIDI and WAVE output (automatical)
  -system dependency? (similar method 5)
  -some still unfixed crashes
  

I hope to have fixed most of the reasons method 3 crashed before, but casually I still got some crashes while closing a song. Currently I'm just using a delay of a quarter second to avoid these, but this of course takes some time if you've got a song with several MIDI machines. Sorry for this, as soon I've found out the exact reason, I'll make a fixed version.

3.2 Delays and Effect slides
The delay and effect-change bytes are used only with the method attribute of the machine set to 4 or 5. The delay byte can be in the range from 0...0xff (255), the latter gives approximately a delay of a whole row. Currently it may happen, that high delays prevent the event from being triggered at all. If you've choosen a general mididelay for the machine, values are just added together.
The time resolution for the delay and the effect slides of course isn't 255/row, but system, driver and BPM dependent. The actual value is shown in the description field for the effect slide byte, or as minimal difference for the delays in the description for the delay columns. On my system (P200,AWE32) for instance it's about 30/row for 125 BPM with the DirectX driver at a resolution of 4 and a latency of 100ms and gets lower with a higher BPM rate or less latency.
Effect slides are currently implemented for continuous MIDI controllers 0x0001...0x0061, all NRP's and the pitchwheel. You just put the MSB (most significant byte = higher byte) of the effect data value you wish to slide to until the next row into the effect change column (the last one). This would look like

  Note  Vel Del Chan  Patch  Effect   EData  Slide 

   C-4  ..  ..  ..     10     0007    fffe    80   

   ..   ..  ..  ..     ..      ..     8000    01   

   ..   ..  ..  ..     ..      ..     0000    ..   

3.3 Cut and Retrigger
The lower byte of the data for the cut/retrigger command (0x0120) is a delay in the same format as the mididelay or the delay column. The higher byte gives a counter for the events to happen, that means 0 just toggles note off after the delay(=cut), 1 starts it again immediately after the cut (=Retrigger), 2 cuts again after another delay and so on.
This way every even number let's you with the note cut off, every odd one with a note-on. If there's an event on the next row the process of retriggering is stopped after reaching it and again the delay values near 0xff aren't reached for sure. If there's no new event, the retrigger process may last about several rows.

3.4 Effects/MIDI controllers
You can apply a lot of effects, which generally depend on your MIDI-equipment. If you just use the effect data column the last applied effect is used. You can try to reset all controllers with the command in the machines menu, it just sends controller 121. Since I wanted to have a full 16Bit range for some of the effects, but also wanted to allow using the BUZZ parameter sliders, I expanded the data ranges of continuous controllers to 16Bit (with version 1b). Some mesages need exact values, so I tried to keep them (controller 0 and 98-127 currently). There probably will be more changes here in the future :]

Effects	MIDI events	MIDI Data Range	BUZZ Data Range (if different)
0x00xx	(7Bit) Midi Controller xx (0-0x7f) (Ctrl 0-31 are MSB and 32-63 LSB of 14Bit ctrl)	0-0x7f	ctrl 1-97: 0-0xfffe (shifted 9Bit left) ctrl 0,98-127: 0-0x007f (=MIDI)
	00:Bank change
	01:Modulation wheel
	02:Breath controller
	04:Foot Pedal
	05:Portamento Time
	07:Volume
	08:Balance??
	0x0a (10):Pan
	0x0b (11):Expression
	0x20-0x3f (32-63):least significant bytes of controllers 0-31 for 14Bit precision
	0x40-0x5f (64-69):Switches	0:off 0x7f:on
	0x40 (64):Sustain
	0x41 (65):Portamento
	0x42 (66):Sustenuto
	0x43 (67):Soft
	0x44 (68):Legato
	0x45 (69):Hold 2 Pedal
	0x5b (91):Reverb
	0x5c (92):Tremolo
	0x5d (93):Chorus
	0x5e (94):Celeste Level
	0x5f (95):Phaser Level
	0x60 (96):Data Button increment
	0x61 (97):Data Button decrement
	0x78(120):All sound off (??)	0
	0x79(121):Reset all controllers	0
	0x79(122):Local Mode off/on	0 or 0x7f
	0x7b(123):All notes off	0
	0x26/62/63 (38/98/99):NRP (see below)
	0x06/64/65 (6/100/101):RP (pitchbend range, see below)
0x0080-0x00ff	14 Bit Midi Controller 0x80+xx (not implemented yet)	0-0x03fff	0-0xfffe (shifted 2Bit left)
0x0101	Pitchwheel	0-0x3fff (default:0x2000)	0-0xfffe (shifted 2Bit left) (default:0x8000)
0x0102	Channel pressure (Aftertouch)	0-0x7f	0-0x7f
0x0103	Key pressure (Aftertouch)	2 Byte(note+pressure)
0x011x	Sync macros
	0x0110: syncing		....(no value): start 0000: refresh sync
	0x0111: stop syncing		....(no value): sends sync stop message 0xfc 0000: dont send 0xfc
	0x0112: wave sync (!obsolete)
	0x0113: start time sync		....(no value): get timerrate from BPM 0000: refresh sync xxxx: set timer rate (in ms)
0x0120	cut/retrigger		0xAABB: A=count,B=delay even A cuts, odd A retriggers
0x01fx	System message fx
	f0:sysex (no way to implement this here)
	f2:song position (in beats)	0-0x03fff	no 14 bit yet
	f3:song select	0-0x7f
	realtime messages:	none
	f8:timing clock (to be sent 6 times per Beat)
	fa:start
	fb:continue
	fc:stop
	fe:active sense
	ff:system reset
0x02xx	7Bit NRP xx (short cut, see NRP )	0-0x07f	0-0xfffe (shift 9Bit left)
	00: LFO1 delay
	01: LFO1 frequency
	02: LFO2 delay
	03: LFO2 frequency
	04: Envelope1 delay
	05: Envelope1 attack
	06: Envelope1 hold
	07: Envelope1 decay
	08: Envelope1 sustain
	09: Envelope1 release
	0x0a (10) Envelope2 delay
	0x0b (11) Envelope2 attack
	0x0c (12) Envelope2 hold
	0x0d (13) Envelope2 decay
	0x0e (14) Envelope2 sustain
	0x0f (15) Envelope2 release
	0x10 (16) Initial pitch
	0x11 (17) LFO1 to pitch
	0x12 (18) LFO2 to pitch
	0x13 (19) Envelope 1 to pitch
	0x14 (20) LFO1 to volume
	0x15 (21) Initial Filter Cutoff
	0x16 (22) Initial Resonance (Filter-Q)
	0x17 (23) LFO1 to Filter Cutoff
	0x18 (24) Envelope 1 to Filter
	0x19 (25) Chorus
	0x1a (26) Reverb

3.5 Some explanations about MIDI data
I'm not that MIDI expert and just tried to apply the information I collected from several sources and bring them into an useful form for the MidiOut machine. MIDI is a protocoll for communication between musical devices, which basically consists of a stream of bytes (8Bit), where the single bits are transmitted sequentially, like serial communication (mouse,modem) does, but with a higher bitrate. If the highest bit is set, the byte is a so called status byte, which means some kind of command, while without the highest bit there are only 7 bits remaining for data, that's just the range 0-0x7f (0-127) in the table. To complicate things, different commands/statusbytes need/allow different data, some combining two (7Bit) data bytes to a 14Bit value (range 0-0x03fff). For controllers 0-31 this get's even worse: you can decide for yourself, if 7Bit resolution are enough and just send one data byte, or if you need some finer adjustments sending the second (least significant byte:LSB) as controller xx+32 (32-63). Also the meaning of the controllers is only rarely standard with General MIDI just giving a start. I don't know much about GS and XG.

3.6 NRP for AWE32/64 (and RP)
The NRP (non registered parameter) stuff is especially useful for the AWE, at least with this values (don't know if there's some kind of standard). For instance if you use an effect 0x215, a value of 127 for controller 99 and a value 0x15 (21) for controller 98 will be sent for the current channel. After this the active controller will be set to 0x26 (38) to transmit the effectdata, sou you best should use only the effectdata after. If you want to apply several NRP to the same channel, you have to use the effect value everywhere, but it still seems to fail in this case.

Registered Parameter (RP) as part of the General MIDI standard
I've not added a shortcut for the RP's yet, but I also have found only few used ones:
To set the pitch bend range for a channel, set controller 0x64 (100) (RP LSB) to a value of 0, and controller 0x65 (101) (RP MSB) to a value of 0, then set controller 6 to the desired range in semitones (up to 12).
RP's 1 and 2 are fine and coarse tune, no idea about the parameters.

3.7 Timing/Synchronizing
To sync a sequencer with BUZZ, you would select some option like "MIDI Sync" there, connect BUZZ and the sequencer with Hubi's LoopBack device (or any other of that kind) and BUZZ would have to send a sync start message (=effect 0x01fa), a stop (= 0x1fc) and between a lot of sync timer messages (=0x1f8).
But only one sync message per row isn't enough, you need 6 of them, and this with as equal distance as possible. This was the thing, which should be easy to achieve (BUZZ manages several times 44100 samples the second, shouldn't it manage these 6 syncs in a row?), but nonetheless was rather hard to implement, and even now has (still?) some drawbacks.

One simple solution is to set the TBP rate to 6*4=24 and use only every 6th line for your song (but you don't have to) and every line for a sync message 0x01f8. This should get you going, but the resulting patterns are hard to deal with.

To get timing more correct I used the event mechanism of the BUZZ machine interface, so at least a synchronisation between Wave and MIDI output can be achieved (method attribute set to 3 or 5).

Further I experimented with an own timer, which is based on the BUZZ BPM and TBP settings, but else works independent from the BUZZ timing (sync command 0x0113). This came close, but had a lot of disadvantages:
-limited timer resources
-distortion of BUZZ timer ?
-even best resolution of 1ms matches only distinct BPM rates, for instance 119 BPM <-> 21ms, 125 BPM <-> 20ms, 131 BPM <-> 19ms, the formula is

             time_ms=60000/ BeatsPerMin/6/TicksPerBeat;

The last implemented method is based on the wave based timing of the methods 4 or 5 and basically just tries to always send 6 sync messages between two BUZZ rows. Even succeeding with this there was no perfect sync, so I added the sync fine tune option, which adds or removes a sync message after several rows. This finally gave kind of satisfying results over several minutes, but still may break due to computer activity or ???

To use this you would make 3 patterns for vMidiOut. In the start pattern place a command 0x0110 .... in the first row, followed by all other lines set to .... 0000. The second pattern, which just refreshs the sync and has to be repeated the whole sequence, just consists of .... 0000 (or maybe a 0x0110 0000 in the first row). The last pattern to stop the sync messages has a single 0x0111 in it (either a 0x0111 .... to send a final stop message or a 0x0111 0000 to leave this out).

• any way of further improving timer sync or new wave based sync?
• correct handling of 14Bit controllers and NRP's
• cross NRP's (2 tracks ->1 channel, needs extra messages for slide)
• easy slides option? (for systems with high latency only):
  probably not, it's easy enough now
• another version with velocity [0...0x7f] ->volume [0...0xfe] and 16Bit Effect Change ?:
  probably not before everything else is working nice enough

contact me: ( vII) or look at my Homepage