NAME

Win32API::MIDI - Perl extension for MS Windows 32bit MIDI API

SYNOPSIS

use Win32API::MIDI;
$midi = new Win32API::MIDI;

# MIDI::Out::ShortMsg
$mo = new Win32API::MIDI::Out	or die $midi->OutGetErrorText();
$mo->ShortMsg(0x00403C90)	or die $mo->GetErrorText();
sleep(1);
$mo->ShortMsg(0x00003C90)	or die $mo->GetErrorText();
$mo->Close			or die $mo->GetErrorText();

See "EXAMPLE" for more examples.

DESCRIPTION

Overview

Win32API::MIDI is a wrapper for MS Windows 32bit MIDI API. It supports all MS Windows 32bit MIDI API, MIDI output, input, and stream API. For more details about each API visit http://msdn.microsoft.com/ and search for the word "MIDI".

This module is still under development. Interface may be changed to improve usability.

Querying MIDI Devices

$midi = new Win32API::MIDI

Returns a object for InGetNumDevs(), OutGetNumDevs(), InGetDevCaps(), OutGetDevCaps(), syserr(), InGetErrorText(), or OutGetErrorText().

$midi->InGetNumDevs(void)

Retrieves the number of MIDI input devices present in the system. Returns zero if there is no device.

$midi->OutGetNumDevs(void)

Retrieves the number of MIDI output devices present in the system. Returns zero if there is no device.

$midi->InGetDevCaps(DeviceID)

Retrieves the capabilities of a given MIDI input device and return this information in a hash data whose keys are "wMid", "wPid", "vDriverVersion", "szPname", and "dwSupport".

$midi->OutGetDevCaps([DeviceID = MIDI_MAPPER])

Retrieves the capabilities of a given MIDI output device and places this information in a hash data whose keys are "wMid", "wPid", "vDriverVersion", "szPname", "wTechnology", "wVoices", "wNotes", "wChannelMask", and "dwSupport".

$midi->syserr(void)

Returns the return value of the MIDI function called recently. Zero means no error.

The only MIDI functions that do not return error codes are the midiInGetNumDevs and midiOutGetNumDevs functions. These functions return a value of zero if no devices are present in a system or if any errors are encountered by the function.

$midi->InGetErrorText([wError])

Retrieves textual descriptions for the error codes given. If the error code is omitted, the error code for the MIDI function called recently is used.

$midi->OutGetErrorText([wError])

Retrieves textual descriptions for the error codes given. If the error code is omitted, the error code for the MIDI function called recently is used.

$midi->InGetDevNum(name)

Retrives the MIDI input device number whose szPname entry of the capabilityes list returned by InGetDevCaps() matches name. If there is no match, returns undef.

This is not a part of MS Windows 32bit MIDI API.

$midi->OutGetDevNum(name)

Retrives the MIDI output device number whose szPname entry of the capabilityes list returned by OutGetDevCaps() matches name. If there is no match, returns undef.

This is not a part of MS Windows 32bit MIDI API.

Recording MIDI Audio

Opening and Closing MIDI Input Device

$midiIn = new Win32API::MIDI::In(DeviceID, [Callback = undef, [CallbackInstance = undef, [Flags = CALLBACK_NULL]]]);

Opens a specified MIDI input device for recording.

For Flags argument only CALLBACK_NULL and CALLBACK_FUNCTION are supported now.

$midiIn->GetID(void)

Retrieves the device identifier for the given MIDI input device.

$midiIn->Close(void)

Closes the MIDI input device.

Managing MIDI Recording

$midiIn->PrepareHeader($lpMidiInHdr)

Prepares a MIDI input data block.

Preparing a header that has already been prepared has no effect, and the function returns zero.

After the header has been prepared, do not modify the buffer. To free the buffer, use the UnprepareHeader method.

Before using this method, you must set the lpData, dwBufferLength, and dwFlags members of the MIDIHDR structure.

The dwFlags member must be set to zero.

