/usr/share/doc/libtse3-dev/Playable.html is in libtse3-dev 0.3.1-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <html>
<head>
<title>MIDI data and the Playable Interface</title>
</head>
<body bgcolor=#ffffff text=#000000>
<table width=100% cellspacing=0 cellpadding=1 border=0 bgcolor=#000000><tr><td>
<table width=100% cellspacing=0 cellpadding=1 border=0><tr><td valign=center bgcolor=#c8d559>
<table width=100% cellspacing=0 cellpadding=0 border=0><tr>
<td align=left width=30%><b> TSE3 documentation<b></td>
<td align=center width=30%>Version 0.3.1</td>
<td align=right width=30%>
<a href="index.html"><b>Index</b></a>
<a href="api/index.html">API</a>
<a href="Version.html">Version</a>
<a href="Structure.html">Structure</a>
</td>
</tr></table>
</td></tr></table>
</td></tr></table>
<h1>MIDI data and the Playable interface</h1>
<h3>MIDI data handling in TSE3</h3>
<p>
The TSE3 library has a single header file providing definitions for the
elements of the standard MIDI specification. This is the file
<code>Midi.h</code> (see the reference at the bottom of this page).
<p>
It defines the following elements:
<dl>
<dt><b>The <code>Clock</code> data value type.</b></dt>
<dd>Describes a time value in a song, as a number of <i>ticks</i>.
These ticks are in units of a pulse. There is a fixed number of
<i>pulses per quarter note</i> (PPQN) defined in
<code>Clock::PPQN</code>. (A <i>quarter note</i> is another
name for a crotchet.)</dd>
<dt><b>The <code>Event</code> template data value type.</b></dt>
<dd>Provides a standard way to generate object which associate a
data value (for example, a tempo change) with a time in
<code>Clock</code>s.</dd>
<dt><b>The <code>MidiCommands</code> and other similar
definitions.</b></dt>
<dd>Definitions of all the MIDI status bytes (e.g.
<code>MidiCommand_NoteOn</code>, system commands, controller
values etc. These are: <code>MidiCommands</code>,
<code>MidiSystemCommands</code>, and <code>MidiControlChanges</code>.
</dd>
<dt><b>The <code>MidiCommand</code> data value class.</b></dt>
<dd>This is the basic value type used to describe a single MIDI
command, including it's statub byte, channel and port pair (which
describe where the MIDI command should be sent), and any data bytes.
</dd>
<dt><b>The <code>MidiEvent</code> data value class.</b></dt>
<dd>This is built upon the <code>MidiCommand</code> class, but associates
it with an event time in <code>Clock<code>s.<br>
Note that here we <i>do not</i> use the <code>Event</code> template
class as a definition. This is because the <code>MidiEvent</code>
contains a second <code>MidiCommand</code>, used if the first is a
<code>MidiCommand_NoteOn</code>. If so, the second command holds the
related <code>MidiCommand_NoteOff</code> event. This can be used by
the TSE3 library to ensure that all MIDI note off events are sent for
any scheduled note on event.
</dd>
<dt><b>The <code>TSE3MetaMidiCommand</code> definitions.</b></dt>
<dd>These are a number of extension status bytes only understood by
the TSE3 library which are used internally.</dd>
</dl>
<p>
Used together, these definitions describe standard MIDI data, scheduled
to some clock source. The TSE3 song components generate musical data
in this format.
<p>
The <a href="KDOC.html">kdoc documentation</a> describes these classes.
You can find further information about them there.
<h3>The playable interface</h3>
<p>
Each component that comprises a Song can produce some sort of stream of
MIDI data that needs to be scheduled to a timed output. To simplify this
process they implement the <b><code>Playable</code></b> interface. This
makes the Song structure use a form of the <i>composite</i> design pattern
(GoF book).
<p>
The <code>Playable</code? meerly defines one method, creating for the
client a <b><code>PlayableIterator</code></b> that can iterate over the
MIDI data in the output stream. This is a form of the <i>iterator</i>
design pattern.
<p>
Each different kind of <code>Playable</code> object provides it's own
implementation of the <code>PlayableIterator</code> interface that knows
how to generate the MIDI events.
<p>
The user can ignore the individual song components <code>Playable</code>
interface, and meerly use the <code>Song</code>'s
<code>PlayableIterator</code> that will in turn use the
<code>Playable</code> iterators of all sub components to create a MIDI data
stream for the whole song.
<pre><b>
+------------\ +------------+ creates +--------------------+
| Interface |_\ | Playable |--------------| PlayableIterator |
| | +------------+ +--------------------+
+------------- + ^ ^
| |
+------------\ | |
| Example |_\ +------------+ +--------------------+
| Implemenation | | Song | | SongIterator |
+---------------+ +------------+ +--------------------+
</b></pre>
<p>
The data generated by a <code>PlayableIterator</code> object is in the form
described above, as defined by the <code>Midi.h</code> header file.
<h3>Streaming system exclusive MIDI data</h3>
<p>
System exclusive MIDI data is a particular nuisance. All sequencer
systems have this problem. If you don't care about, or know about
system exclusive MIDI data (or <i>sysex</i> data) then you can skip
this section.
<p>
Any other form of MIDI data, for example <code>MidiCommand_NoteOn</code>
events and the like, can be interspersed in any order. They are sent
in whole atomic units (the <code>MidiEvent</code> or
<code>MidiCommand</code> classes). They are easy to handle and stream around
the system in <code>PlaybaleIterator</code> objects.
<p>
However, sysex events break this simple atomic data structure. They
can be of arbitrary size, with a single start of sysex system byte at the
start, and an end of sysex status byte at the end.
<p>
So how do we stream these around using the <code>PlayableIterator</code>
class? <i>Carefully</i>, is the answer.
<p>
Sysex data has been designed to fit into the <code>Playable</code>
architecture rather than be handled as a special case. However, there are
certain restrictions involved in their use.
<p>
The start of a sysex block is naturally defined by a
<code>MidiCommand</code> with
<code>MidiComand_System</code> status byte and reason code
<code>MidiSystem_SysExStart</code>. The <code>data1</code> byte contains
the first data byte. <code>data2</code> is not used. If the event
is held in a <code>MidiEvent</code> (rather than a single
<code>MidiCommand</code> - this will be true if it is streamed from a
<code>PlayableIterator</code>) then the second (note off) field is not
used to hold extra values.
<p>
The next <code>MidiCommand</code> may need to be another sysex data byte. In
this case the same status information is put in the <code>MidiComand</code>
- although the playing
<code>MidiScheduler</code> object knows not to send this again.
<code>data1</code> contains this next data byte. More sysex data bytes
may follow.
<p>
The stream carries on in this manner until the end of the sysex data block,
when a <code>MidiComand</code> containing the
<code>MidiSystem_SysExEnd</code> status information is put in the stream.
<p>
As stated above, sysex data cannot be rearranged. Nor can other MIDI
events occur in the middle of them (you cannot shove a note on in the
middle of a block of sysex). For this reason any
<code>PlayableIterator</code> must take care to give each sysex
<code>MidiCommand</code>
<i>exactly the same</i> clock time to ensure no other events can get into
the middle of the sysex stream.
<p>
The standard TSE3 <code>PlayableIterator</code> objects are designed in
such a way that if all events have the same event time, events from
other sources will not interrupt the stream.
<h3>See also</h3>
<ul>
<li><a href="api/Midi_h.html"><code>Midi.h</code></a> for
descriptions of the TSE3 representation of MIDI data.
<li><a href="api/Playable_h.html"><code>Playable.h</code></a> for
the definition of the <code>Playable</code> class.
</ul>
<body bgcolor=#ffffff text=#000000>
<table width=100% cellspacing=0 cellpadding=1 border=0 bgcolor=#000000><tr><td>
<table width=100% cellspacing=0 cellpadding=1 border=0><tr><td valign=center bgcolor=#c8d559>
<table width=100% cellspacing=0 cellpadding=0 border=0><tr>
<td align=left width=30%> © Pete Goodliffe, 2001-2003</td>
<td align=center width=30%><a href="Copyright.html">Copyright</a></td>
<td align=right width=30%><a href="Psalm150.html">Psalm 150</a> </td>
</tr></table>
</td></tr></table>
</td></tr></table>
</body>
</html>
|