{
    "content": [
        {
            "type": "text",
            "text": "# MIDI::Track (perldoc)\n\n## NAME\n\nMIDI::Track -- functions and methods for MIDI tracks\n\n## SYNOPSIS\n\nuse MIDI; # ...which \"use\"s MIDI::Track et al\n$tacotrack = MIDI::Track->new;\n$tacotrack->events(\n['textevent', 0, \"I like tacos!\"],\n['noteon',    0, 4, 50, 96 ],\n['noteoff', 300, 4, 50, 96 ],\n);\n$opus = MIDI::Opus->new(\n{  'format' => 0,  'ticks' => 240,  'tracks' => [ $tacotrack ] }\n);\n...etc...\n\n## DESCRIPTION\n\nMIDI::Track provides a constructor and methods for objects representing a MIDI track. It is part\nof the MIDI suite.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **CONSTRUCTOR AND METHODS**\n- **COPYRIGHT**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "MIDI::Track",
        "section": "",
        "mode": "perldoc",
        "summary": "MIDI::Track -- functions and methods for MIDI tracks",
        "synopsis": "use MIDI; # ...which \"use\"s MIDI::Track et al\n$tacotrack = MIDI::Track->new;\n$tacotrack->events(\n['textevent', 0, \"I like tacos!\"],\n['noteon',    0, 4, 50, 96 ],\n['noteoff', 300, 4, 50, 96 ],\n);\n$opus = MIDI::Opus->new(\n{  'format' => 0,  'ticks' => 240,  'tracks' => [ $tacotrack ] }\n);\n...etc...",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 12,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 23,
                "subsections": []
            },
            {
                "name": "CONSTRUCTOR AND METHODS",
                "lines": 110,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 4,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "MIDI::Track -- functions and methods for MIDI tracks\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use MIDI; # ...which \"use\"s MIDI::Track et al\n$tacotrack = MIDI::Track->new;\n$tacotrack->events(\n['textevent', 0, \"I like tacos!\"],\n['noteon',    0, 4, 50, 96 ],\n['noteoff', 300, 4, 50, 96 ],\n);\n$opus = MIDI::Opus->new(\n{  'format' => 0,  'ticks' => 240,  'tracks' => [ $tacotrack ] }\n);\n...etc...\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "MIDI::Track provides a constructor and methods for objects representing a MIDI track. It is part\nof the MIDI suite.\n\nMIDI tracks have, currently, three attributes: a type, events, and data. Almost all tracks\nyou'll ever deal with are of type \"MTrk\", and so this is the type by default. Events are what\nmake up an MTrk track. If a track is not of type MTrk, or is an unparsed MTrk, then it has (or\nbetter have!) data.\n\nWhen an MTrk track is encoded, if there is data defined for it, that's what's encoded (and\n\"encoding data\" means just passing it thru untouched). Note that this happens even if the data\ndefined is \"\" (but it won't happen if the data is undef). However, if there's no data defined\nfor the MTrk track (as is the general case), then the track's events are encoded, via a call to\n\"MIDI::Event::encode\".\n\n(If neither events not data are defined, it acts as a zero-length track.)\n\nIf a non-MTrk track is encoded, its data is encoded. If there's no data for it, it acts as a\nzero-length track.\n\nIn other words, 1) events are meaningful only in an MTrk track, 2) you probably don't want both\ndata and events defined, and 3) 99.999% of the time, just worry about events in MTrk tracks,\nbecause that's all you ever want to deal with anyway.\n",
                "subsections": []
            },
            "CONSTRUCTOR AND METHODS": {
                "content": "MIDI::Track provides...\n\nthe constructor MIDI::Track->new({ ...options... })\nThis returns a new track object. By default, the track is of type MTrk, which is probably\nwhat you want. The options, which are optional, is an anonymous hash. There are four\nrecognized options: \"data\", which sets the data of the new track to the string provided;\n\"type\", which sets the type of the new track to the string provided; \"events\", which sets\nthe events of the new track to the contents of the list-reference provided (i.e., a\nreference to a LoL -- see perllol for the skinny on LoLs); and \"eventsr\", which is an exact\nsynonym of \"events\".\n\nthe method $newtrack = $track->copy\nThis duplicates the contents of the given track, and returns the duplicate. If you are\nunclear on why you may need this function, consider:\n\n$funk  = MIDI::Opus->new({'fromfile' => 'funk1.mid'});\n$samba = MIDI::Opus->new({'fromfile' => 'samba1.mid'});\n\n$basstrack = ( $funk->tracks )[-1]; # last track\npush(@{ $samba->tracksr }, $basstrack );\n# make it the last track\n\n&funkitup(  ( $funk->tracks )[-1]  );\n# modifies the last track of $funk\n&turnitout(  ( $samba->tracks )[-1]  );\n# modifies the last track of $samba\n\n$funk->writetofile('funk2.mid');\n$samba->writetofile('samba2.mid');\nexit;\n\nSo you have your routines funkitup and turnitout, and they each modify the track they're\napplied to in some way. But the problem is that the above code probably does not do what you\nwant -- because the last track-object of $funk and the last track-object of $samba are the\n*same object*. An object, you may be surprised to learn, can be in different opuses at the\nsame time -- which is fine, except in cases like the above code. That's where you need to do\ncopy the object. Change the above code to read:\n\npush(@{ $samba->tracksr }, $basstrack->copy );\n\nand what you want to happen, will.\n\nIncidentally, this potential need to copy also occurs with opuses (and in fact any\nreference-based data structure, altho opuses and tracks should cover almost all cases with\nMIDI stuff), which is why there's $opus->copy, for copying entire opuses.\n\n(If you happen to need to copy a single event, it's just $new = [@$old] ; and if you happen\nto need to copy an event structure (LoL) outside of a track for some reason, use\nMIDI::Event::copystructure.)\n\ntrack->skyline({ ...options... })\nskylines the entire track. Modifies the track. See MIDI::Score for documentation on skyline\n\nthe method $track->events( @events )\nReturns the list of events in the track, possibly after having set it to @events, if\nspecified and not empty. (If you happen to want to set the list of events to an empty list,\nfor whatever reason, you have to use \"$track->eventsr([])\".)\n\nIn other words: $track->events(@events) is how to set the list of events (assuming @events\nis not empty), and @events = $track->events is how to read the list of events.\n\nthe method $track->eventsr( $eventr )\nReturns a reference to the list of events in the track, possibly after having set it to\n$eventsr, if specified. Actually, \"$eventsr\" can be any listref to a LoL, whether it comes\nfrom a scalar as in $someeventsr, or from something like \"[@events]\", or just plain old\n\"\\@events\"\n\nOriginally $track->events was the only way to deal with events, but I added $track->eventsr\nto make possible 1) setting the list of events to (), for whatever that's worth, and 2) so\nyou can directly manipulate the track's events, without having to *copy* the list of events\n(which might be tens of thousands of elements long) back and forth. This way, you can say:\n\n$eventsr = $track->eventsr();\n@somestuff = splice(@$eventsr, 4, 6);\n\nBut if you don't know how to deal with listrefs outside of LoLs, that's OK, just use\n$track->events.\n\nthe method $track->type( 'MFoo' )\nReturns the type of $track, after having set it to 'MFoo', if provided. You probably won't\never need to use this method, other than in a context like:\n\nif( $track->type eq 'MTrk' ) { # The usual case\ngiveupthefunk($track);\n} # Else just keep on walkin'!\n\nTrack types must be 4 bytes long; see MIDI::Filespec for details.\n\nthe method $track->data( $kookybinarydata )\nReturns the data from $track, after having set it to $kookybinarydata, if provided -- even\nif it's zero-length! You probably won't ever need to use this method. For your information,\n$track->data(undef) is how to undefine the data for a track.\n\nthe method $track->newevent('event', ...parameters... )\nThis adds the event ('event', ...parameters...) to the end of the event list for $track.\nIt's just sugar for:\n\npush( @{$thistrack->eventsr}, [ 'event', ...params... ] )\n\nIf you want anything other than the equivalent of that, like some kinda splice(), then do it\nyourself with $track->eventsr or $track->events.\n\nthe method $track->dump({ ...options... })\nThis dumps the track's contents for your inspection. The dump format is code that looks like\nPerl code that you'd use to recreate that track. This routine outputs with just \"print\", so\nyou can use \"select\" to change where that'll go. I intended this to be just an internal\nroutine for use only by the method MIDI::Opus::dump, but I figure it might be useful to you,\nif you need to dump the code for just a given track. Read the source if you really need to\nknow how this works.\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Copyright (c) 1998-2002 Sean M. Burke. All rights reserved.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Sean M. Burke \"sburke@cpan.org\" (until 2010)\n\nDarrell Conklin \"conklin@cpan.org\" (from 2010)\n",
                "subsections": []
            }
        }
    }
}