The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
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.