# Example of how to use PrepareHeader()
# create buffer
$buf = "\0" x 1024;
# make a pointer to MIDIHDR data structure
# cf. perlpacktut in Perl 5.8.0 or later
#     (http://www.perldoc.com/)
$midihdr = pack ("PLLLLPLL",
		 $buf,		# lpData
		 length $buf,	# dwBufferLength
		 0,		# dwBytesRecorded
		 0xBEEF,	# dwUser
		 0,		# dwFlags (must be zero)
		 undef,		# lpNext
		 0,		# reserved
		 0);		# dwOffset
$lpMidiInHdr = unpack('L!', pack('P', $midihdr));
# pass the pointer to PrepareHeader()
$midiIn->PrepareHeader($lpMidiInHdr);

$midiIn->UnprepareHeader($lpMidiInHdr)

Cleans up the preparation of a MIDI input data block.

$midiIn->AddBuffer($lpMidiInHdr)

Sends a buffer to the device driver so it can be filled with recorded system exclusive MIDI data.

$midiIn->Reset(void)

Stops MIDI recording and marks all pending buffers as done.

$midiIn->Start(void)

Starts MIDI recording and resets the time stamp to zero.

$midiIn->Stop(void)

Stops MIDI recording.

$midiIn->GetErrorText([$mmsyserr])

Retrieves textual descriptions for the error codes given. If the error code is omitted, the error code for the MIDI function called recently is used.

$midiIn->Connect($midi_thru_or_output)

Connects a MIDI input device to a MIDI thru or output device.

$midiIn->Disconnect($midi_thru_or_output)

Disconnects a MIDI input device from a MIDI thru or output device.

Playing MIDI

Opening and Closing MIDI Output Device

$midiOut = new Win32API::MIDI::Out([DeviceID = MIDI_MAPPER, [Callback = undef, [CallbackInstance = undef, [Flags = CALLBACK_NULL]]]]);

Opens a MIDI output device for playback.

For Flags argument only CALLBACK_NULL is supported now.

$midiOut->GetID(void)

Retrieves the device identifier for the given MIDI output device.

$midiOut->Close(void)

Closes a specified MIDI output device.

Sending Individual MIDI Messages

$midiOut->ShortMsg(Msg)

Sends a MIDI message to a specified MIDI output device.

$midiOut->PrepareHeader($lpMidiOutHdr)

Prepares a MIDI output data block.

Preparing a header that has already been prepared has no effect, and the method returns zero.

After the header has been prepared, do not modify the buffer. To free the buffer, use the UnprepareHeader method.

Before using this method, you must set the lpData, dwBufferLength, and dwFlags members of the MIDIHDR structure.

The dwFlags member must be set to zero.

A stream buffer cannot be larger than 64K.

# Example of how to use PrepareHeader()
# "Set Master Volume" System Exclusive Message
$buf = "\xf0\x7f\x7f\x04\x01\x7f\x7f\xf7";
# make a pointer to MIDIHDR data structure
# cf. perlpacktut in Perl 5.8.0 or later
#     (http://www.perldoc.com/)
$midihdr = pack ("PLLLLPLL",
		 $buf,		# lpData
		 length $buf,	# dwBufferLength
		 0,		# dwBytesRecorded
		 0,		# dwUser
		 0,		# dwFlags (must be zero)
		 undef,		# lpNext
		 0,		# reserved
		 0);		# dwOffset
$lpMidiOutHdr = unpack('L!', pack('P', $midihdr));
# pass the pointer to PrepareHeader()
$midiOut->PrepareHeader($lpMidiOutHdr);

$midiOut->UnprepareHeader($lpMidiOutHdr)

Cleans up the preparation of a MIDI output data block.

$midiOut->LongMsg($lpMidiOutHdr)

Sends a buffer of MIDI data to the specified MIDI output device. Use this function to send system-exclusive messages to a MIDI device.

Misc.

