/ 
Win32API-MIDI-0.05
River stage zero No dependents
/ Win32API::MIDI::SysEX

NAME

Win32API::MIDI::SysEX - Perl Module for MIDI System Exclusive Message.

SYNOPSIS

use Win32API::MIDI::SysEX;
$se = new Win32API::MIDI::SysEX;
$d = $se->turnGeneralMIDISystemOff;
$d = $se->turnGeneralMIDISystemOn;
$d = $se->masterVolume(0xD20);

DESCRIPTION

Overview

This module is still under development and most of function are not debugged yet. And the this module may have to be renamed as MIDI::SysEX in the future, since this module is dependent with Microsoft Windows.

Manufacturer's ID Number

MIDI manufacturer's ID is distributed as follows.

	       not used  American  European  Japanese  Other     Special
1 byte ID: 00        01 -- 1F  20 -- 3F  40 -- 5F  60 -- 7C  7D -- 7F
3 byte ID: 00 00 00  00 00 01  00 20 00  00 40 00  00 60 00
			 00 1F 7F  00 3F 7F  00 5F 7F  00 7F 7F

7D: non-commercial use (e.g. schools, research, etc.)
7E: Non-Real Time Universal System Exclusive ID
7F: Real Time Universal System Exclusive ID (all call device ID)

Standard MIDI System Exclusive Messages use LSB first (a kind of little endian) notation. By following this rule, a 3 byte ID "xxh yyh zzh" in MIDI specification is expressed as 0xzzyyxx in this module. By using this notation we can distinguish "01h" (Sequential: 0x01) from "00h 00h 01h" (Time Warner Interactive: 0x010000).

The following methods are provided.

manufacturer(ID)

Returns the manufacturer name for manufacturer's ID.

manufacturersID(name)

Returns the manufacturer ID whose manufacturer's name equals with name. Returns undef when no matches.

Device ID

The value for device ID option (argument) should be a number from 1 to 16 (not 0 to 15).

Create an Object

new Win32API::MIDI::SysEX([param => value,]...)
deviceID [devID]:
	Device ID.  If device_ID is omitted, BRD+1 broadcast,
	all call, 127+1) is used.  The device ID is used on
	every method calls.  You can create any numbers of
	object with different device ID.

manufacturersID [mID]:
	manufacturers ID.  If omitted, 0x7d (Non-commercail
	use) is used.

manufacturerName [mName]:
	manufacturers name. It must be one of key of
	%Win32API::MIDI::mID

modelID [mdlID]:
	MIDI device model ID

modelName [mdlName]:
	MIDI device model name.

Sample Dump Standard

Generic Handshaking Messages

sampleDumpACK(pp_1B)
sampleDumpNAK(pp_1B)
sampleDumpCANCEL(pp_1B)
sampleDumpWAIT(pp_1B)
sampleDumpEOF(pp_1B)
pp_1B:packet number (1 byte)

Dump Header

sampleDumpHeader(sample_number_2B, sample_format, sample_period_3B, sample_length_3B, sustain_loop_start_point_word_number_3B, sustain_loop_end_point_word_number_3B, loop_type)
sample_format: # of significant bits from 8-28
sample_period_3B: 1/sample_rate in nanosecond
loop_type: 00=forward only, 01=backward/forward, 7f=loop off

Dump Request

sampleDumpRequest(requested_sample_2B)

Data Packet (for Sample Data)

sampleDataPacket(running_packet_count_1B, data)
running_packet_count_1B: 0-127
data: 120 bytes of data

Sample Dump Extensions

sampleDumpLoopPointTransmission(sample_number_2B, loop_number_2B, loop_type, loop_start_address_3B, loop_end_address_3B);
  loop_type:
	00 = Forwards Only (unidirectional)
	01 = Backwards/Forwards (bi-directional)
	7F = Off
sampleDumpLoopPointRequest(sample_number_2B, loop_number_2B)

Device Inquiry

