-
Notifications
You must be signed in to change notification settings - Fork 0
/
documentation.htm
executable file
·431 lines (350 loc) · 17.4 KB
/
documentation.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
<!-- last changes: 26.04.2005 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>PHP MIDI CLASS</title>
<link rel="stylesheet" type="text/css" href="css/midi.css" />
</head>
<body>
<div>
<h1>PHP MIDI CLASS</h1>
<h2>METHOD OVERVIEW</h2>
<a href="#addMsg">addMsg()</a><br />
<a href="#deleteMsg">deleteMsg()</a><br />
<a href="#deleteTrack">deleteTrack()</a><br />
<a href="#downloadMidFile">downloadMidFile()</a><br />
<a href="#getBpm">getBpm()</a><br />
<a href="#getDrumkitList">getDrumkitList()</a><br />
<a href="#getDrumset">getDrumset()</a><br />
<a href="#getInstrumentList">getInstrumentList()</a><br />
<a href="#getMid">getMid()</a><br />
<a href="#getMsg">getMsg()</a><br />
<a href="#getMsgCount">getMsgCount()</a><br />
<a href="#getNoteList">getNoteList()</a><br />
<a href="#getTempo">getTempo()</a><br />
<a href="#getTimebase">getTimebase()</a><br />
<a href="#getTrack">getTrack()</a><br />
<a href="#getTrackCount">getTrackCount()</a><br />
<a href="#getTrackTxt">getTrackTxt()</a><br />
<a href="#getTxt">getTxt()</a><br />
<a href="#getXml">getXml()</a><br />
<a href="#importMid">importMid()</a><br />
<a href="#importTrackTxt">importTrackTxt()</a><br />
<a href="#importTxt">importTxt()</a><br />
<a href="#importXml">importXml()</a><br />
<a href="#insertMsg">insertMsg()</a><br />
<a href="#newTrack">newTrack()</a><br />
<a href="#open">open()</a><br />
<a href="#playMidFile">playMidFile()</a><br />
<a href="#saveMidFile">saveMidFile()</a><br />
<a href="#setBpm">setBpm()</a><br />
<a href="#setTempo">setTempo()</a><br />
<a href="#setTimebase">setTimebase()</a><br />
<a href="#soloTrack">soloTrack()</a><br />
<a href="#transpose">transpose()</a><br />
<a href="#transposeTrack">transposeTrack()</a><br />
<br />
<b>RTTL Class (entension/child class)</b><br />
<a href="#getRttl">getRttl()</a><br />
<a href="#importRttl">importRttl()</a><br />
<h2>METHODS IN DETAIL</h2>
<h3>Binary Input</h3>
<a name="importMid"></a><span class="func">importMid($smf_path [, $tn])</span><br />
imports standard MIDI file (SMF, *.mid) or RMID files (*.rmi) of type 0 or 1. If optional 2. parameter $tn is set, only track number $tn is imported (similar effect as soloTrack(), but much faster, as only one track is parsed).
<br /><br />
Example:<br />
<span class="sample">$midi->importMid('music/song1.mid');</span>
<h3>Text Input</h3>
<a name="importTxt"></a><span class="func">importTxt($txt)</span><br />
imports MIDI song in <a href="#mf2t">MF2T/T2MF</a> ASCII format (e.g. fetched from database). If a line "TimestampType=Delta" is found at the beginning of a track (next line after "MTrk"), all timestamps of this track are interpreted as relative (delta) values, otherwise as absolute values.
<br /><br />
Notice:<br />
Relative timestamps and the "TimestampType=Delta" are not compatible with the original MF2T/T2MF format!
<br /><br />
Example:<br />
<span class="sample">$midi->importTxt($txt);</span>
<br /><br /><br />
<a name="importTrackTxt"></a><span class="func">importTrackTxt($txt [, $tn])</span><br />
imports MIDI track in <a href="#mf2t">MF2T/T2MF</a> format. If optional track number $tn is specified, track $tn is replaced, otherwise new track is appended. If a line "TimestampType=Delta" is found at the beginning of the track (next line after "MTrk"), all timestamps of this track are interpreted as relative (delta) values, otherwise as absolute values.
<br /><br />
Notice:<br />
Relative timestamps and the "TimestampType=Delta" are not compatible with the original MF2T/T2MF format!
<br /><br />
Example:<br />
<span class="sample">$midi->importTrackTxt($txt, 2);</span>
<h3>XML Input</h3>
<a name="importXml"></a><span class="func">importXML($txt)</span><br />
imports MIDI song in <a href="#xml">MIDI XML</a> format
<br /><br />
Example:<br />
<span class="sample">$midi->importXML($xmlStr);</span>
<h3>Binary Output</h3>
<a name="getMid"></a><span class="func">getMid()</span><br />
returns MIDI song as binary MIDI string (SMF).
<br /><br />
Example:<br />
<span class="sample">$smf = $midi->getMid();</span>
<br /><br /><br />
<a name="saveMidFile"></a><span class="func">saveMidFile($mid_path)</span><br />
saves MIDI song as standard MIDI file (SMF).
<br /><br />
Example:<br />
<span class="sample">$midi->saveMidFile('/tmp/song1.mid');</span>
<br /><br /><br />
<a name="playMidFile"></a><span class="func">playMidFile($file [,$visible=true,$autostart=true,$loop=true,$player='default'])</span><br />
embeds MIDI file in web page. Optional boolean parameters for visibility, autostart and looping. Optional parameter $player determines preferred plugin, it must correspond to a player-template in folder 'player'. By default the following templates are available: default, quicktime, windowsmedia, crescendo, beatnik, bgsound.
<br /><br />
Examples:<br />
<span class="sample">$midi->playMidFile($file);</span><br />
<span class="sample">$midi->playMidFile($file,0,1,0,'quicktime');</span>
<br /><br /><br />
<a name="downloadMidFile"></a><span class="func">downloadMidFile($output [,$file])</span><br />
if parameter $file is specified, starts download of file $file, otherwise the current midi song is downloaded from memory. $output is the proposed filename for saving.
<br /><br />
Example:<br />
<span class="sample">$midi->downloadMidFile('song1.mid', '/tmp/~tmp1.mid');</span>
<h3>Text Output</h3>
<a name="getTxt"></a><span class="func">getTxt([$ttype=0])</span><br />
returns MIDI song in <a href="#mf2t">MF2T/T2MF</a> format (e.g. to save to database). Optional Parameter $ttype determines timestamp type, if $ttype==0 (or omitted), the timestamps are absolute values and the result is compatible to the original MF2T/T2MF format, if $ttype==1, timestamps are relative values (not compatible to original MF2T/T2MF format):
<br /><br />
Notice:<br />
As messages are internally stored with absolute timestamps, getTxt() is much faster than getTxt(1);
<br /><br />
Example:<br />
<span class="sample">$str = $midi->getTxt();</span>
<br /><br /><br />
<a name="getTrackTxt"></a><span class="func">getTrackTxt($tn[,$ttype=0])</span><br />
returns track number $tn in <a href="#mf2t">MF2T/T2MF</a> format. For optional parameter $ttype see <a href="#getTxt">getTxt()</a>.
<br /><br />
Example:<br />
<span class="sample">$str = $midi->getTrackTxt(2,1);</span>
<h3>XML Output</h3>
<a name="getXml"></a><span class="func">getXml([$ttype=0])</span><br />
returns MIDI song as <a href="#xml">MIDI XML</a>. Optional Parameter $ttype determines timestamp type, if $ttype==0 (or omitted), the timestamps are absolute values, if $ttype==1 timestamps are relative (delta) values. The output is valid XML according to the MIDI XML standard v0.9 by <a href="http://www.recordare.com/dtds/midixml.html">MusicXML/Recordare</a>.
<br /><br />
Notice:<br />
As messages are internally stored with absolute timestamps, getXml() is much faster than getXml(1);
<br /><br />
Example:<br />
<span class="sample">$xmlStr = $midi->getXml();</span>
<h3>Info</h3>
<a name="getTempo"></a><span class="func">getTempo()</span><br />
returns MIDI tempo value (0 if not set).
<br /><br /><br />
<a name="getBpm"></a><span class="func">getBpm()</span><br />
returns tempo as beats per minute (0 if tempo not set).
<br /><br /><br />
<a name="getTimebase"></a><span class="func">getTimebase()</span><br />
returns timebase value.
<br /><br /><br />
<a name="getTrackCount"></a><span class="func">getTrackCount()</span><br />
returns number of tracks.
<br /><br /><br />
<a name="getTrack"></a><span class="func">getTrack($tn)</span><br />
returns track number $tn as array of msg strings in <a href="#mf2t">MF2T/T2MF</a> format.
<br /><br />
Example:<br />
<span class="sample">$track = $midi->getTrack(2);</span>
<br /><br /><br />
<a name="getMsgCount"></a><span class="func">getMsgCount()</span><br />
returns number of messages of track number $tn.
<br /><br />
Example:<br />
<span class="sample">$msgCnt = $midi->getMsgCount(2);</span>
<br /><br /><br />
<a name="getMsg"></a><span class="func">getMsg($tn,$mn)</span><br />
returns message string number $mn of track number $tn. The message string is in <a href="#mf2t">MF2T/T2MF</a> format.
<br /><br />
Example:<br />
<span class="sample">$msgStr = $midi->getMsg(2, 23);</span>
<h3>Generation/Manipulation</h3>
<a name="open"></a><span class="func">open([$timebase=480])</span><br />
creates(resets) new empty MIDI song for further processing (eg. with newTrack() and addMsg()). Optional parameter $timebase to set its timebase (default = 480).
<br /><br />
Example:<br />
<span class="sample">$midi->open(240);</span>
<br /><br /><br />
<a name="newTrack"></a><span class="func">newTrack()</span><br />
adds new empty track, returns its track number.
<br /><br />
Example:<br />
<span class="sample">$newTrck = $midi->newTrack();</span>
<br /><br /><br />
<a name="addMsg"></a><span class="func">addMsg($tn, $msgStr[, $ttype=0])</span><br />
appends message string $msgStr to end of track $tn. If $ttype==0 or omitted, timestamp is interpreted as absolute value, if $ttype==1, it's interpreted as relative (delta) value. The message string has to be in <a href="#mf2t">MF2T/T2MF</a> format.
<br /><br />
Notice:<br />
addMsg() is faster then insertMsg(), but it does not check for correct position according to time.
<br /><br />
Example:<br />
<span class="sample">$midi->addMsg(1, "4800 On ch=1 n=66 v=80");</span>
<br /><br /><br />
<a name="insertMsg"></a><span class="func">insertMsg($tn,$msgStr)</span><br />
adds message at adequate position of track number $tn (slower than addMsg).<br />
If other messages with same time are found, new message is inserted before
those. The message string has to be in <a href="#mf2t">MF2T/T2MF</a> format.
<br /><br />
Example:<br />
<span class="sample">$midi->insertMsg(0, "0 Meta Text \"created by fluxus\"");</span>
<br /><br /><br />
<a name="deleteMsg"></a><span class="func">deleteMsg($tn,$mn)</span><br />
deletes message $mn of track $tn.
<br /><br /><br />
<a name="setBpm"></a><span class="func">setBpm($bpm)</span><br />
sets tempo corresponding to given beats per minute $bpm.
<br /><br /><br />
<a name="setTempo"></a><span class="func">setTempo($tempo)</span><br />
sets tempo by replacing set tempo msg in track 0 (or adding new track 0).
<br /><br /><br />
<a name="setTimebase"></a><span class="func">setTimebase($tb)</span><br />
sets timebase
<br /><br /><br />
<a name="deleteTrack"></a><span class="func">deleteTrack($tn)</span><br />
deletes track number $tn.
<br /><br /><br />
<a name="soloTrack"></a><span class="func">soloTrack($tn)</span><br />
deletes all tracks except track number $tn (and $track 0 which contains tempo info).
<br /><br /><br />
<a name="transpose"></a><span class="func">transpose($dn)</span><br />
transposes song by $dn (positive or negative) half tone steps.
<br /><br />
Example:<br />
<span class="sample">$midi->transpose(12); // 1 octave up</span>
<br /><br /><br />
<a name="transposeTrack"></a><span class="func">transposeTrack($tn, $dn)</span><br />
transposes all notes of track number $tn by $dn (positive or negative) half tone steps.
<br /><br />
Example:<br />
<span class="sample">$midi->transposeTrack(1, -12); // 1 octave down</span>
<h3>Utilities</h3>
<a name="getDrumkitList"></a><span class="func">getDrumkitList()</span><br />
returns list of standard gm drum kit names (associative array, key=number, value=name).
<br /><br /><br />
<a name="getDrumset"></a><span class="func">getDrumset()</span><br />
returns list of gm drumset instrument names (associative array, key=number, value=name).
<br /><br /><br />
<a name="getInstrumentList"></a><span class="func">getInstrumentList()</span><br />
returns list of standard instrument names.
<br /><br /><br />
<a name="getNoteList"></a><span class="func">getNoteList()</span><br />
returns list of note names ('C0',...).
<h3>RTTL Extension</h3>
<a name="getRttl"></a><span class="func">getRttl([$title='', $tn=-1]])</span><br />
returns RTTL ringtone as string. If optional parameter $title is specified, this will be the RTTL name (max. 10 characters), if it's "" or omitted, the method looks for a TrkName meta event, and if there is none, name will be "mid2rttl". The optional parameter $tn determines the tracknumber that will be used, if it's <0 or omitted, the first track that contains note events will be used.
<br /><br />
Example:<br />
<span class="sample">$rttlStr = $rttl->getRttl();</span>
<br /><br /><br />
<a name="importRttl"></a><span class="func">importRttl($rttlStr)</span><br />
imports a RTTL ringtone as string (creates a new midi song of type 0).
<br /><br />
Example:<br />
<span class="sample">$rttl->importRttl($rttlStr);</span>
<br /><br />
<h2><a name="mf2t"></a>MF2T/T2MF text format</h2>
excerpt of readme.txt in <a href="ftp://ftp.cs.ruu.nl/pub/MIDI/PROGRAMS/MSDOS/mf2t.zip">mf2t.zip</a>
<pre>
Format of the textfile:
-----------------------
File header: Mfile <format> <ntrks> <division>
Start of track: MTrk
End of track: TrkEnd
Note On: On <ch> <note> <vol>
Note Off: Off <ch> <note> <vol>
Poly Pressure: PoPr[PolyPr] <ch> <note> <val>
Channel Pressure: ChPr[ChanPr] <ch> <val>
Controller
parameter: Par[Param] <ch> <con> <val>
Pitch bend: Pb <ch> <val>
Program change: PrCh[ProgCh] <ch> <prog>
Sysex message: SysEx <hex>
Sequence nr: Seqnr <num>
Key signature: KeySig <num> <manor>
Tempo: Tempo <num>
Time signature: TimeSig <num>/<num> <num> <num>
SMPTE event: SMPTE <num> <num> <num> <num> <num>
Meta text events: Meta <texttype> <string>
Meta end of track: Meta TrkEnd
Sequencer specific: SeqSpec <type> <hex>
Misc meta events: Meta <type> <hex>
The <> have the following meaning:
<ch> ch=<num>
<note> n=<noteval> [note=<noteval>]
<vol> v=<num> [vol=<num>]
<val> v=<num> [val=<num>]
<con> c=<num> [con=<num>]
<prog> p=<num> [prog=<num>]
<manor> minor or major
<noteval> either a <num> or A-G optionally followed by #,
followed by <num> without intermediate spaces.
<texttype> Text Copyright SeqName TrkName InstrName Lyric Marker Cue or <type>
<type> a hex number of the form 0xab
<hex> a sequence of 2-digit hex numbers (without 0x) separated by space
<string> a string between double quotes (like "text").
Channel numbers are 1-based, all other numbers are as they appear in the midifile.
<division> is either a positive number (giving the time resolution in
clicks per quarter note) or a negative number followed by a positive
number (giving SMPTE timing).
<format> <ntrks> <num> are decimal numbers.
The <num> in the Pb is the real value (two midibytes combined).
In Tempo it is a long (32 bits) value. Others are in the interval 0-127.
The SysEx sequence contains the leading F0 and the trailing F7.
</pre>
<h2><a name="xml"></a>MIDI XML format</h2>
(for details see Standard MIDI File DTD by <a href="http://www.recordare.com/dtds/midixml.html">Recordare</a>)
<br /><br />
<b>Supported elements:</b>
<pre>
<MIDIFile>...</MIDIFile>
<Format>...</Format>
<TrackCount>...</TrackCount>
<TicksPerBeat>...</TicksPerBeat>
<TimestampType>...</TimestampType>
</pre>
<b>Supported events:</b>
<pre>
<ProgramChange Channel="..." Number="..."/>
<NoteOn Channel="..." Note="..." Velocity="..."/>
<NoteOff Channel="..." Note="..." Velocity="..."/>
<PolyKeyPressure Channel="..." Note="..." Pressure="..."/>
<ControlChange Channel="..." Control="..." Value="..."/>
<ChannelKeyPressure Channel="..." Pressure="..."/>
<PitchBendChange Channel="..." Value="..."/>
<SequenceNumber Value="..."/>
<TextEvent>...</TextEvent>
<CopyrightNotice>...</CopyrightNotice>
<TrackName>...</TrackName>
<InstrumentName>...</InstrumentName>
<Lyric>...</Lyric>
<Marker>...</Marker>
<CuePoint>...</CuePoint>
<EndOfTrack/>
<MIDIChannelPrefix Value="..."/>
<SetTempo Value="..."/>
<SMPTEOffset TimeCodeType="1" Hour="..." Minute="..." Second="..." Frame="..." FractionalFrame="..."></SMPTEOffset>
<TimeSignature Numerator="..." LogDenominator="..." MIDIClocksPerMetronomeClick="..." ThirtySecondsPer24Clocks="..."/>
<KeySignature Fifths="..." Mode="..."/>
<SequencerSpecific>...</SequencerSpecific>
<SystemExclusive>...</SystemExclusive>
</pre>
<b>Not (yet) supported elements:</b>
<pre>
<!-- for SMPTE time codes -->
<FrameRate>...</FrameRate>
<TicksPerFrame>...<TicksPerFrame>
</pre>
<b>Not (yet) supported events:</b>
<pre>
<EndOfExclusive>...</EndOfExclusive>
<ProgramName>...</ProgramName>
<DeviceName>...</DeviceName>
<XMFPatchTypePrefix Value="..."/>
<Port Value="..."/>
<OtherMetaEvent Number="...">...</OtherMetaEvent>
</pre>
<br /><br /><br /><br /><br /><br />
</div>
</body>
</html>