$midiOut->GetErrorText([mmsyserr]): Retrieves textual descriptions for the error codes given. If the error code is omitted, the error code for the MIDI function called recently is used.
$midiOut->Reset(void): Turns off all notes on all channels for a specified MIDI output device. Any pending system-exclusive buffers and stream buffers are marked as done and returned to the application.
$midiOut->Connect($midi_output): Connects a MIDI thru device to a MIDI output device.
$midiOut->Disconnect($midi_output): Disconnects a MIDI thru device from a MIDI output device.

Sending MIDI Messages with Stream Buffers

$midiStream = new Win32API::MIDI::Stream([DeviceID = MIDI_MAPPER, [Callback = undef, [CallbackInstance = undef, [Flags = CALLBACK_NULL]]]]);

Opens a MIDI stream for output. By default, the device is opened in paused mode.

For Flags argument only CALLBACK_NULL is supported now.

$midiStream->Close(void)

Closes an open MIDI stream.

$midiStream->PrepareHeader($lpMidiInHdr)

Prepares a MIDI stream data block.

Preparing a header that has already been prepared has no effect, and the function returns zero.

After the header has been prepared, do not modify the buffer. To free the buffer, use the midiInUnprepareHeader function.

Before using this function, you must set the lpData, dwBufferLength, and dwFlags members of the MIDIHDR structure.

The dwFlags member must be set to zero.

A stream buffer cannot be larger than 64K.

$midiStream->UnprepareHeader($lpMidiInHdr)

Cleans up the preparation of a MIDI output data block.

$midiStream->Out($midiOutHdr)

Plays or queues a stream (buffer) of MIDI data to a MIDI output device.

$midiStream->Pause(void)

Pauses playback of a specified MIDI stream.

$midiStream->Restart(void)

Restarts a paused MIDI stream.

$midiStream->Stop(void)

Turns off all notes on all MIDI channels for the specified MIDI output device.

$midiStream->GetErrorText([$mmsyserr])

Retrieves textual descriptions for the error codes given. If the error code is omitted, the error code for the MIDI function called recently is used.

$midiStream->Position($lpmmtime)

Retrieves the current position in a MIDI stream.

$midiStream->Property($lppropdata, $dwProperty)

Sets or retrieves properties of a MIDI data stream associated with a MIDI output device.

EXPORT

None by default. The following constant values can be exported.

CALLBACK_EVENT CALLBACK_FUNCTION CALLBACK_NULL CALLBACK_TASK
CALLBACK_THREAD CALLBACK_TYPEMASK CALLBACK_WINDOW

MEVT_COMMENT MEVT_EVENTPARM MEVT_EVENTTYPE MEVT_F_CALLBACK MEVT_F_LONG
MEVT_F_SHORT MEVT_LONGMSG MEVT_NOP MEVT_SHORTMSG MEVT_TEMPO MEVT_VERSION

MIDICAPS_CACHE MIDICAPS_LRVOLUME MIDICAPS_STREAM MIDICAPS_VOLUME

MIDIMAPPER MIDIPATCHSIZE MIDIPROP_GET MIDIPROP_SET MIDIPROP_TEMPO
MIDIPROP_TIMEDIV MIDISTRM_ERROR MIDI_CACHE_ALL MIDI_CACHE_BESTFIT
MIDI_CACHE_QUERY MIDI_IO_STATUS MIDI_MAPPER MIDI_UNCACHE

MIXERLINE_TARGETTYPE_MIDIIN MIXERLINE_TARGETTYPE_MIDIOUT
MIXER_OBJECTF_HMIDIIN MIXER_OBJECTF_HMIDIOUT
MIXER_OBJECTF_MIDIIN MIXER_OBJECTF_MIDIOUT

MIDIERR_BADOPENMODE MIDIERR_BASE MIDIERR_DONT_CONTINUE
MIDIERR_INVALIDSETUP MIDIERR_LASTERROR MIDIERR_NODEVICE MIDIERR_NOMAP
MIDIERR_NOTREADY MIDIERR_STILLPLAYING MIDIERR_UNPREPARED

