Hiroo HAYASHI > Win32API-MIDI-0.05 > Win32API::MIDI::SysEX

Download:
Win32API-MIDI-0.05.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Source  

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.

Header

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.

syntax highlighting: