MIDI::Track(3pm)

💖 MIDI::Track — bestie's guide to MIDI tracks 💖

okay so real talk, this is MIDI::Track, a page from the User Contributed Perl Documentation, and it's literally just functions and methods for MIDI tracks. that's the whole vibe. let's get into it 🎀

---

✨ SYNOPSIS ✨

 use MIDI; # ...which "use"s MIDI::Track et al
 $taco_track = MIDI::Track->new;
 $taco_track->events(
  ['text_event', 0, "I like tacos!"],
  ['note_on',    0, 4, 50, 96 ],
  ['note_off', 300, 4, 50, 96 ],
 );
 $opus = MIDI::Opus->new(
  {  'format' => 0,  'ticks' => 240,  'tracks' => [ $taco_track ] }
 );
   ...etc...

like… the taco track. she's iconic, she's the moment 🌮✨

---

🌸 DESCRIPTION 🌸

so MIDI::Track hands you a constructor and a bunch of methods for objects that represent a MIDI track. it's part of the MIDI suite, one big happy family 🫶

MIDI tracks have, currently, three attributes: a type, events, and data. almost every track you'll ever deal with is of type MTrk, so like… that's the type by default, no cap. events are what make up an MTrk track. if a track is not of type MTrk, or is an unparsed MTrk, then it has (or better have!) data. 👑

when an MTrk track is encoded, if there's data defined for it, that's what gets encoded (and "encoding data" just means passing it thru untouched, no thoughts head empty). heads up tho: this happens even if the data defined is "" — but it won't happen if the data is undef. however, if there's no data defined for the MTrk track (as is the general case, the normie case), then the track's events are encoded, via a call to MIDI::Event::encode.

(if neither events nor data are defined, it acts as a zero-length track. she's giving minimalism 💅)

if a non-MTrk track is encoded, its data is encoded. if there's no data for it, it acts as a zero-length track.

in other words, let me spell it out bestie:

1. events are meaningful only in an MTrk track
2. you probably don't want both data and events defined
3. 99.999% of the time, just worry about events in MTrk tracks, because that's all you ever want to deal with anyway. periodt. 💖

---

🦋 CONSTRUCTOR AND METHODS 🦋

MIDI::Track provides…

the constructor MIDI::Track->new({ ...options... })

this returns a new track object. by default, the track is of type MTrk, which is probably what you want (it's what everyone wants, fr fr). the options, which are optional, is an anonymous hash. there are four recognized options:

• "data" — sets the data of the new track to the string provided
• "type" — sets the type of the new track to the string provided
• "events" — sets the events of the new track to the contents of the list-reference provided (i.e., a reference to a LoL — see perllol for the skinny on LoLs 👀)
• "events_r" — which is an exact synonym of "events"

the method $new_track = $track->copy

this duplicates the contents of the given track, and returns the duplicate. if you are unclear on why you may need this function, consider:

          $funk  = MIDI::Opus->new({'from_file' => 'funk1.mid'});
          $samba = MIDI::Opus->new({'from_file' => 'samba1.mid'});

          $bass_track = ( $funk->tracks )[-1]; # last track
          push(@{ $samba->tracks_r }, $bass_track );
               # make it the last track

          &funk_it_up(  ( $funk->tracks )[-1]  );
               # modifies the last track of $funk
          &turn_it_out(  ( $samba->tracks )[-1]  );
               # modifies the last track of $samba

          $funk->write_to_file('funk2.mid');
          $samba->write_to_file('samba2.mid');
          exit;

so you have your routines funk_it_up and turn_it_out, and they each modify the track they're applied to in some way. but the problem is that the above code probably does not do what you want — because the last track-object of $funk and the last track-object of $samba are the same object. an object, you may be surprised to learn, can be in different opuses at the same time — which is fine, except in cases like the above code. that's where you need to copy the object. change the above code to read:

          push(@{ $samba->tracks_r }, $bass_track->copy );

and what you want to happen, will. ✨

incidentally, this potential need to copy also occurs with opuses (and in fact any reference-based data structure, altho opuses and tracks should cover almost all cases with MIDI stuff), which is why there's $opus->copy, for copying entire opuses.

(if you happen to need to copy a single event, it's just $new = [@$old] ; and if you happen to need to copy an event structure (LoL) outside of a track for some reason, use MIDI::Event::copy_structure.)

track->skyline({ ...options... })

skylines the entire track. modifies the track. see MIDI::Score for documentation on skyline.

track->skyline({ ...options... })

skylines the entire track. modifies the track. see MIDI::Score for documentation on skyline.

not me noticing this one is listed twice 💀 bestie the manpage said it once and then said it again. i'm keeping both because the rule is every detail stays, and honestly? double skyline. she ate. 👑

the method $track->events( @events )

returns the list of events in the track, possibly after having set it to @events, if specified and not empty. (if you happen to want to set the list of events to an empty list, for whatever reason, you have to use "$track->events_r([])".)

in other words: $track->events(@events) is how to set the list of events (assuming @events is not empty), and @events = $track->events is how to read the list of events. reading and writing, she contains multitudes 🦋

the method $track->events_r( $event_r )

returns a reference to the list of events in the track, possibly after having set it to $events_r, if specified. actually, "$events_r" can be any listref to a LoL, whether it comes from a scalar as in $some_events_r, or from something like [@events], or just plain old \@events.

originally $track->events was the only way to deal with events, but the author added $track->events_r to make possible:

1. setting the list of events to (), for whatever that's worth
2. so you can directly manipulate the track's events, without having to copy the list of events (which might be tens of thousands of elements long) back and forth. like, imagine. 😭

this way, you can say:

          $events_r = $track->events_r();
          @some_stuff = splice(@$events_r, 4, 6);

but if you don't know how to deal with listrefs outside of LoLs, that's OK, just use $track->events. no gatekeeping here 💜

the method $track->type( 'MFoo' )

returns the type of $track, after having set it to 'MFoo', if provided. you probably won't ever need to use this method, other than in a context like:

          if( $track->type eq 'MTrk' ) { # The usual case
            give_up_the_funk($track);
          } # Else just keep on walkin'!

track types must be 4 bytes long; see MIDI::Filespec for details. four bytes. not three, not five. four. 💅

the method $track->data( $kooky_binary_data )

returns the data from $track, after having set it to $kooky_binary_data, if provided — even if it's zero-length! you probably won't ever need to use this method. for your information, $track->data(undef) is how to undefine the data for a track.

the method $track->new_event('event', ...parameters... )

this adds the event ('event', ...parameters...) to the end of the event list for $track. it's just sugar for:

          push( @{$this_track->events_r}, [ 'event', ...params... ] )

if you want anything other than the equivalent of that, like some kinda splice(), then do it yourself with $track->events_r or $track->events. DIY queen 🎀

the method $track->dump({ ...options... })

this dumps the track's contents for your inspection. the dump format is code that looks like Perl code that you'd use to recreate that track. this routine outputs with just print, so you can use select to change where that'll go. the author intended this to be just an internal routine for use only by the method MIDI::Opus::dump, but figured it might be useful to you, if you need to dump the code for just a given track. read the source if you really need to know how this works. 👀

---

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

---

⭐ AUTHOR ⭐

• Sean M. Burke "sburke@cpan.org" (until 2010)
• Darrell Conklin "conklin@cpan.org" (from 2010)

---

and that's the whole page bestie, tysm for reading 🫶 this was MIDI::Track(3pm) from perl v5.36.0, dated 2023-10-28 — go make some tracks, they're gonna be iconic, i just know it 💖✨🎀🦋🌸