MMSYSERR_ALLOCATED MMSYSERR_BADDB MMSYSERR_BADDEVICEID
MMSYSERR_BADERRNUM MMSYSERR_BASE MMSYSERR_DELETEERROR MMSYSERR_ERROR
MMSYSERR_HANDLEBUSY MMSYSERR_INVALFLAG MMSYSERR_INVALHANDLE
MMSYSERR_INVALIDALIAS MMSYSERR_INVALPARAM MMSYSERR_KEYNOTFOUND
MMSYSERR_LASTERROR MMSYSERR_NODRIVER MMSYSERR_NODRIVERCB
MMSYSERR_NOERROR MMSYSERR_NOMEM MMSYSERR_NOTENABLED
MMSYSERR_NOTSUPPORTED MMSYSERR_READERROR MMSYSERR_VALNOTFOUND
MMSYSERR_WRITEERROR

MM_MIM_CLOSE MM_MIM_DATA MM_MIM_ERROR MM_MIM_LONGDATA
MM_MIM_LONGERROR MM_MIM_MOREDATA MM_MIM_OPEN

MIM_CLOSE MIM_DATA MIM_ERROR MIM_LONGDATA
MIM_LONGERROR MIM_MOREDATA MIM_OPEN

MM_MOM_CLOSE MM_MOM_DONE MM_MOM_OPEN MM_MOM_POSITIONCB

MOM_CLOSE MOM_DONE MOM_OPEN MOM_POSITIONCB

TIME_CALLBACK_EVENT_PULSE TIME_CALLBACK_EVENT_SET
TIME_CALLBACK_FUNCTION TIME_MIDI

MOD_MIDIPORT MCIERR_SEQ_NOMIDIPRESENT MCI_SEQ_MIDI

EXAMPLE

