Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MIDI::Track(3)	      User Contributed Perl Documentation	MIDI::Track(3)

NAME
       MIDI::Track -- functions	and methods for	MIDI tracks

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

DESCRIPTION
       MIDI::Track provides a constructor and methods for objects representing
       a MIDI track.  It is part of the	MIDI suite.

       MIDI tracks have, currently, three attributes: a	type, events, and
       data.  Almost all tracks	you'll ever deal with are of type "MTrk", and
       so this is the type by default.	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 is data defined for it, that's
       what's encoded (and "encoding data" means just passing it thru
       untouched).  Note that 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), then the track's
       events are encoded, via a call to "MIDI::Event::encode".

       (If neither events not data are defined,	it acts	as a zero-length
       track.)

       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, 1) events are meaningful	only in	an MTrk	track, 2) you
       probably	don't want both	data and events	defined, and 3)	99.999%	of the
       time, just worry	about events in	MTrk tracks, because that's all	you
       ever want to deal with anyway.

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.  The options,	which are
	   optional, is	an anonymous hash.  There are four recognized options:
	   "data", which sets the data of the new track	to the string
	   provided; "type", which sets	the type of the	new track to the
	   string provided; "events", which 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); and	"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 do 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

       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.

       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
	   I added $track->events_r to make possible 1)	setting	the list of
	   events to (), for whatever that's worth, and	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.  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.

       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.

       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.

       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.	 I intended this to be just an
	   internal routine for	use only by the	method MIDI::Opus::dump, but I
	   figure 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)

perl v5.24.1			  2013-02-01			MIDI::Track(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR AND METHODS | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MIDI::Track&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help