This is a wrapper for the Windows [Midi] stream API.
**News**

   * [jdc] 10-jul-2009. Source code and downloads now available at http://code.google.com/p/tclmidi 
   * [jdc] 20-mar-2008. Initial public release.

**Man page**

<<doctool>>
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin midistreamdll n 0.4]
[copyright {2007-2008 Jos Decoster <jos.decoster@gmail.com>}]
[moddesc {Wrapper for the Win32 Midi stream API}]
[titledesc {Wrapper for the Win32 Midi stream API}]
[require Tcl 8.5]
[description]

[para]

This page describes the Tcl [package midistreamdll] package, a wrapper for the
Win32 Midi stream API. Commands to query the available Midi devices, open a Midi
stream device and send Midi data to it are discussed here.

[para]

The [package midistreamdll] package adds the namespace midistreamdll to the Tcl
interpreter in which it is loaded. In this namespace, the main commands to
work with midi stream are created:

[list_begin definitions]
[lst_item midistreamdll::devs]
[lst_item midistreamdll::open]
[lst_item midistreamdll::header]
[list_end]

[section midistreamdll::devs]

[list_begin definitions]

[call [cmd midistreamdll::devs]]

This command returns a list of names of the available Midi devices. 

[list_end]

[section midistreamdll::open]

[list_begin definitions]

[call [cmd midistreamdll::open] [arg deviceId]]

This command will open the specified Midi stream device and returns a unique
Midi stream device id. This id should be used to manipulate the Midi device
later on. A Midi device is specified as an integer index in the list of Midi
devices as obtained with the [cmd midistreamdll::devs] command.

[call [arg midiStreamId] [method close]]

Closes the Midi stream devices.

[call [arg midiStreamId] [method out] [arg headerId]]

Stream the specified Midi header, which must be created with the 
[cmd midistreamdll::header] command, to the Midi stream device.

[call [arg midiStreamId] [method pause]]

Pauses the Midi stream device.

[call [arg midiStreamId] [method play]]

Starts playback of the Midi stream device.

[call [arg midiStreamId] [method position]]

Returns the current position in the stream being sequenced as Midi ticks.

[call [arg midiStreamId] [method set] [arg option] [arg value]]

Set the specified option. Known options are:

[list_begin opt]

[opt_def -timediv integer]

Set the number of ticks per beat.

[opt_def "" ""]

[list_end]

[call [arg midiStreamId] [method short] [arg byte0] [opt [arg byte1]] [opt [arg byte2]]]

Immediately plays a short event on the Midi device.

[call [arg midiStreamId] [method stop]]

Stops playback of the Midi stream device.

[list_end]

[section midistreamdll::header]

[list_begin definitions]

[call [cmd midistreamdll::header]]

This commands creates a new Midi header, suitable for use with the Midi stream
[cmd out] command and returns a unique header id. This id should be used to
manipulate the Midi header later on.

[call [arg headerId] [method add] [arg eventType] [arg deltaTime] [arg eventData]]

Adds the specified event data to the Midi header with specified
delta-time. Known event types are:

[list_begin opt]

[opt_def event "deltaTime byteList"]

Adds event specified as a list of bytes to the Midi header. When an empty list
is specified, a nop event is added. For 1 up to 3 bytes, the data is added as a
short event. For more bytes, the data is added as a long event.

[opt_def long "deltaTime byteList"]

Adds event specified as a list of bytes to the Midi header. 

[opt_def nop deltaTime]

Adds nop event to the Midi header.

[opt_def short "deltaTime byte0 ?byte1 ?byte2??"]

Adds one, two or three bytes to the Midi header as short event.

[opt_def tempo "deltaTime tempo"]

Adds tempo event to the Midi header.

[opt_def "" ""]

[list_end]

[call [arg headerId] [method destroy]]

Destroys the Midi header.

[list_end]

[keywords midi stream]
[manpage_end]
<<doctool>>

**Examples**

***Midi file sequencer***

In the examples directory in the zips, you'll find `seq.tcl`, a midi file sequencer. This example uses the [tclMIDI] package to read Midi files.

======
package require midi
package require midistreamdll

# Create a midi stream header, this header will be used to send event to the
# sequencer.
set h [midistreamdll::header]

# Load the midi file specified on the command line
set mf [midi::file]
$mf read [lindex $argv 0]

# Add events to header, skip SysEx and non-tempo Meta events
set cnt 0
foreach te [$mf flatten -no_sys_ex 1 -include_meta {tempo}] {
    $h add event {*}$te
    incr cnt
}

puts "Streamed $cnt event"

# Open a midi stream device
set s [midistreamdll::open 0]

# Set the ticks per beat
if {[$mf cget -time_division_type] eq "ticks_per_beat"} {
    $s set timediv [$mf cget -ticks_per_beat]
}

# Send header to the device
$s out $h

# Sequence the events
$s play

# Wait until header is released by the sequencer
while 1 {
    if {![catch {$h destroy}]} {
        break
    }
    puts "@ [$s position]"
    after 1000
}

# Cleanup
$s close
$mf destroy

exit
======

***Drum machine***

In the examples directory in the zips, you'll find `drums.tcl`, a little drum machine.

[WikiDbImage drums.png]

[AMG]: The user interface looks a bit like the screenshot I have posted on [Possible Grid Enhancements], except that mine is all screwed up. :^)

**Questions / remarks**

   * MiR 21. March 2008: Ok, actually the examples from the packages are missing, otherwise its working fine on my WinXP machine. Thx for the work, please post the drum and seq. sample.... [jdc] 21-mar-2008: The link was wrong, it's updated now.

   * [D. McC] 2008 Mar 29: Is there anything similar for unix?! [jdc] 31-mar-2008 On linux writing to /dev/midi should be possible. Check [http://www.faqs.org/docs/Linux-HOWTO/MIDI-HOWTO.html] section 9.3 for an example.

----

!!!!!!
%| [Category Music] |%
!!!!!!