{
    "content": [
        {
            "type": "text",
            "text": "# MIDI::Score (perldoc)\n\n## NAME\n\nMIDI::Score - MIDI scores\n\n## SYNOPSIS\n\n# it's a long story; see below\n\n## DESCRIPTION\n\nThis module provides functions to do with MIDI scores. It is used as the basis for all the\nfunctions in MIDI::Simple. (Incidentally, MIDI::Opus's draw() method also uses some of the\nfunctions in here.)\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **WHAT CAN BE IN A SCORE**\n- **FUNCTIONS**\n- **COPYRIGHT**\n- **AUTHORS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "MIDI::Score",
        "section": "",
        "mode": "perldoc",
        "summary": "MIDI::Score - MIDI scores",
        "synopsis": "# it's a long story; see below",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 99,
                "subsections": []
            },
            {
                "name": "WHAT CAN BE IN A SCORE",
                "lines": 50,
                "subsections": []
            },
            {
                "name": "FUNCTIONS",
                "lines": 61,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 4,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "MIDI::Score - MIDI scores\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "# it's a long story; see below\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module provides functions to do with MIDI scores. It is used as the basis for all the\nfunctions in MIDI::Simple. (Incidentally, MIDI::Opus's draw() method also uses some of the\nfunctions in here.)\n\nWhereas the events in a MIDI event structure are items whose timing is expressed in delta-times,\nthe timing of items in a score is expressed as an absolute number of ticks from the track's\nstart time. Moreover, pairs of 'noteon' and 'noteoff' events in an event structure are\nabstracted into a single 'note' item in a score structure.\n\n'note' takes the following form:\n\n('noteon', I<starttime>, I<duration>, I<channel>, I<note>, I<velocity>)\n\nThe problem that score structures are meant to solve is that 1) people definitely don't think in\ndelta-times -- they think in absolute times or in structures based on that (like 'time from\nstart of measure'); 2) people think in notes, not noteon and noteoff events.\n\nSo, given this event structure:\n\n['textevent', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],\n['textevent', 0, 'Lord through this hour/ be Thou our guide'],\n['textevent', 0, 'so, by Thy power/ no foot shall slide'],\n['patchchange', 0, 1, 8],\n['noteon', 0, 1, 25, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 29, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 27, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 20, 96],\n['noteoff', 192, 0, 1, 0],\n['noteon', 0, 1, 25, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 27, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 29, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 25, 96],\n['noteoff', 192, 0, 1, 0],\n['noteon', 0, 1, 29, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 25, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 27, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 20, 96],\n['noteoff', 192, 0, 1, 0],\n['noteon', 0, 1, 20, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 27, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 29, 96],\n['noteoff', 96, 0, 1, 0],\n['noteon', 0, 1, 25, 96],\n['noteoff', 192, 0, 1, 0],\n\nhere is the corresponding score structure:\n\n['textevent', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],\n['textevent', 0, 'Lord through this hour/ be Thou our guide'],\n['textevent', 0, 'so, by Thy power/ no foot shall slide'],\n['patchchange', 0, 1, 8],\n['note', 0, 96, 1, 25, 96],\n['note', 96, 96, 1, 29, 96],\n['note', 192, 96, 1, 27, 96],\n['note', 288, 192, 1, 20, 96],\n['note', 480, 96, 1, 25, 96],\n['note', 576, 96, 1, 27, 96],\n['note', 672, 96, 1, 29, 96],\n['note', 768, 192, 1, 25, 96],\n['note', 960, 96, 1, 29, 96],\n['note', 1056, 96, 1, 25, 96],\n['note', 1152, 96, 1, 27, 96],\n['note', 1248, 192, 1, 20, 96],\n['note', 1440, 96, 1, 20, 96],\n['note', 1536, 96, 1, 27, 96],\n['note', 1632, 96, 1, 29, 96],\n['note', 1728, 192, 1, 25, 96]\n\nNote also that scores aren't crucially ordered. So this:\n\n['note', 768, 192, 1, 25, 96],\n['note', 960, 96, 1, 29, 96],\n['note', 1056, 96, 1, 25, 96],\n\nmeans the same thing as:\n\n['note', 960, 96, 1, 29, 96],\n['note', 768, 192, 1, 25, 96],\n['note', 1056, 96, 1, 25, 96],\n\nThe only exception to this is in the case of things like:\n\n['patchchange', 200,     2, 15],\n['note',         200, 96, 2, 25, 96],\n\nwhere two (or more) score items happen *at the same time* and where one affects the meaning of\nthe other.\n",
                "subsections": []
            },
            "WHAT CAN BE IN A SCORE": {
                "content": "Besides the new score structure item \"note\" (covered above), the possible contents of a score\nstructure can be summarized thus: Whatever can appear in an event structure can appear in a\nscore structure, save that its second parameter denotes not a delta-time in ticks, but instead\ndenotes the absolute number of ticks from the start of the track.\n\nTo avoid the long periphrase \"items in a score structure\", I will occasionally refer to items in\na score structure as \"notes\", whether or not they are actually \"note\" commands. This leaves\n\"event\" to unambiguously denote items in an event structure.\n\nThese, below, are all the items that can appear in a score. This is basically just a repetition\nof the table in MIDI::Event, with starttime substituting for dtime -- so refer to MIDI::Event\nfor an explanation of what the data types (like \"velocity\" or \"pitchwheel\"). As far as order,\nthe first items are generally the most important:\n\n('note', *starttime*, *duration*, *channel*, *note*, *velocity*)\n('keyaftertouch', *starttime*, *channel*, *note*, *velocity*)\n('controlchange', *starttime*, *channel*, *controller(0-127)*, *value(0-127)*)\n('patchchange', *starttime*, *channel*, *patch*)\n('channelaftertouch', *starttime*, *channel*, *velocity*)\n('pitchwheelchange', *starttime*, *channel*, *pitchwheel*)\n('setsequencenumber', *starttime*, *sequence*)\n('textevent', *starttime*, *text*)\n('copyrighttextevent', *starttime*, *text*)\n('trackname', *starttime*, *text*)\n('instrumentname', *starttime*, *text*)\n('lyric', *starttime*, *text*)\n('marker', *starttime*, *text*)\n('cuepoint', *starttime*, *text*)\n('textevent08', *starttime*, *text*)\n('textevent09', *starttime*, *text*)\n('textevent0a', *starttime*, *text*)\n('textevent0b', *starttime*, *text*)\n('textevent0c', *starttime*, *text*)\n('textevent0d', *starttime*, *text*)\n('textevent0e', *starttime*, *text*)\n('textevent0f', *starttime*, *text*)\n('endtrack', *starttime*)\n('settempo', *starttime*, *tempo*)\n('smpteoffset', *starttime*, *hr*, *mn*, *se*, *fr*, *ff*)\n('timesignature', *starttime*, *nn*, *dd*, *cc*, *bb*)\n('keysignature', *starttime*, *sf*, *mi*)\n('sequencerspecific', *starttime*, *raw*)\n('rawmetaevent', *starttime*, *command*(0-255), *raw*)\n('sysexf0', *starttime*, *raw*)\n('sysexf7', *starttime*, *raw*)\n('songposition', *starttime*)\n('songselect', *starttime*, *songnumber*)\n('tunerequest', *starttime*)\n('rawdata', *starttime*, *raw*)\n",
                "subsections": []
            },
            "FUNCTIONS": {
                "content": "This module provides these functions:\n\n$score2r = MIDI::Score::copystructure($scorer)\nThis takes a *reference* to a score structure, and returns a *reference* to a copy of it.\nExample usage:\n\n@newscore = @{ MIDI::Score::copystructure( \\@oldscore ) };\n\n$eventsr = MIDI::Score::scorertoeventsr( $scorer )\n($eventsr, $ticks) = MIDI::Score::scorertoeventsr( $scorer )\nThis takes a *reference* to a score structure, and converts it to an event structure, which\nit returns a *reference* to. In list context, also returns a second value, a count of the\nnumber of ticks that structure takes to play (i.e., the end-time of the temporally last\nitem).\n\n$score2r = MIDI::Score::sortscorer( $scorer)\nThis takes a *reference* to a score structure, and returns a *reference* to a sorted (by\ntime) copy of it. Example usage:\n\n@sortedscore = @{ MIDI::Score::sortscorer( \\@oldscore ) };\n\n$scorer = MIDI::Score::eventsrtoscorer( $eventsr )\n($scorer, $ticks) = MIDI::Score::eventsrtoscorer( $eventsr )\nThis takes a *reference* to an event structure, converts it to a score structure, which it\nreturns a *reference* to. If called in list context, also returns a count of the number of\nticks that structure takes to play (i.e., the end-time of the temporally last item).\n\n$ticks = MIDI::Score::scorertime( $scorer )\nThis takes a *reference* to a score structure, and returns a count of the number of ticks\nthat structure takes to play (i.e., the end-time of the temporally last item).\n\nMIDI::Score::dumpscore( $scorer )\nThis dumps (via \"print\") a text representation of the contents of the event structure you\npass a reference to.\n\nMIDI::Score::quantize( $scorer )\nThis takes a *reference* to a score structure, performs a grid quantize on all events,\nreturning a new score reference with new quantized events. Two parameters to the method are:\n'grid': the quantization grid, and 'durations': whether or not to also quantize event\ndurations (default off).\n\nWhen durations of note events are quantized, they can get 0 duration. These events are *not\ndropped* from the returned score, and it is the responsibility of the caller to deal with\nthem.\n\nMIDI::Score::skyline( $scorer )\nThis takes a *reference* to a score structure, performs skyline (create a monophonic track\nby extracting the event with highest pitch at unique onset times) on the score, returning a\nnew score reference. The parameters to the method is: 'clip': whether durations of events\nare preserved or possibly clipped and modified.\n\nTo explain this, consider the following (from Bach 2 part invention no.6 in E major):\n\n|------e------|-------ds--------|-------d------|...\n|--E-----|-------Fs-------|------Gs-----|...\n\nWithout duration cliping, the skyline is E, Fs, Gs...\n\nWith duration clipping, the skyline is E, e, ds, d..., where the duration of E is clipped to\njust the * portion above\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": []
            },
            "AUTHORS": {
                "content": "Sean M. Burke \"sburke@cpan.org\" (until 2010)\n\nDarrell Conklin \"conklin@cpan.org\" (from 2010)\n",
                "subsections": []
            }
        }
    }
}