Version 17 of midistreamdll

Updated 2009-12-10 07:49:45 by jdc

This is a wrapper for the Windows Midi stream API.

News

Man page

<<doctool>> comment {-*- tcl -*- doctools manpage} manpage_begin midistreamdll n 0.4 copyright {2007-2008 Jos Decoster <[email protected]>} 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 [L1 ] section 9.3 for an example.
Category Music