Provided by: libmidi-perl_0.83-1_all bug

NAME

       MIDI::Opus -- functions and methods for MIDI opuses

SYNOPSIS

        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;

DESCRIPTION

       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.

CONSTRUCTOR AND METHODS

       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::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.)

       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->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.

WHERE'S THE DESTRUCTOR?

       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.

NOTE ON TICKS

       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.

NOTE ON WARN-ING AND DIE-ING

       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

       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.

AUTHORS

       Sean M. Burke "sburke@cpan.org" (until 2010)

       Darrell Conklin "conklin@cpan.org" (from 2010)