The files under t/ and eg/ directory are actual working examples.

  use Win32API::MIDI qw( /^(MIM_)/ );
  $midi = new Win32API::MIDI;

  # MIDI::Out::ShortMsg
  $mo = new Win32API::MIDI::Out		or die $midi->OutGetErrorText();
  $mo->ShortMsg(0x00403C90)		or die $mo->GetErrorText();
  sleep(1);
  $mo->ShortMsg(0x00003C90)		or die $mo->GetErrorText();
  $mo->Close				or die $mo->GetErrorText();

  # MIDI::Out::LongMsg
  $mo = new Win32API::MIDI::Out		or die $midi->OutGetErrorText();
  # sysEx: Set Master Volume
  $m = "\xf0\x7f\x7f\x04\x01\x7f\x7f\xf7";
  $midiHdr = pack ("PL4PL6",
  		   $m,	# lpData
  		   length $m, # dwBufferLength
  		   0, 0, 0, undef, 0, 0);
  $mo->PrepareHeader(unpack('L!', pack('P',$midiHdr)))
			 		or die $mo->GetErrorText();
  $mo->LongMsg($lpMidiOutHdr)		or die $mo->GetErrorText();
  $mo->UnprepareHeader($lpMidiOutHdr)	or die $mo->GetErrorText();
  $mo->Close				or die $mo->GetErrorText();

  # MIDI::Stream
  $ms = new Win32API::MIDI::Stream()	or die $midi->OutGetErrorText();
  $buf = pack('L*',
	      # System Exclusive (Set Master Volume Full)
	      0,  0, (&MEVT_LONGMSG << 24) | 8, 0x047F7FF0, 0xF77F7F01,
	      # Short Messages
	      0,  0, 0x007F3C90,
	      48, 0, 0x00003C90);
  $midihdr = pack("PLLLLPLL",
		  $buf,	# lpData
		  length $buf,	# dwBufferLength
		  length $buf,	# dwBytesRecorded
		  0,		# dwUser
		  0,		# dwFlags
		  undef,	# lpNext
		  0,		# reserved
		  0);		# dwOffset
  $lpMidiHdr = unpack('L!', pack('P', $midihdr));
  $ms->PrepareHeader($lpMidiHdr)	or die $ms->GetErrorText();
  $ms->Out($lpMidiHdr)			or die $ms->GetErrorText();
  $ms->Restart()			or die $ms->GetErrorText();
  sleep(1);
  $ms->UnprepareHeader($lpMidiHdr)	or die $ms->GetErrorText();
  $ms->Close()				or die $ms->GetErrorText();

  # MIDI::In
  $mi = new Win32API::MIDI::In(0, \&midiincallback, 0x1234)
					or die $midi->InGetErrorText();
  sub midiincallback {
    my ($self, $msg, $instance, $param1, $param2) = @_;
    if ($msg == MIM_OPEN) {
  	  print "MIM_OPEN\n";
  	  ...
    } elsif ($msg == MIM_LONGDATA) {
  	  print "MIM_LONGDATA\n";
  	  ...
    }
  }
  $buf = "\0" x 1024;
  $midihdr = pack ("PLLLLPLL",
		   $buf,	# lpData
		   length $buf, # dwBufferLength
		   0,		# dwBytesRecorded
		   0xBEEF,	# dwUser
		   0,		# dwFlags
		   undef,	# lpNext
		   0,		# reserved
		   0);		# dwOffset
  $lpMidiInHdr = unpack('L!', pack('P', $midihdr));
  $mi->PrepareHeader($lpMidiInHdr)	or die $mi->GetErrorText();
  $mi->AddBuffer($lpMidiInHdr)		or die $mi->GetErrorText();
  $mi->Start				or die $mi->GetErrorText();
  # do some job here
  $mi->Stop				or die $mi->GetErrorText();
  $mi->Reset				or die $mi->GetErrorText();
  $mi->UnprepareHeader($lpMidiInHdr)	or die $mi->GetErrorText();
  $mi->Close()				or die $ms->GetErrorText();

  sub midiincallback {
      my ($self, $msg, $instance, $param1, $param2) = @_;
      printf "<<<0x%x,0x%x,0x%x,0x%x>>>\n", $msg, $instance, $param1, $param2;
      if ($msg == MIM_OPEN) {
  	  print "MIM_OPEN\n";
      } elsif ($msg == MIM_CLOSE) {
  	  print "MIM_CLOSE\n";
      } elsif ($msg == MIM_ERROR) {
  	  print "MIM_ERROR\n";
      } elsif ($msg == MIM_DATA) {
  	  print "MIM_DATA\n";
      } elsif ($msg == MIM_LONGDATA) {
  	  print "MIM_LONGDATA\n";
  	  my $midiHdr = unpack('P32', pack('L!', $param1));
  	  my @d = unpack('LL4LL2', $midiHdr);
  	  printf "lpData:%x,Buflen:%x,bytesrecorded:%d,dwUser:%x,dwFlags:%d\n",
  	      @d[0..4];
  	  datadump(unpack("P$d[2]", $midiHdr));
      } elsif ($msg == MIM_LONGERROR) {
  	  print "MIM_LONGERROR\n";
      } else {
  	  print "unknown message type\n";
      }
  }

AUTHOR

Hiroo Hayashi, <hiroo.hayashi@computer.org>

TODO

More test.

BUGS

If you find bugs, report to the author. Thank you.

To install Win32API::MIDI, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Win32API::MIDI

CPAN shell

perl -MCPAN -e shell
install Win32API::MIDI

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Overview

Querying MIDI Devices

Recording MIDI Audio

Opening and Closing MIDI Input Device

Managing MIDI Recording

Playing MIDI

Opening and Closing MIDI Output Device

Sending Individual MIDI Messages

Misc.

Sending MIDI Messages with Stream Buffers

EXPORT

EXAMPLE

AUTHOR

SEE ALSO

TODO

BUGS

Module Install Instructions