{ "content": [ { "type": "text", "text": "# MIDI::Simple (perldoc)\n\n## NAME\n\nMIDI::Simple - procedural/OOP interface for MIDI composition\n\n## SYNOPSIS\n\nuse MIDI::Simple;\nnewscore;\ntextevent 'http://www.ely.anglican.org/parishes/camgsm/bells/chimes.html';\ntextevent 'Lord through this hour/ be Thou our guide';\ntextevent 'so, by Thy power/ no foot shall slide';\nsettempo 500000; # 1 qn => .5 seconds (500,000 microseconds)\npatchchange 1, 8; # Patch 8 = Celesta\nnoop c1, f, o5; # Setup\n# Now play\nn qn, Cs; n F; n Ds; n hn, Gsd1;\nn qn, Cs; n Ds; n F; n hn, Cs;\nn qn, F; n Cs; n Ds; n hn, Gsd1;\nn qn, Gsd1; n Ds; n F; n hn, Cs;\nwritescore 'westmisterchimes.mid';\n\n## DESCRIPTION\n\nThis module sits on top of all the MIDI modules -- notably MIDI::Score (so you should skim\nMIDI::Score) -- and is meant to serve as a basic interface to them, for composition. By\ncomposition, I mean composing anew; you can use this module to add to or modify existing MIDI\nfiles, but that functionality is to be considered a bit experimental.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **NOTE ON VERSION CHANGES** (7 subsections)\n- **COPYRIGHT**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "MIDI::Simple", "section": "", "mode": "perldoc", "summary": "MIDI::Simple - procedural/OOP interface for MIDI composition", "synopsis": "use MIDI::Simple;\nnewscore;\ntextevent 'http://www.ely.anglican.org/parishes/camgsm/bells/chimes.html';\ntextevent 'Lord through this hour/ be Thou our guide';\ntextevent 'so, by Thy power/ no foot shall slide';\nsettempo 500000; # 1 qn => .5 seconds (500,000 microseconds)\npatchchange 1, 8; # Patch 8 = Celesta\nnoop c1, f, o5; # Setup\n# Now play\nn qn, Cs; n F; n Ds; n hn, Gsd1;\nn qn, Cs; n Ds; n F; n hn, Cs;\nn qn, F; n Cs; n Ds; n hn, Gsd1;\nn qn, Gsd1; n Ds; n F; n hn, Cs;\nwritescore 'westmisterchimes.mid';", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 17, "subsections": [] }, { "name": "DESCRIPTION", "lines": 13, "subsections": [] }, { "name": "NOTE ON VERSION CHANGES", "lines": 85, "subsections": [ { "name": "new_score", "lines": 4 }, { "name": "n", "lines": 6 }, { "name": "r", "lines": 4 }, { "name": "noop", "lines": 340 }, { "name": "About Tempo", "lines": 1 }, { "name": "set_tempo", "lines": 96 }, { "name": "synch", "lines": 257 } ] }, { "name": "COPYRIGHT", "lines": 5, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "MIDI::Simple - procedural/OOP interface for MIDI composition\n", "subsections": [] }, "SYNOPSIS": { "content": "use MIDI::Simple;\nnewscore;\ntextevent 'http://www.ely.anglican.org/parishes/camgsm/bells/chimes.html';\ntextevent 'Lord through this hour/ be Thou our guide';\ntextevent 'so, by Thy power/ no foot shall slide';\nsettempo 500000; # 1 qn => .5 seconds (500,000 microseconds)\npatchchange 1, 8; # Patch 8 = Celesta\n\nnoop c1, f, o5; # Setup\n# Now play\nn qn, Cs; n F; n Ds; n hn, Gsd1;\nn qn, Cs; n Ds; n F; n hn, Cs;\nn qn, F; n Cs; n Ds; n hn, Gsd1;\nn qn, Gsd1; n Ds; n F; n hn, Cs;\n\nwritescore 'westmisterchimes.mid';\n", "subsections": [] }, "DESCRIPTION": { "content": "This module sits on top of all the MIDI modules -- notably MIDI::Score (so you should skim\nMIDI::Score) -- and is meant to serve as a basic interface to them, for composition. By\ncomposition, I mean composing anew; you can use this module to add to or modify existing MIDI\nfiles, but that functionality is to be considered a bit experimental.\n\nThis module provides two related but distinct bits of functionality: 1) a mini-language\n(implemented as procedures that can double as methods) for composing by adding notes to a score\nstructure; and 2) simple functions for reading and writing scores, specifically the scores you\nmake with the composition language.\n\nThe fact that this module's interface is both procedural and object-oriented makes it a definite\ntwo-headed beast. The parts of the guts of the source code are not for the faint of heart.\n", "subsections": [] }, "NOTE ON VERSION CHANGES": { "content": "This module is somewhat incompatible with the MIDI::Simple versions before .700 (but that was a\n*looong* time ago).\n\nOBJECT STRUCTURE\nA MIDI::Simple object is a data structure with the following attributes:\n\nScore\nThis is a list of all the notes (each a listref) that constitute this one-track musical\npiece. Scores are explained in MIDI::Score. You probably don't need to access the Score\nattribute directly, but be aware that this is where all the notes you make with \"n\" events\ngo.\n\nTime\nThis is a non-negative integer expressing the start-time, in ticks from the start-time of\nthe MIDI piece, that the next note pushed to the Score will have.\n\nChannel\nThis is a number in the range [0-15] that specifies the current default channel for note\nevents.\n\nDuration\nThis is a non-negative (presumably nonzero) number expressing, in ticks, the current default\nlength of note events, or rests.\n\nOctave\nThis is a number in the range [0-10], expressing what the current default octave number is.\nThis is used for figuring out exactly what note-pitch is meant by a relative note-pitch\nspecification like \"A\".\n\nNotes\nThis is a list (presumably non-empty) of note-pitch specifications, *as note numbers* in the\nrange [0-127].\n\nVolume\nThis is an integer in the range [0-127] expressing the current default volume for note\nevents.\n\nTempo\nThis is an integer expressing the number of ticks a quarter note occupies. It's currently\n96, and you shouldn't alter it unless you *really* know what you're doing. If you want to\ncontrol the tempo of a piece, use the \"settempo\" routine, instead.\n\nCookies\nThis is a hash that can be used by user-defined object-methods for storing whatever they\nwant.\n\nEach package that you call the procedure \"newscore\" from, has a default MIDI::Simple object\nassociated with it, and all the above attributes are accessible as:\n\n@Score $Time $Channel $Duration $Octave\n@Notes $Volume $Tempo %Cookies\n\n(Although I doubt you'll use these from any package other than \"main\".) If you don't know what a\npackage is, don't worry about it. Just consider these attributes synonymous with the\nabove-listed variables. Just start your programs with\n\nuse MIDI::Simple;\nnewscore;\n\nand you'll be fine.\n\nRoutine/Method/Procedure\nMIDI::Simple provides some pure functions (i.e., things that take input, and give a return\nvalue, and that's all they do), but what you're mostly interested in its routines. By \"routine\"\nI mean a subroutine that you call, whether as a procedure or as a method, and that affects data\nstructures other than the return value.\n\nHere I'm using \"procedure\" to mean a routine you call like this:\n\nname(parameters...);\n# or, just maybe:\nname;\n\n(In technical terms, I mean a non-method subroutine that can have side effects, and which may\nnot even provide a useful return value.) And I'm using \"method\" to mean a routine you call like\nthis:\n\n$object->name(parameters);\n\nSo bear these terms in mind when you see routines below that act like one, or the other, or\nboth.\n\nMAIN ROUTINES\nThese are the most important routines:\n", "subsections": [ { "name": "new_score", "content": "As a procedure, this initializes the package's default object (Score, etc.). As a method,\nthis is a constructor, returning a new MIDI::Simple object. Neither form takes any\nparameters.\n" }, { "name": "n", "content": "This uses the parameters given (and/or the state variables like Volume, Channel, Notes, etc)\nto add a new note to the Score -- or several notes to the Score, if Notes has more than one\nelement in it -- or no notes at all, if Notes is empty list.\n\nThen it moves Time ahead as appropriate. See the section \"Parameters For n/r/noop\", below.\n" }, { "name": "r", "content": "This is exactly like \"n\", except it never pushes anything to Score, but moves ahead Time.\n(In other words, there is no such thing as a rest-event; it's just a item during which there\nare no note-events playing.)\n" }, { "name": "noop", "content": "This is exactly like \"n\" and \"r\", except it never alters Score, *and* never changes Time. It\nis meant to be used for setting the other state variables, i.e.: Channel, Duration, Octave,\nVolume, Notes.\n\nParameters for n/r/noop\nA parameter in an \"n\", \"r\", or \"noop\" call is meant to change an attribute (AKA state variable),\nnamely Channel, Duration, Octave, Volume, or Notes.\n\nHere are the kinds of parameters you can use in calls to n/r/noop:\n\n* A numeric volume parameter. This has the form \"V\" followed by a positive integer in the range\n0 (completely inaudible?) to 127 (AS LOUD AS POSSIBLE). Example: \"V90\" sets Volume to 90.\n\n* An alphanumeric volume parameter. This is a key from the hash %MIDI::Simple::Volume. Current\nlegal values are \"ppp\", \"pp\", \"p\", \"mp\", \"mezzo\" (or \"m\"), \"mf\", \"f\", \"ff\", and \"fff\". Example:\n\"ff\" sets Volume to 112. (Note that \"m\" isn't a good bareword, so use \"mezzo\" instead, or just\nalways remember to use quotes around \"m\".)\n\n* A numeric channel parameter. This has the form \"c\" followed by a positive integer 0 to 15.\nExample: \"c2\", to set Channel to 2.\n\n* A numeric duration parameter. This has the form \"d\" followed by a positive (presumably\nnonzero) integer. Example: \"d48\", to set Duration to 48.\n\n* An alphabetic (or in theory, possibly alphanumeric) duration parameter. This is a key from the\nhash %MIDI::Simple::Length. Current legal values start with \"wn\", \"hn\", \"qn\", \"en\", \"sn\" for\nwhole, half, quarter, eighth, or sixteenth notes. Add \"d\" to the beginning of any of these to\nget \"dotted...\" (e.g., \"dqn\" for a dotted quarter note). Add \"dd\" to the beginning of any of\nthat first list to get \"double-dotted...\" (e.g., \"ddqn\" for a double-dotted quarter note). Add\n\"t\" to the beginning of any of that first list to get \"triplet...\" (e.g., \"tsn\" for a triplet\nsixteenth note -- i.e. a note such that 3 of them add up to something as long as one eighth\nnote). You may add to the contents of %MIDI::Simple::Length to support whatever abbreviations\nyou want, as long as the parser can't mistake them for any other kind of n/r/noop parameter.\n\n* A numeric, absolute octave specification. This has the form: an \"o\" (lowercase oh), and then\nan integer in the range 0 to 10, representing an octave 0 to 10. The Octave attribute is used\nonly in resolving relative note specifications, as explained further below in this section. (All\nabsolute note specifications also set Octave to whatever octave they occur in.)\n\n* A numeric, relative octave specification. This has the form: \"od\" (\"d\" for down) or \"ou\"\n(\"u\" for down), and then an integer. This increments, or decrements, Octave. E.g., if Octave is\n6, \"od2\" will decrement Octave by 2, making it 4. If this moves Octave below 0, it is forced to\n0. Or if it moves Octave above 10, it is forced to 10. (For more information, see the section\n\"Invalid or Out-of-Range Parameters to n/r/noop\", below.)\n\n* A numeric, absolute note specification. This has the form: an optional \"n\", and then an\ninteger in the range 0 to 127, representing a note ranging from C0 to G10. The source to MIDI\nhas a useful reference table showing the meanings of given note numbers. Examples: \"n60\", or\n\"60\", which each add a 60 to the list Notes.\n\nSince this is a kind of absolute note specification, it sets Octave to whatever octave the given\nnumeric note occurs in. E.g., \"n60\" is \"C5\", and therefore sets Octave to 5.\n\nThe setting of the Notes list is a bit special, compared to how setting the other attributes\nworks. If there are any note specifications in a given parameter list for n, r, or noop, then\nall those specifications together are assigned to Notes.\n\nIf there are no note specifications in the parameter list for n, r, or noop, then Notes isn't\nchanged. (But see the description of \"rest\", at the end of this section.)\n\nSo this:\n\nn mf, n40, n47, n50;\n\nsets Volume to 80, and Notes to (40, 47, 50). And it sets Octave, first to 3 (since n40 is in\noctave 3), then to 3 again (since n47 = B3), and then finally to 4 (since n50 = D4).\n\nNote that this is the same as:\n\nn n40, n47, n50, mf;\n\nThe relative orders of parameters is usually irrelevant; but see the section \"Order of\nParameters in a Call to n/r/noop\", below.\n\n* An alphanumeric, absolute note specification.\n\nThese have the form: a string denoting a note within the octave (as determined by\n%MIDI::Simple::Note -- see below, in the description of alphanumeric, relative note\nspecifications), and then a number denoting the octave number (in the range 0-10). Examples:\n\"C3\", \"As4\" or \"Asharp4\", \"Bf9\" or \"Bflat9\".\n\nSince this is a kind of absolute note specification, it sets Octave to whatever octave the given\nnumeric note occurs in. E.g., \"C3\" sets Octave to 3, \"As4\" sets Octave to 4, and \"Bflat9\" sets\nOctave to 9.\n\nThis:\n\nn E3, B3, D4, mf;\n\ndoes the same as this example of ours from before:\n\nn n40, n47, n50, mf;\n\n* An alphanumeric, relative note specification.\n\nThese have the form: a string denoting a note within the octave (as determined by\n%MIDI::Simple::Note), and then an optional parameter \"u[number]\" meaning \"so many octaves up\nfrom the current octave\" or \"d[parameter]\" meaning \"so many octaves down from the current\noctave\".\n\nExamples: \"C\", \"As\" or \"Asharp\", \"Bflat\" or \"Bf\", \"Cd3\", \"Asd1\" or \"Asharpd1\", \"Bflatu3\" or\n\"Bfu3\".\n\nIn resolving what actual notes these kinds of specifications denote, the current value of Octave\nis used.\n\nWhat's a legal for the first bit (before any optional octave up/down specification) comes from\nthe keys to the hash %MIDI::Simple::Note. The current acceptable values are:\n\nC (maps to the value 0)\nCs or Df or Csharp or Dflat (maps to the value 1)\nD (maps to the value 2)\nDs or Ef or Dsharp or Eflat (maps to the value 3)\nE (maps to the value 4)\nF (maps to the value 5)\nFs or Gf or Fsharp or Gflat (maps to the value 6)\nG (maps to the value 7)\nGs or Af or Gsharp or Aflat (maps to the value 8)\nA (maps to the value 9)\nAs or Bf or Asharp or Bflat (maps to the value 10)\nB (maps to the value 11)\n\n(Note that these are based on the English names for these notes. If you prefer to add values to\naccommodate other strings denoting notes in the octave, you may do so by adding to the hash\n%MIDI::Simple::Note like so:\n\nuse MIDI::Simple;\n%MIDI::Simple::Note =\n(%MIDI::Simple::Note, # keep all the old values\n'H' => 10,\n'Do' => 0,\n# ...etc...\n);\n\nBut the values you add must not contain any characters outside the range [A-Za-z\\x80-\\xFF]; and\nyour new values must not look like anything that could be any other kind of specification. E.g.,\ndon't add \"mf\" or \"o3\" to %MIDI::Simple::Note.)\n\nConsider that these bits of code all do the same thing:\n\nn E3, B3, D4, mf; # way 1\n\nn E3, B, Du1, mf; # way 2\n\nn o3, E, B, Du1, mf; # way 3\n\nnoop o3, mf; # way 4\nn E, B, Du1;\n\nor even\n\nn o3, E, B, o4, D, mf; # way 5!\n\nn o6, Ed3, Bd3, Dd2, mf; # way 6!\n\nIf a \"d[number]\" would refer to a note in an octave below 0, it is forced into octave 0. If a\n\"u[number]\" would refer to a note in an octave above 10, it is forced into octave 10. E.g., if\nOctave is 8, \"Gu4\" would resolve to the same as \"G10\" (not \"G12\" -- as that's out of range); if\nOctave is 2, \"Gd4\" would resolve to the same as \"G0\". (For more information, see the section\n\"Invalid or Out-of-Range Parameters to n/r/noop\", below.)\n\n* The string \"\"rest\"\" acts as a sort of note specification -- it sets Notes to empty-list. That\nway you can make a call to \"n\" actually make a rest:\n\nn qn, G; # makes a G quarter-note\nn hn, rest; # half-rest -- alters Notes, making it ()\nn C,G; # half-note chord: simultaneous C and G\nr; # half-rest -- DOESN'T alter Notes.\nn qn; # quarter-note chord: simultaneous C and G\nn rest; # quarter-rest\nn; # another quarter-rest\n\n(If you can follow the above code, then you understand.)\n\nA \"\"rest\"\" that occurs in a parameter list with other note specs (e.g., \"n qn, A, rest, G\") has\nno effect, so don't do that.\n\nOrder of Parameters in a Call to n/r/noop\nThe order of parameters in calls to n/r/noop is not important except insofar as the parameters\nchange the Octave parameter, which may change how some relative note specifications are\nresolved. For example:\n\nnoop o4, mf;\nn G, B, A3, C;\n\nis the same as \"n mf, G4, B4, A3, C3\". But just move that \"C\" to the start of the list:\n\nnoop o4, mf;\nn C, G, B, A3;\n\nand you something different, equivalent to \"n mf, C4, G4, B4, A3\".\n\nBut note that you can put the \"mf\" anywhere without changing anything.\n\nBut stylistically, I strongly advise putting note parameters at the end of the parameter list:\n\nn mf, c10, C, B; # 1. good\nn C, B, mf, c10; # 2. bad\nn C, mf, c10, B; # 3. so bad!\n\n3 is particularly bad because an uninformed/inattentive reader may get the impression that the C\nmay be at a different volume and on a different channel than the B.\n\n(Incidentally, \"n C5,G5\" and \"n G5,C5\" are the same for most purposes, since the C and the G are\nplayed at the same time, and with the same parameters (channel and volume); but actually they\ndiffer in which note gets put in the Score first, and therefore which gets encoded first in the\nMIDI file -- but this makes no difference at all, unless you're manipulating the note-items in\nScore or the MIDI events in a track.)\n\nInvalid or Out-of-Range Parameters to n/r/noop\nIf a parameter in a call to n/r/noop is uninterpretable, Perl dies with an error message to that\neffect.\n\nIf a parameter in a call to n/r/noop has an out-of-range value (like \"o12\" or \"c19\"), Perl dies\nwith an error message to that effect.\n\nAs somewhat of a merciful exception to this rule, if a parameter in a call to n/r/noop is a\nrelative specification (whether like \"od3\" or \"ou3\", or like \"Gd3\" or \"Gu3\") which happens\nto resolve to an out-of-range value (like \"Gd3\" given an Octave value of 2), then Perl will not\ndie, but instead will silently try to bring that note back into range, by forcing it up to\noctave 0 (if it would have been lower), or down into 9 or 10 (if it would have been an octave\nhigher than 10, or a note higher than G10), as appropriate.\n\n(This becomes strange in that, given an Octave of 8, \"Gu4\" is forced down to G10, but \"Au4\" is\nforced down to an A9. But that boundary has to pop up someplace -- it's just unfortunate that\nit's in the middle of octave 10.)\n\nATTRIBUTE METHODS\nThe object attributes discussed above are readable and writeable with object methods. For each\nattribute there is a read/write method, and a read-only method that returns a reference to the\nattribute's value:\n\nAttribute || R/W-Method || RO-R-Method\n----------++-------------++--------------------------------------\nScore || Score || Scorer (returns a listref)\nNotes || Notes || Notesr (returns a listref)\nTime || Time || Timer (returns a scalar ref)\nDuration || Duration || Durationr (returns a scalar ref)\nChannel || Channel || Channelr (returns a scalar ref)\nOctave || Octave || Octaver (returns a scalar ref)\nVolume || Volume || Volumer (returns a scalar ref)\nTempo || Tempo || Tempor (returns a scalar ref)\nCookies || Cookies || Cookiesr (returns a hashref)\n\nTo read any of the above via a R/W-method, call with no parameters, e.g.:\n\n$notes = $obj->Notes; # same as $obj->Notes()\n\nThe above is the read-attribute (\"get\") form.\n\nTo set the value, call with parameters:\n\n$obj->Notes(13,17,22);\n\nThe above is the write-attribute (\"put\") form. Incidentally, when used in write-attribute form,\nthe return value is the same as the parameters, except for Score or Cookies. (In those two\ncases, I've suppressed it for efficiency's sake.)\n\nAlternately (and much more efficiently), you can use the read-only reference methods to read or\nalter the above values;\n\n$notesr = $obj->Notesr;\n# to read:\n@oldnotes = @$notesr;\n# to write:\n@$notesr = (13,17,22);\n\nAnd this is the only way to set Cookies, Notes, or Score to a (), like so:\n\n$notesr = $obj->Notesr;\n@$notesr = ();\n\nSince this:\n\n$obj->Notes;\n\nis just the read-format call, remember?\n\nLike all methods in this class, all the above-named attribute methods double as procedures that\nact on the default object -- in other words, you can say:\n\nVolume 10; # same as: $Volume = 10;\n@scorecopy = Score; # same as: @scorecopy = @Score\nScore @newscore; # same as: @Score = @newscore;\n$scoreref = Scorer; # same as: $scoreref = \\@Score\nVolume(Volume + 10) # same as: $Volume += 10\n\nBut, stylistically, I suggest not using these procedures -- just directly access the variables\ninstead.\n\nMIDI EVENT ROUTINES\nThese routines, below, add a MIDI event to the Score, with a start-time of Time. Example:\n\ntextevent \"And now the bongos!\"; # procedure use\n\n$obj->textevent \"And now the bongos!\"; # method use\n\nThese are named after the MIDI events they add to the score, so see MIDI::Event for an\nexplanation of what the data types (like \"velocity\" or \"pitchwheel\") mean. I've reordered this\nlist so that what I guess are the most important ones are toward the top:\n\npatchchange *channel*, *patch*;\nkeyaftertouch *channel*, *note*, *velocity*;\nchannelaftertouch *channel*, *velocity*;\ncontrolchange *channel*, *controller(0-127)*, *value(0-127)*;\npitchwheelchange *channel*, *pitchwheel*;\nsettempo *tempo*; (See the section on tempo, below.)\nsmpteoffset *hr*, *mn*, *se*, *fr*, *ff*;\ntimesignature *nn*, *dd*, *cc*, *bb*;\nkeysignature *sf*, *mi*;\ntextevent *text*;\ncopyrighttextevent *text*;\ntrackname *text*;\ninstrumentname *text*;\nlyric *text*;\nsetsequencenumber *sequence*;\nmarker *text*;\ncuepoint *text*;\nsequencerspecific *raw*;\nsysexf0 *raw*;\nsysexf7 *raw*;\n\nAnd here's the ones I'll be surprised if anyone ever uses:\n\ntextevent08 *text*;\ntextevent09 *text*;\ntextevent0a *text*;\ntextevent0b *text*;\ntextevent0c *text*;\ntextevent0d *text*;\ntextevent0e *text*;\ntextevent0f *text*;\nrawmetaevent *command*(0-255), *raw*;\nsongposition *starttime*;\nsongselect *songnumber*;\ntunerequest *starttime*;\nrawdata *raw*;\nendtrack *starttime*;\nnote *duration*, *channel*, *note*, *velocity*;\n" }, { "name": "About Tempo", "content": "The chart above shows that tempo is set with a method/procedure that takes the form" }, { "name": "set_tempo", "content": "(0x00FFFFFF)\". But at the same time, you see that there's an attribute of the MIDI::Simple\nobject called \"Tempo\", which I've warned you to leave at the default value of 96. So you may\nwonder what the deal is.\n\nThe \"Tempo\" attribute (AKA \"Divisions\") is an integer that specifies the number of \"ticks\" per\nMIDI quarter note. Ticks is just the notional timing unit all MIDI events are expressed in terms\nof. Calling it \"Tempo\" is misleading, really; what you want to change to make your music go\nfaster or slower isn't that parameter, but instead the mapping of ticks to actual time -- and\nthat is what \"settempo\" does. Its one parameter is the number of microseconds each quarter note\nshould get.\n\nSuppose you wanted a tempo of 120 quarter notes per minute. In terms of microseconds per quarter\nnote:\n\nsettempo 500000; # you can use like a thousands-separator comma\n\nIn other words, this says to make each quarter note take up 500,000 microseconds, namely .5\nseconds. And there's 120 of those half-seconds to the minute; so, 120 quarter notes to the\nminute.\n\nIf you see a \"[quarter note symbol] = 160\" in a piece of sheet music, and you want to figure out\nwhat number you need for the \"settempo\", do:\n\n60000000 / 160 ... and you get: 375000\n\nTherefore, you should call:\n\nsettempo 375000;\n\nSo in other words, this general formula:\n\nsettempo int(60000000 / $quarternotesperminute);\n\nshould do you fine.\n\nAs to the Tempo/Duration parameter, leave it alone and just assume that 96\nticks-per-quarter-note is a universal constant, and you'll be happy.\n\n(You may wonder: Why 96? As far as I've worked out, all purmutations of the normal note lengths\n(whole, half, quarter, eighth, sixteenth, and even thirty-second notes) and tripletting,\ndotting, or double-dotting, times 96, all produce integers. For example, if a quarter note is 96\nticks, then a double-dotted thirty-second note is 21 ticks (i.e., 1.75 * 1/8 * 96). But that'd\nbe a messy 10.5 if there were only 48 ticks to a quarter note. Now, if you wanted a quintuplet\nanywhere, you'd be out of luck, since 96 isn't a factor of five. It's actually 3 * (2 5),\ni.e., three times two to the fifth. If you really need quintuplets, then you have my very\nspecial permission to mess with the Tempo attribute -- I suggest multiples of 96, e.g., 5 * 96.)\n\n(You may also have read in MIDI::Filespec that \"timesignature\" allows you to define an\narbitrary mapping of your concept of quarter note, to MIDI's concept of quarter note. For your\nsanity and mine, leave them the same, at a 1:1 mapping -- i.e., with an '8' for\n\"timesignature\"'s last parameter, for \"eight notated 32nd-notes per MIDI quarter note\". And\nthis is relevant only if you're calling \"timesignature\" anyway, which is not necessarily a\ngiven.)\n\nMORE ROUTINES\n$opus = writescore *filespec*\n$opus = $obj->writescore(*filespec*)\nWrites the score to the filespec (e.g, \"../../samples/funk2.midi\", or a variable containing\nthat value), with the score's Ticks as its tick parameters (AKA \"divisions\"). Among other\nthings, this function calls the function \"makeopus\", below, and if you capture the output\nof writescore, you'll get the opus created, if you want it for anything. (Also: you can\nalso use a filehandle-reference instead of the filespec: \"writescore *STDOUT{IO}\".)\n\nreadscore *filespec*\n$obj = MIDI::Simple->readscore('foo.mid'))\nIn the first case (a procedure call), does \"newscore\" to erase and initialize the object\nattributes (Score, Octave, etc), then reads from the file named. The file named has to be a\nMIDI file with exactly one eventful track, or Perl dies. And in the second case,\n\"readscore\" acts as a constructor method, returning a new object read from the file.\n\nScore, Ticks, and Time are all affected:\n\nScore is the event form of all the MIDI events in the MIDI file. (Note: *Seriously* deformed\nMIDI files may confuse the routine that turns MIDI events into a Score.)\n\nTicks is set from the ticks setting (AKA \"divisions\") of the file.\n\nTime is set to the end time of the latest event in the file.\n\n(Also: you can also use a filehandle-reference instead of the filespec: \"readscore\n*STDIN{IO}\".)\n\nIf ever you have to make a Score out of a single track from a *multitrack* file, read the\nfile into an $opus, and then consider something like:\n\nnewscore;\n$opus = MIDI::Opus->new({ 'fromfile' => \"foo2.mid\" });\n$track = ($opus->tracks)[2]; # get the third track\n\n($scorer, $endtime) =\nMIDI::Score::eventsrtoscorer($track->eventsr);\n\n$Ticks = $opus->ticks;\n@Score = @$scorer;\n$Time = $endtime;\n" }, { "name": "synch", "content": "$obj->synch( LIST of coderefs )\nLIST is a list of coderefs (whether as a series of anonymous subs, or as a list of items\nlike \"(\\&foo, \\&bar, \\&baz)\", or a mixture of both) that \"synch\" calls in order to add to\nthe given object -- which in the first form is the package's default object, and which in\nthe second case is $obj. What \"synch\" does is:\n\n* remember the initial value of Time, before calling any of the routines;\n\n* for each routine given, reset Time to what it was initially, call the routine, and then\nnote what the value of Time is, after each call;\n\n* then, after having called all of the routines, set Time to whatever was the greatest\n(equals latest) value of Time that resulted from any of the calls to the routines.\n\nThe coderefs are all called with one argument in @ -- the object they are supposed to\naffect. All these routines should/must therefore use method calls instead of procedure\ncalls. Here's an example usage of synch:\n\nmy $measure = 0;\nmy @phrases =(\n[ Cs, F, Ds, Gsd1 ], [Cs, Ds, F, Cs],\n[ F, Cs, Ds, Gsd1 ], [Gsd1, Ds, F, Cs]\n);\n\nfor(1 .. 20) { synch(\\&count, \\&lalala); }\n\nsub count {\nmy $it = $[0];\n$it->r(wn); # whole rest\n# not just \"r(wn)\" -- we want a method, not a procedure!\n++$measure;\n}\n\nsub lalala {\nmy $it = $[0];\n$it->noop(c1,mf,o3,qn); # setup\nmy $phrasenumber = ($measure + -1) % 4;\nmy @phrase = @{$phrases[$phrasenumber]};\nforeach my $note (@phrase) { $it->n($note); }\n}\n\n$opus = makeopus or $opus = $obj->makeopus\nMakes an opus (a MIDI::Opus object) out of Score, setting the opus's tick parameter (AKA\n\"divisions\") to $ticks. The opus is, incidentally, format 0, with one track.\n\ndumpscore or $obj->dumpscore\nDumps Score's contents, via \"print\" (so you can \"select()\" an output handle for it).\nCurrently this is in this somewhat uninspiring format:\n\n['note', 0, 96, 1, 25, 96],\n['note', 96, 96, 1, 29, 96],\n\nas it is (currently) just a call to &MIDI::Score::dumpscore; but in the future I may\n(should?) make it output in \"n\"/\"r\" notation. In the meantime I assume you'll use this, if\nat all, only for debugging purposes.\n\nFUNCTIONS\nThese are subroutines that aren't methods and don't affect anything (i.e., don't have \"side\neffects\") -- they just take input and/or give output.\n\ninterval LISTREF, LIST\nThis takes a reference to a list of integers, and a list of note-pitch specifications\n(whether relative or absolute), and returns a list consisting of the given note\nspecifications transposed by that many half-steps. E.g.,\n\n@majors = interval [0,4,7], C, Bflat3;\n\nwhich returns the list \"(C,E,G,Bf3,D4,F4)\".\n\nItems in LIST which aren't note specifications are passed thru unaltered.\n\nnotemap { BLOCK } LIST\nThis is pretty much based on (or at least inspired by) the normal Perl \"map\" function, altho\nthe syntax is a bit more restrictive (i.e., \"map\" can take the form \"map {BLOCK} LIST\" or\n\"map(EXPR,LIST)\" -- the latter won't work with \"notemap\").\n\n\"notemap {BLOCK} (LIST)\" evaluates the BLOCK for each element of LIST (locally setting $\nto each element's note-number value) and returns the list value composed of the results of\neach such evaluation. Evaluates BLOCK in a list context, so each element of LIST may produce\nzero, one, or more elements in the returned value. Moreover, besides setting $, \"notemap\"\nfeeds BLOCK (which it sees as an anonymous subroutine) three parameters, which BLOCK can\naccess in @ :\n\n$[0] : Same as $. I.e., The current note-specification,\nas a note number.\nThis is the result of having fed the original note spec\n(which you can see in $[2]) to isnotespec.\n\n$[1] : The absoluteness flag for this note, from the\nabove-mentioned call to isnotespec.\n0 = it was relative (like 'C')\n1 = it was absolute (whether as 'C4' or 'n41' or '41')\n\n$[2] : the actual note specification from LIST, if you want\nto access it for any reason.\n\nIncidentally, any items in LIST that aren't a note specification are passed thru unchanged\n-- BLOCK isn't called on it.\n\nSo, in other words, what \"notemap\" does, for each item in LIST, is:\n\n* It calls \"isnotespec\" on it to test whether it's a note specification at all. If it\nisn't, just passes it thru. If it is, then \"notemap\" stores the note number and the\nabsoluteness flag that \"isnotespec\" returned, and...\n\n* It calls BLOCK, providing the note number in $ and $[0], the absoluteness flag in $[1],\nand the original note specification in $[2]. Stores the return value of calling BLOCK (in a\nlist context of course) -- this should be a list of note numbers.\n\n* For each element of the return value (which is actually free to be an empty list),\nconverts it from a note number to whatever kind of specification the original note value\nwas. So, for each element, if the original was relative, \"notemap\" interprets the return\nvalue as a relative note number, and calls \"numbertorelative\" on it; if it was absolute,\n\"notemap\" will try to restore it to the correspondingly formatted absolute specification\ntype.\n\nAn example is, I hope, helpful:\n\nThis:\n\nnotemap { $ - 3, $ + 2 } qw(Cs3 n42 50 Bf)\n\nreturns this:\n\n('Bf2', 'Ef3', 'n39', 'n44', '47', '52', 'G', 'Cu1')\n\nOr, to line things up:\n\nCs3 n42 50 Bf\n| | | |\n/-----\\ /-----\\ /---\\ /----\\\nBf2 Ef3 n39 n44 47 52 G Cu1\n\nNow, of course, this is the same as what this:\n\ninterval [-3, 2], qw(Cs3 n42 50 Bf)\n\nreturns. This is fitting, as \"interval\", internally, is basically a simplified version of\n\"notemap\". But \"interval\" only lets you do unconditional transposition, whereas \"notemap\"\nlets you do anything at all. For example:\n\n@notespecs = notemap { $funkylookuptable{$} }\nC, Gf;\n\nor\n\n@notespecs = notemap { $ + int(rand(2)) }\n@stuff;\n\n\"notemap\", like \"map\", can seem confusing to beginning programmers (and many intermediate\nones, too), but it is quite powerful.\n\nnumbertoabsolute NUMBER\nThis returns the absolute note specification (in the form \"C5\") that the MIDI note number in\nNUMBER represents.\n\nThis is like looking up the note number in %MIDI::number2note -- not exactly the same, but\neffectively the same. See the source for more details.\n\nthe function numbertorelative NUMBER\nThis returns the relative note specification that NUMBER represents. The idea of a numerical\nrepresentation for \"relative\" note specifications was necessitated by \"interval\" and\n\"notemap\" -- since without this, you couldn't meaningfully say, for example, interval [0,2]\n'F'. This should illustrate the concept:\n\nnumbertorelative(-10) => \"Dd1\"\nnumbertorelative( -3) => \"Ad1\"\nnumbertorelative( 0) => \"C\"\nnumbertorelative( 5) => \"F\"\nnumbertorelative( 10) => \"Bf\"\nnumbertorelative( 19) => \"Gu1\"\nnumbertorelative( 40) => \"Eu3\"\n\nisnotespec STRING\nIf STRING is a note specification, \"isnotespec(STRING)\" returns a list of two elements:\nfirst, a flag of whether the note specification is absolute (flag value 1) or relative (flag\nvalue 0); and second, a note number corresponding to that note specification. If STRING is\nnot a note specification, \"isnotespec(STRING)\" returns an empty list (which in a boolean\ncontext is FALSE).\n\nImplementationally, \"isnotespec\" just uses \"isabsolutenotespec\" and\n\"isrelativenotespec\".\n\nExample usage:\n\n@notedetails = isnotespec($thing);\nif(@notedetails) {\n($absolutenessflag, $notenum) = @notedetails;\n...stuff...\n} else {\npush @otherstuff, $thing; # or whatever\n}\n\nisrelativenotespec STRING\nIf STRING is an relative note specification, returns the note number for that specification\nas a one-element list (which in a boolean context is TRUE). Returns empty-list (which in a\nboolean context is FALSE) if STRING is NOT a relative note specification.\n\nTo just get the boolean value:\n\nprint \"Snorf!\\n\" unless isrelativenotespec($note);\n\nBut to actually get the note value:\n\n($notenumber) = isrelativenotespec($note);\n\nOr consider this:\n\n@isrel = isrelativenotespec($note);\nif(@isrel) {\n$notenumber = $isrel[0];\n} else {\nprint \"Snorf!\\n\";\n}\n\n(Author's note, two years later: all this business of returning lists of various sizes, with\nthis and other functions in here, is basically a workaround for the fact that there's not\nreally any such thing as a boolean context in Perl -- at least, not as far as user-defined\nfunctions can see. I now think I should have done this with just returning a single scalar\nvalue: a number (which could be 0!) if the input is a number, and undef/emptylist\n(\"return;\") if not -- then, the user could test:\n\n# Hypothetical --\n# This function doesn't actually work this way:\nif(defined(my $noteval = isrelativenotespec($string))) {\n...do things with $noteval...\n} else {\nprint \"Hey, that's no note!\\n\";\n}\n\nHowever, I don't anticipate users actually using these messy functions often at all -- I\nbasically wrote these for internal use by MIDI::Simple, then I documented them on the off\nchance they *might* be of use to anyone else.)\n\nisabsolutenotespec STRING\nJust like \"isrelativenotespec\", but for absolute note specifications instead of relative\nones.\n\nSelf() or $obj->Self();\nPresumably the second syntax is useless -- it just returns $obj. But the first syntax\nreturns the current package's default object.\n\nSuppose you write a routine, \"funkify\", that does something-or-other to a given MIDI::Simple\nobject. You could write it so that acts on the current package's default object, which is\nfine -- but, among other things, that means you can't call \"funkify\" from a sub you have\n\"synch\" call, since such routines should/must use only method calls. So let's say that,\ninstead, you write \"funkify\" so that the first argument to it is the object to act on. If\nthe MIDI::Simple object you want it to act on is it $sonata, you just say\n\nfunkify($sonata)\n\nHowever, if you want it to act on the current package's default MIDI::Simple object, what to\nsay? Simply,\n\n$packageopus = Self;\nfunkify($packageopus);\n" } ] }, "COPYRIGHT": { "content": "Copyright (c) 1998-2005 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\"\n", "subsections": [] } } } }