| MIDI::Opus(3pm) | User Contributed Perl Documentation | MIDI::Opus(3pm) |
MIDI::Opus -- functions and methods for MIDI opuses
use MIDI; # uses MIDI::Opus et al
foreach $one (@ARGV) {
my $opus = MIDI::Opus->new({ 'from_file' => $one, 'no_parse' => 1 });
print "$one has ", scalar( $opus->tracks ) " tracks\n";
}
exit;
MIDI::Opus provides a constructor and methods for objects representing a MIDI opus (AKA "song"). It is part of the MIDI suite.
An opus object has three attributes: a format (0 for MIDI Format 0), a tick parameter (parameter "division" in MIDI::Filespec), and a list of tracks objects that are the real content of that opus.
Be aware that options specified for the encoding or decoding of an opus may not be documented in this module's documentation, as they may be (and, in fact, generally are) options just passed down to the decoder/encoder in MIDI::Event -- so see MIDI::Event for an explanation of most of them, actually.
MIDI::Opus provides...
If you specify either "from_file" or "from_handle", you probably don't want to specify any of the other options -- altho you may well want to specify options that'll get passed down to the decoder in MIDI::Events, such as 'include' => ['sysex_f0', 'sysex_f7'], just for example.
Finally, the option "no_parse" can be used in conjunction with either "from_file" or "from_handle", and, if true, will block MTrk tracks' data from being parsed into MIDI events, and will leave them as track data (i.e., what you get from $track->data). This is useful if you are just moving tracks around across files (or just counting them in files, as in the code in the Synopsis, above), without having to deal with any of the events in them. (Actually, this option is implemented in code in MIDI::Track, but in a routine there that I've left undocumented, as you should access it only thru here.)
In other words: $opus->tracks(@tracks) is how to set the list of tracks (assuming @tracks is not empty), and @tracks = $opus->tracks is how to read the list of tracks.
Originally $opus->tracks was the only way to deal with tracks, but I added $opus->tracks_r to make possible 1) setting the list of tracks to (), for whatever that's worth, 2) parallel structure between MIDI::Opus::tracks[_r] and MIDI::Tracks::events[_r] and 3) so you can directly manipulate the opus's tracks, without having to copy the list of tracks back and forth. This way, you can say:
$tracks_r = $opus->tracks_r();
@some_stuff = splice(@$tracks_r, 4, 6);
But if you don't know how to deal with listrefs like that, that's OK, just use $opus->tracks.
This means that if you specify
channel_colors => ['00ffff','0000ff']
then all the channels' notes will be plotted with an aqua pixel followed by blue ones; and if you specify
channel_colors => ['00ffff','0000ff', 'ff00ff','ff0000']
then all the even channels' notes will be plotted with an aqua pixel followed by blue ones, and all the odd channels' notes will be plotted with a purple pixel followed by red ones.
As to what to do with the object you get back, you probably want something like:
$im = $chachacha->draw;
open(OUT, ">$gif_out"); binmode(OUT);
print OUT $im->gif;
close(OUT);
Using this method will cause a "die" if it can't successfully "use GD".
I emphasise that "draw" is expermental, and, in any case, is only meant to be a crude hack. Notably, it does not address well some basic problems: neither volume nor patch-selection (nor any notable aspects of the patch selected) are represented; pitch-wheel changes are not represented; percussion (whether on percussive patches or on channel 10) is not specially represented, as it probably should be; notes overlapping are not represented at all well.
Because MIDI objects (whether opuses or tracks) do not contain any circular data structures, you don't need to explicitly destroy them in order to deallocate their memory. Consider this code snippet:
use MIDI;
foreach $one (@ARGV) {
my $opus = MIDI::Opus->new({ 'from_file' => $one, 'no_parse' => 1 });
print "$one has ", scalar( $opus->tracks ) " tracks\n";
}
At the end of each iteration of the foreach loop, the variable $opus goes away, along with its contents, a reference to the opus object. Since no other references to it exist (i.e., you didn't do anything like push(@All_opuses,$opus) where @All_opuses is a global), the object is automagically destroyed and its memory marked for recovery.
If you wanted to explicitly free up the memory used by a given opus object (and its tracks, if those tracks aren't used anywhere else) without having to wait for it to pass out of scope, just replace it with a new empty object:
$opus = MIDI::Opus->new;
or replace it with anything at all -- or even just undef it:
undef $opus;
Of course, in the latter case, you can't then use $opus as an opus object anymore, since it isn't one.
If you want to use "negative" values for ticks (so says the spec: "If division is negative, it represents the division of a second represented by the delta-times in the file,[...]"), then it's up to you to figure out how to represent that whole ball of wax so that when it gets "pack()"'d as an "n", it comes out right. I think it'll involve something like:
$opus->ticks( (unpack('C', pack('c', -25)) << 8) & 80 );
for bit resolution (80) at 25 f/s.
But I've never tested this. Let me know if you get it working right, OK? If anyone does get it working right, and tells me how, I'll try to support it natively.
In the case of trying to parse a malformed MIDI file (which is not a common thing, in my experience), this module (or MIDI::Track or MIDI::Event) may warn() or die() (Actually, carp() or croak(), but it's all the same in the end). For this reason, you shouldn't use this suite in a case where the script, well, can't warn or die -- such as, for example, in a CGI that scans for text events in a uploaded MIDI file that may or may not be well-formed. If this is the kind of task you or someone you know may want to do, let me know and I'll consider some kind of 'no_die' parameter in future releases. (Or just trap the die in an eval { } around your call to anything you think you could die.)
Copyright (c) 1998-2002 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" (until 2010)
Darrell Conklin "conklin@cpan.org" (from 2010)
| 2022-10-13 | perl v5.34.0 |