MIDI::Opus provides...
the constructor MIDI::Opus->new({ ...options... })
This returns a new opus object. The options, which are optional, is an anonymous hash. By default,
you get a new format-0 opus with no tracks and a tick parameter of 96. There are six recognized
options: "format", to set the MIDI format number (generally either 0 or 1) of the new object;
"ticks", to set its ticks parameter; "tracks", which sets the tracks of the new opus to the contents
of the list-reference provided; "tracks_r", which is an exact synonym of "tracks"; "from_file", which
reads the opus from the given filespec; and "from_handle", which reads the opus from the the given
filehandle reference (e.g., *STDIN{IO}), after having called binmode() on that handle, if that's a
problem.
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::Event, 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.)
the method $new_opus = $opus->copy
This duplicates the contents of the given opus, and returns the duplicate. If you are unclear on why
you may need this function, read the documentation for the "copy" method in MIDI::Track.
the method $opus->tracks( @tracks )
Returns the list of tracks in the opus, possibly after having set it to @tracks, if specified and not
empty. (If you happen to want to set the list of tracks to an empty list, for whatever reason, you
have to use "$opus->tracks_r([])".)
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.
the method $opus->tracks_r( $tracks_r )
Returns a reference to the list of tracks in the opus, possibly after having set it to $tracks_r, if
specified. "$tracks_r" can actually be any listref, whether it comes from a scalar as in
$some_tracks_r, or from something like "[@tracks]", or just plain old "\@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.
the method $opus->ticks( $tick_parameter )
Returns the tick parameter from $opus, after having set it to $tick_parameter, if provided.
the method $opus->format( $format )
Returns the MIDI format for $opus, after having set it to $format, if provided.
the method $new_opus = $opus->skyline
This skylines an $opus. It first converts the score to format 0 with the skyline result as the
track. See the documentation for Score::skyline() and Track::skyline(). Original $opus is modified,
use MIDI::Opus::copy if you want to take a copy first. Appearance order of concurrent events may not
be preserved.
the method $new_opus = $opus->format0
This converts $opus to format 0 by collapsing all tracks into one. Original $opus is modified, use
MIDI::Opus::copy if you want to take a copy first.
the method $new_opus = $opus->quantize
This grid quantizes an opus. It simply calls MIDI::Score::quantize on every track. See docs for
MIDI::Score::quantize. Original opus is destroyed, use MIDI::Opus::copy if you want to take a copy
first.
the method $opus->dump( { ...options...} )
Dumps the opus object as a bunch of text, for your perusal. Options include: "flat", if true, will
have each event in the opus as a tab-delimited line -- or as delimited with whatever you specify with
option "delimiter"; otherwise, dump the data as Perl code that, if run, would/should reproduce the
opus. For concision's sake, the track data isn't dumped, unless you specify the option "dump_tracks"
as true.
the method $opus->write_to_file('filespec', { ...options...} )
Writes $opus as a MIDI file named by the given filespec. The options hash is optional, and whatever
you specify as options percolates down to the calls to MIDI::Event::encode -- which see. Currently
this just opens the file, calls $opus->write_to_handle on the resulting filehandle, and closes the
file.
the method $opus->write_to_handle(IOREF, { ...options...} )
Writes $opus as a MIDI file to the IO handle you pass a reference to (example: *STDOUT{IO}). The
options hash is optional, and whatever you specify as options percolates down to the calls to
MIDI::Event::encode -- which see. Note that this is probably not what you'd want for sending music
to "/dev/sequencer", since MIDI files are not MIDI-on-the-wire.
the method $opus->draw({ ...options...})
This currently experimental method returns a new GD image object that's a graphic representation of
the notes in the given opus. Options include: "width" -- the width of the image in pixels (defaults
to 600); "bgcolor" -- a six-digit hex RGB representation of the background color for the image
(defaults to $MIDI::Opus::BG_color, currently '000000'); "channel_colors" -- a reference to a list of
colors (in six-digit hex RGB) to use for representing notes on given channels. Defaults to
@MIDI::Opus::Channel_colors. This list is a list of pairs of colors, such that: the first of a pair
(color N*2) is the color for the first pixel in a note on channel N; and the second (color N*2 + 1)
is the color for the remaining pixels of that note. If you specify only enough colors for channels 0
to M, notes on a channels above M will use 'recycled' colors -- they will be plotted with the color
for channel "channel_number % M" (where "%" = the MOD operator).
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.
Install Now
PNG Icons