identityRequest(void)
identityReply(manufacturer's_ID, device_family_code_2B, device_family_member_code_2B, software_revision_level_4B)
manufacturer's_ID : 1 or 3 byte ID
parseIdentityReply(identity_reply_data)

parseIdentityReply() returns list of;

device ID (1 byte)
manufactures ID (1 byte or 3 byte)
device family code (2 byte)
device family member code (2 byte)
software revision level (4 byte)

Or returns NULL list if data format of identity_reply_data is illegal.

File Dump

Request

fileDumpRequest(receiver_ID_1B, type [,file_name])
  type:
	"MIDI" : MIDI File
	"MIEX" : MIDIEX File
	"ESEQ" : ESQ File
	"TEXT" : 7-bit ASCII Text File
	"BIN " : binary file
	"MAC " : Macintosh file (with MacBinary header)

Returns undef if type or file_name is illegal value.

fileDumpHeader(sender_ID, type, length [,file_name])
type: see fileDumpRequest().

Data Packet (for File Dump)

fileDumpDataPacket(pp_1B, data)

Maximum data length is 112 byte.

Handshaking Flags

fileDumpNAK(pp_1B)
fileDumpACK(pp_1B)
fileDumpWAIT(pp_1B)
fileDumpCANCEL(pp_1B)
fileDumpEOF(pp_1B)
pp_1B:packet number (1 byte)

MIDI Tuning

Bulk Tuning Dump Request

bulkTuningDumpRequest(pn_1B)
pn: tuning program number (0-127)

Bulk Tuning Dump

bulkTuningDump(pn_1B, tuning_name, data)
pn: tuning program number (0-127)
tuning_name: 16 ASCII characters
data: 3 x 128 bytes frequency data

Single Note Tuning Change (Real-Time)

singleNoteTuningChange(pn_1B, nc_1B, data)
pn: tuning program number (0-127)
nc: number of changes
data: 4 x nc bytes data

General MIDI System Messages

Turn General MIDI System On

GM1SystemOn(void)
GM2SystemOn(void)

Turn General MIDI System Off

GMSystemOff(void)

Notation Information

Bar Maker

notationInfoBarMarker(bar_number_2B)
    bar_number:
	0x2000			not running
	0x2001 - 0x0000		count-in
	0x0001 - 0x1FFE		bar number in song
	0x1FFF			running: bar number unknown

Time Signature

notationInfoTimeSignatureImmediate(nb0_1B, bd0_1B, nc_1B, nn_1B [,nb1_1B, bd1_1B]...)
notationInfoTimeSignatureDelayed(nb0_1B, bd0_1B, nc_1B, nn_1B [,nb1_1B, bd1_1B]...)
nbn : number of beats (numerator) of time signature
bdn : beat value (denominator) of time signature (negative power of 2)
nc  : number of MIDI clocks in a metronome click
nn  : number of notated 32nd notes in a MIDI quarter note

Example
  3/4       : nb0 = 3, bd0 = 2
  4/4 + 3/8 : nb0 = 4, bd0 = 2, nb1 = 3, bd1 = 3

Device Control

Master Volume and Master Balance

masterVolume(volume_2B)
volume :
  0x0000 = volume off
  0x3FFF = maximum volume
masterBalance(balance_2B)
balance :
  0x0000 = hard left
  0x2000 = center
  0x3fff = hard right
globalParameterReverb(parameter_1B, value_1B) (GM2)
    parameter = 0: Reverb Type
	0: small room
	1: medium room
	2: large room
	3: medium hall
	4: large hall (default)
	5: plate

    parameter = 1: Reverb Time
	0: 44 (1.1s)
	1: 50 (1.3s)
	2: 56 (1.5s)
	3: 64 (1.8s)
	4: 64 (1.8s)
	8: 50 (1.3s)
globalParameterChorus(parameter_1B, value_1B) (GM2)
    parameter = 0: Chorus Type
	0: Chorus 1
	1: Chorus 2
	2: Chorus 3
	3: Chorus 4
	4: FB Chorus
	5: Flanger

    parameter = 1: Modulation Rate
	MR = value * 0.122 (MR: modulation frequency in Hz)

    parameter = 2: Modulation Depth
	MD = (value+1) / 3.2 (MD: peak-to-peak swing of modulation in ms)

    parameter = 3: Feedback
	FB = value * 0.763 (FB: amount of feedback from Chorus output in percent)

    parameter = 4: Send to Reverb
	CTR = value * 0.787 (CTR: send level from Chorus to Reverb in percent)
channelPressure(channel_1B, pp_1B, rr_1B [,pp_1B, rr_1B]...) (GM2)

Controller Destination Setting, Channel Pressure (Aftertouch)

pp				rr		description
00 Pitch Control		0x28-0x58	-24 - +24 semitones
01 Filter Cutoff Control	0x00-0x7f	-9600 - +9450 cents
02 Amplitude Control		0x00-0x7f	0 - (127/64)*10 percent
03 LFO Pitch Depth		0x00-0x7f	0 - 600 cents
04 LFO Filter Depth		0x00-0x7f	0 - 2400 cents
05 LFO Amplitude Depth	0x00-0x7f	0 - 100 percent
controlChange(channel_1B, cc_1B, pp_1B, rr_1B [,pp_1B, rr_1B]...) (GM2)

Controller Destination Setting, Controller (Control Change)

cc : controller number 0x01 - 0x1f, 0x40 - 0x5f

pp				rr		description
00 Pitch Control		0x28-0x58	-24 - +24 semitones
01 Filter Cutoff Control	0x00-0x7f	-9600 - +9450 cents
02 Amplitude Control		0x00-0x7f	0 - (127/64)*10 percent
03 LFO Pitch Depth		0x00-0x7f	0 - 600 cents
04 LFO Filter Depth		0x00-0x7f	0 - 2400 cents
05 LFO Amplitude Depth	0x00-0x7f	0 - 100 percent

EXPORT

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

System Exclusive Message
SOX = 0xf0	# Start of System Exclusive Status
System Common Messages
MQF = 0xf1	# MTC (MIDI Time Code) Quarter Frame
SPP = 0xf2	# Song Position Pointer
SSL = 0xf3	# Song Select
TRQ = 0xf6	# Tune Request
EOX = 0xf7	# EOX: End Of System Exclusive
System Real Time Messages
CLK = 0xf8	# Timing Clock
STT = 0xfa	# Start
CNT = 0xfb	# Continue
STP = 0xfc	# Stop
ASN = 0xfe	# Active Sensing
RST = 0xff	# System Reset
Special Manufacturer's IDs
UNM = 0x7e	# Universal Non-realtime Messages
URM = 0x7f	# Universal Realtime Messages
Special Device ID
BRD = 0x7f	# Broadcast Device ID (all call)

AUTHOR

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

SEE ALSO

Win32API::MIDI
Win32API::MIDI::SysEX::Roland.pm, Win32API::MIDI::SysEX::Yamaha.pm, etc

TODO

Add more Subclasses other than Roland or Yamaha. Contributions are welcome.
More test and debug.
Implement MTC (MIDI Time Control), MSC (MIDI Show Control), and MMC (MIDI Machine Control) functions.

BUGS

If you find bugs, report to the author.