/ 
Test2-Tools-MIDI-0.01
/ Test2::Tools::MIDI

NAME

Test2::Tools::MIDI - test MIDI file contents

SYNOPSIS

use Test2::Tools::MIDI;

open my $fh, '<', 'foo.midi' or die "open 'foo.midi': $!\n";
binmode $fh;

midi_header( $fh, 1, 3, 96 ); # format 1, 3 tracks, 96 tick
...

DESCRIPTION

This module offers functions that test whether MIDI files (or an in-memory string) contain particular MIDI structures and events.

FUNCTIONS

The various midi_* functions are exported by default; the other utility functions are not.

midi_header file-handle format ntracks division

Test for a MIDI header which among other things will have a particular format (0 for a single track, 1 for multiple tracks, or possibly other values), some number of tracks ntracks, and a particular division (usually a positive number of ticks such as 96).

A MIDI header is generally followed by some number of tracks (that ideally should agree with ntracks), each of which containing some number of events.

Check that there is a MIDI footer event with the given dtime (usually 0) in the file-handle. (The MIDI::Opus module hides the footer in dumps though does parse it.)

midi_note_off file-handle dtime channel pitch velocity

Check that there is a MIDI note_off event with the given details in the file-handle. See the MIDI::Event module for more documentation on the fields.

midi_note_on file-handle dtime channel pitch velocity

Check that there is a MIDI note_on event with the given details in the file-handle.

midi_skip file-handle size

Skips over size bytes in the file-handle. Good for any pesky MIDI events that are not (yet?) supported by this module.

midi_track file-handle length event-callback

Test that a MIDI track is of a certain length in bytes. Calls the event-callback to handle any MIDI events in the track; there should be length bytes of events and the file-handle will have been advanced to the first of them.

midi_track( $fh, 64, 0,
    sub ( $fh, $length ) {
        # test MIDI events including the track footer here ...
    }
);
read_vlq file-handle

Reads a variable length quantity (VLQ) from the file-handle, or failing that throws an error. VLQ are used for MIDI durations (dtime). The w template to the pack or unpack functions is a more efficient way to convert such quantities, though does not work on a file handle.

BUGS

None known. However, the module is very incomplete.

SEE ALSO

MIDI::Event, Test2::Suite

COPYRIGHT AND LICENSE

Copyright 2024 Jeremy Mates

This program is distributed under the (Revised) BSD License: https://opensource.org/licenses/BSD-3-Clause