|
MIDI::Event - MIDI events |
MIDI::Event - MIDI events
# Dump a MIDI file's text events
die "No filename" unless @ARGV;
use MIDI; # which "use"s MIDI::Event;
MIDI::Opus->new( {
"from_file" => $ARGV[0],
"exclusive_event_callback" => sub{print "$_[2]\n"},
"include" => \@MIDI::Event::Text_events
} ); # These options percolate down to MIDI::Event::decode
exit;
Functions and lists to do with MIDI events and MIDI event structures.
An event is a list, like:
( 'note_on', 141, 4, 50, 64 )
where the first element is the event name, the second is the delta-time, and the remainder are further parameters, per the event-format specifications below.
An event structure is a list of references to such events -- a ``LoL''. If you don't know how to deal with LoLs, you must read the perllol manpage.
For your use in code (as in the code in the Synopsis), this module provides a few lists:
This module provides three functions of interest, which all act upon event structures. As an end user, you probably don't need to use any of these directly, but note that options you specify for MIDI::Opus->new with a from_file or from_handle options will percolate down to these functions; so you should understand the options for the first two of the below functions. (The casual user should merely skim this section.)
'end_track', in ``EVENTS'', below.
\&wanted or as
sub { BLOCK }) is called on every event after it's been parsed into
an event list (and any EOT magic performed), but before it's added to
the event structure. So if you want to alter the event stream on the
way to the event structure (which counts as deep voodoo), define
'event_callback' and have it modify its @_.
decode() at the end will always be
empty.) Good for cases like the text dumper in the Synopsis, above.
If no 'unknown_callback' is specified, encode() will warn (well,
carp) of the unknown event. To merely block that, just set
'unknown_callback' to sub{return('')}
encode() never ever adds an end-track (EOT) event to the
encoded data generated unless it's explicitly there as an
'end_track' in the given event structure. You probably don't ever
need this unless you're encoding for straight writing to a MIDI
port, instead of to a file.
Note: If you're encoding just a single event at a time or less than a whole trackful in any case, then you probably want something like:
$data_r = MIDI::Event::encode(
[
[ 'note_on', 141, 4, 50, 64 ]
],
{ 'never_add_eot' => 1} );
which just encodes that one event as an event structure of one event -- i.e., an LoL that's just a list of one list.
But note that running status will not always apply when you're encoding less than a whole trackful at a time, since running status works only within a LoL encoded all at once. This'll result in non-optimally compressed, but still effective, encoding.
$track2 = $track->copy
instead. But it's here if you happen to need it.
Events use these data types:
For data types not defined above, (e.g., sf and mi for
'key_signature'), consult the MIDI::Filespec manpage and/or the source for
MIDI::Event.pm. And if you don't see it documented, it's probably
because I don't understand it, so you'll have to consult a real MIDI
reference.
And these are the events:
Three of the above events are represented a bit oddly from the point of view of the file spec:
The parameter pitch_wheel for 'pitch_wheel_change' is a value
-8192 to 8191, although the actual encoding of this is as a value 0 to
16,383, as per the spec.
Sysex events are represented as either 'sysex_f0' or 'sysex_f7',
depending on the status byte they are encoded with.
'end_track' is a bit stranger, in that it is almost never actually
found, or needed. When the MIDI decoder sees an EOT (i.e., an
end-track status: FF 2F 00) with a delta time of 0, it is ignored!
If in the unlikely event that it has a nonzero delta-time, it's
decoded as a 'text_event' with whatever that delta-time is, and a
zero-length text parameter. (This happens before the
'event_callback' or 'exclusive_event_callback' callbacks are
given a crack at it.) On the encoding side, an EOT is added to the
end of the track as a normal part of the encapsulation of track data.
I chose to add this special behavior so that you could add events to
the end of a track without having to work around any track-final
'end_track' event.
However, if you set no_eot_magic as a decoding parameter, none of
this magic happens on the decoding side -- 'end_track' is decoded
just as it is.
And if you set no_eot_magic as an encoding parameter, then a
track-final 0-length 'text_event' with non-0 delta-times is left as
is. Normally, such an event would be converted from a 'text_event'
to an 'end_track' event with thath delta-time.
Normally, no user needs to use the no_eot_magic option either in
encoding or decoding. But it is provided in case you need your event
LoL to be an absolutely literal representation of the binary data,
and/or vice versa.
For your reference (if you can make any sense of it), here is a copy of the MIDI BNF, as I found it in a text file that's been floating around the Net since the late 1980s.
Note that this seems to describe MIDI events as they can occur in MIDI-on-the-wire. I think that realtime data insertion (i.e., the ability to have <realtime byte>s popping up in the middle of messages) is something that can't happen in MIDI files.
In fact, this library, as written, can't correctly parse MIDI data
that has such realtime bytes inserted in messages. Nor does it
support representing such insertion in a MIDI event structure that's
encodable for writing to a file. (Although you could theoretically
represent events with embedded <realtime byte>s as just
raw_data events; but then, you can always stow anything
at all in a raw_data event.)
1. <MIDI Stream> ::= <MIDI msg> < MIDI Stream>
2. <MIDI msg> ::= <sys msg> | <chan msg>
3. <chan msg> ::= <chan 1byte msg> |
| <chan 2byte msg>
4. <chan 1byte msg> ::= <chan stat1 byte> <data singlet>
<running singlets>
5. <chan 2byte msg> ::= <chan stat2 byte> <data pair>
<running pairs>
6. <chan stat1 byte> ::= <chan voice stat1 nibble>
<hex nibble>
7. <chan stat2 byte> ::= <chan voice stat2 nibble>
<hex nibble>
8. <chan voice stat1 nyble>::= C | D
9. <chan voice stat2 nyble>::= 8 | 9 | A | B | E
10. <hex nyble> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| 8 | 9 | A | B | C | D | E | F
11. <data pair> ::= <data singlet> <data singlet>
12. <data singlet> ::= <realtime byte> <data singlet> |
| <data byte>
13. <running pairs> ::= <empty> | <data pair> <running pairs>
14. <running singlets> ::= <empty> |
| <data singlet> <running singlets>
15. <data byte> ::= <data MSD> <hex nyble>
16. <data MSD> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
17. <realtime byte> ::= F8 | FA | FB | FC | FE | FF
18. <sys msg> ::= <sys common msg> |
| <sysex msg> |
| <sys realtime msg>
19. <sys realtime msg> ::= <realtime byte>
20. <sysex msg> ::= <sysex data byte>
<data singlet> <running singlets>
<eox byte>
21. <sysex stat byte> ::= F0
22. <eox byte> ::= F7
23. <sys common msg> ::= <song position msg> |
| <song select msg> |
| <tune request>
24. <tune request> ::= F6
25. <song position msg> ::= <song position stat byte>
<data pair>
26. <song select msg> ::= <song select stat byte>
<data singlet>
27. <song position stat byte>::=F2
28. <song select stat byte> ::= F3
Copyright (c) 1998-2005 Sean M. Burke. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Sean M. Burke sburke@cpan.org (Except the BNF --
who knows who's behind that.)
|
MIDI::Event - MIDI events |