1<html xmlns:v="urn:schemas-microsoft-com:vml" 2xmlns:o="urn:schemas-microsoft-com:office:office" 3xmlns:w="urn:schemas-microsoft-com:office:word" 4xmlns:st1="urn:schemas-microsoft-com:office:smarttags" 5xmlns="http://www.w3.org/TR/REC-html40"> 6 7<head> 8<meta http-equiv=Content-Type content="text/html; charset=windows-1252"> 9<meta name=ProgId content=Word.Document> 10<meta name=Generator content="Microsoft Word 11"> 11<meta name=Originator content="Microsoft Word 11"> 12<link rel=File-List href="JET_Programming_Manual_files/filelist.xml"> 13<link rel=Edit-Time-Data href="JET_Programming_Manual_files/editdata.mso"> 14<link rel=OLE-Object-Data href="JET_Programming_Manual_files/oledata.mso"> 15<!--[if !mso]> 16<style> 17v\:* {behavior:url(#default#VML);} 18o\:* {behavior:url(#default#VML);} 19w\:* {behavior:url(#default#VML);} 20.shape {behavior:url(#default#VML);} 21</style> 22<![endif]--> 23<title>JET PROGRAMMING MANUAL</title> 24<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" 25 name="place"/> 26<!--[if gte mso 9]><xml> 27 <o:DocumentProperties> 28 <o:Author>Dave Sparks</o:Author> 29 <o:Template>SONiVOX Technical Note.dot</o:Template> 30 <o:LastAuthor>Jennifer Hruska</o:LastAuthor> 31 <o:Revision>5</o:Revision> 32 <o:TotalTime>34</o:TotalTime> 33 <o:LastPrinted>2006-06-30T19:06:00Z</o:LastPrinted> 34 <o:Created>2009-03-13T18:45:00Z</o:Created> 35 <o:LastSaved>2009-03-19T14:20:00Z</o:LastSaved> 36 <o:Pages>1</o:Pages> 37 <o:Words>3887</o:Words> 38 <o:Characters>22157</o:Characters> 39 <o:Company> </o:Company> 40 <o:Lines>184</o:Lines> 41 <o:Paragraphs>51</o:Paragraphs> 42 <o:CharactersWithSpaces>25993</o:CharactersWithSpaces> 43 <o:Version>11.9999</o:Version> 44 </o:DocumentProperties> 45 <o:OfficeDocumentSettings> 46 <o:AllowPNG/> 47 </o:OfficeDocumentSettings> 48</xml><![endif]--><!--[if gte mso 9]><xml> 49 <w:WordDocument> 50 <w:DrawingGridHorizontalSpacing>6 pt</w:DrawingGridHorizontalSpacing> 51 <w:DrawingGridVerticalSpacing>8.15 pt</w:DrawingGridVerticalSpacing> 52 <w:DisplayHorizontalDrawingGridEvery>2</w:DisplayHorizontalDrawingGridEvery> 53 <w:DisplayVerticalDrawingGridEvery>2</w:DisplayVerticalDrawingGridEvery> 54 <w:ValidateAgainstSchemas/> 55 <w:SaveIfXMLInvalid>false</w:SaveIfXMLInvalid> 56 <w:IgnoreMixedContent>false</w:IgnoreMixedContent> 57 <w:AlwaysShowPlaceholderText>false</w:AlwaysShowPlaceholderText> 58 <w:Compatibility> 59 <w:BreakWrappedTables/> 60 <w:SnapToGridInCell/> 61 <w:WrapTextWithPunct/> 62 <w:UseAsianBreakRules/> 63 <w:UseWord2002TableStyleRules/> 64 </w:Compatibility> 65 <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel> 66 </w:WordDocument> 67</xml><![endif]--><!--[if gte mso 9]><xml> 68 <w:LatentStyles DefLockedState="false" LatentStyleCount="156"> 69 </w:LatentStyles> 70</xml><![endif]--><!--[if !mso]><object 71 classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object> 72<style> 73st1\:*{behavior:url(#ieooui) } 74</style> 75<![endif]--> 76<style> 77<!-- 78 /* Font Definitions */ 79 @font-face 80 {font-family:Tahoma; 81 panose-1:2 11 6 4 3 5 4 4 2 4; 82 mso-font-charset:0; 83 mso-generic-font-family:swiss; 84 mso-font-pitch:variable; 85 mso-font-signature:1627421319 -2147483648 8 0 66047 0;} 86 /* Style Definitions */ 87 p.MsoNormal, li.MsoNormal, div.MsoNormal 88 {mso-style-parent:""; 89 margin:0in; 90 margin-bottom:.0001pt; 91 mso-pagination:widow-orphan; 92 font-size:12.0pt; 93 font-family:Arial; 94 mso-fareast-font-family:"Times New Roman"; 95 mso-bidi-font-family:"Times New Roman";} 96h1 97 {mso-style-next:Normal; 98 margin-top:12.0pt; 99 margin-right:0in; 100 margin-bottom:3.0pt; 101 margin-left:0in; 102 text-align:center; 103 mso-pagination:widow-orphan; 104 page-break-after:avoid; 105 mso-outline-level:1; 106 font-size:16.0pt; 107 font-family:Arial; 108 mso-font-kerning:16.0pt;} 109h2 110 {mso-style-link:"Heading 2 Char"; 111 mso-style-next:Normal; 112 margin-top:12.0pt; 113 margin-right:0in; 114 margin-bottom:3.0pt; 115 margin-left:0in; 116 mso-pagination:widow-orphan; 117 page-break-after:avoid; 118 mso-outline-level:2; 119 font-size:14.0pt; 120 font-family:Arial; 121 font-style:italic;} 122h3 123 {mso-style-next:Normal; 124 margin-top:12.0pt; 125 margin-right:0in; 126 margin-bottom:3.0pt; 127 margin-left:0in; 128 mso-pagination:widow-orphan; 129 page-break-after:avoid; 130 mso-outline-level:3; 131 font-size:13.0pt; 132 font-family:Arial;} 133h4 134 {mso-style-next:Normal; 135 margin-top:12.0pt; 136 margin-right:0in; 137 margin-bottom:3.0pt; 138 margin-left:0in; 139 mso-pagination:widow-orphan; 140 page-break-after:avoid; 141 mso-outline-level:4; 142 font-size:12.0pt; 143 mso-bidi-font-size:14.0pt; 144 font-family:Arial; 145 mso-bidi-font-family:"Times New Roman"; 146 font-style:italic; 147 mso-bidi-font-style:normal;} 148p.MsoToc1, li.MsoToc1, div.MsoToc1 149 {mso-style-update:auto; 150 mso-style-noshow:yes; 151 mso-style-next:Normal; 152 margin:0in; 153 margin-bottom:.0001pt; 154 mso-pagination:widow-orphan; 155 font-size:12.0pt; 156 font-family:Arial; 157 mso-fareast-font-family:"Times New Roman"; 158 mso-bidi-font-family:"Times New Roman";} 159p.MsoToc2, li.MsoToc2, div.MsoToc2 160 {mso-style-update:auto; 161 mso-style-noshow:yes; 162 mso-style-next:Normal; 163 margin-top:0in; 164 margin-right:0in; 165 margin-bottom:0in; 166 margin-left:12.0pt; 167 margin-bottom:.0001pt; 168 mso-pagination:widow-orphan; 169 font-size:12.0pt; 170 font-family:Arial; 171 mso-fareast-font-family:"Times New Roman"; 172 mso-bidi-font-family:"Times New Roman";} 173p.MsoToc3, li.MsoToc3, div.MsoToc3 174 {mso-style-update:auto; 175 mso-style-noshow:yes; 176 mso-style-next:Normal; 177 margin-top:0in; 178 margin-right:0in; 179 margin-bottom:0in; 180 margin-left:24.0pt; 181 margin-bottom:.0001pt; 182 mso-pagination:widow-orphan; 183 font-size:12.0pt; 184 font-family:Arial; 185 mso-fareast-font-family:"Times New Roman"; 186 mso-bidi-font-family:"Times New Roman";} 187p.MsoToc4, li.MsoToc4, div.MsoToc4 188 {mso-style-update:auto; 189 mso-style-noshow:yes; 190 mso-style-next:Normal; 191 margin-top:0in; 192 margin-right:0in; 193 margin-bottom:0in; 194 margin-left:.5in; 195 margin-bottom:.0001pt; 196 mso-pagination:widow-orphan; 197 font-size:12.0pt; 198 font-family:Arial; 199 mso-fareast-font-family:"Times New Roman"; 200 mso-bidi-font-family:"Times New Roman";} 201p.MsoCommentText, li.MsoCommentText, div.MsoCommentText 202 {mso-style-noshow:yes; 203 margin:0in; 204 margin-bottom:.0001pt; 205 mso-pagination:widow-orphan; 206 font-size:10.0pt; 207 font-family:Arial; 208 mso-fareast-font-family:"Times New Roman"; 209 mso-bidi-font-family:"Times New Roman";} 210p.MsoHeader, li.MsoHeader, div.MsoHeader 211 {margin:0in; 212 margin-bottom:.0001pt; 213 mso-pagination:widow-orphan; 214 tab-stops:center 3.0in right 6.0in; 215 font-size:12.0pt; 216 font-family:Arial; 217 mso-fareast-font-family:"Times New Roman"; 218 mso-bidi-font-family:"Times New Roman";} 219p.MsoFooter, li.MsoFooter, div.MsoFooter 220 {margin:0in; 221 margin-bottom:.0001pt; 222 mso-pagination:widow-orphan; 223 tab-stops:center 3.0in right 6.0in; 224 font-size:12.0pt; 225 font-family:Arial; 226 mso-fareast-font-family:"Times New Roman"; 227 mso-bidi-font-family:"Times New Roman";} 228p.MsoCaption, li.MsoCaption, div.MsoCaption 229 {mso-style-noshow:yes; 230 mso-style-next:Normal; 231 margin-top:6.0pt; 232 margin-right:0in; 233 margin-bottom:6.0pt; 234 margin-left:0in; 235 mso-pagination:widow-orphan; 236 font-size:10.0pt; 237 font-family:Arial; 238 mso-fareast-font-family:"Times New Roman"; 239 mso-bidi-font-family:"Times New Roman"; 240 font-weight:bold;} 241span.MsoCommentReference 242 {mso-style-noshow:yes; 243 mso-ansi-font-size:8.0pt; 244 mso-bidi-font-size:8.0pt;} 245p.MsoTitle, li.MsoTitle, div.MsoTitle 246 {margin-top:12.0pt; 247 margin-right:0in; 248 margin-bottom:3.0pt; 249 margin-left:0in; 250 text-align:center; 251 mso-pagination:widow-orphan lines-together; 252 mso-outline-level:1; 253 font-size:16.0pt; 254 mso-bidi-font-size:10.0pt; 255 font-family:Arial; 256 mso-fareast-font-family:"Times New Roman"; 257 mso-font-kerning:14.0pt; 258 mso-ansi-language:EN-IE; 259 font-weight:bold; 260 mso-bidi-font-weight:normal;} 261a:link, span.MsoHyperlink 262 {color:blue; 263 text-decoration:underline; 264 text-underline:single;} 265a:visited, span.MsoHyperlinkFollowed 266 {color:purple; 267 text-decoration:underline; 268 text-underline:single;} 269p.MsoCommentSubject, li.MsoCommentSubject, div.MsoCommentSubject 270 {mso-style-noshow:yes; 271 mso-style-parent:"Comment Text"; 272 mso-style-next:"Comment Text"; 273 margin:0in; 274 margin-bottom:.0001pt; 275 mso-pagination:widow-orphan; 276 font-size:10.0pt; 277 font-family:Arial; 278 mso-fareast-font-family:"Times New Roman"; 279 mso-bidi-font-family:"Times New Roman"; 280 font-weight:bold;} 281p.MsoAcetate, li.MsoAcetate, div.MsoAcetate 282 {mso-style-noshow:yes; 283 margin:0in; 284 margin-bottom:.0001pt; 285 mso-pagination:widow-orphan; 286 font-size:8.0pt; 287 font-family:Tahoma; 288 mso-fareast-font-family:"Times New Roman";} 289span.Heading2Char 290 {mso-style-name:"Heading 2 Char"; 291 mso-style-locked:yes; 292 mso-style-link:"Heading 2"; 293 mso-ansi-font-size:14.0pt; 294 mso-bidi-font-size:14.0pt; 295 font-family:Arial; 296 mso-ascii-font-family:Arial; 297 mso-hansi-font-family:Arial; 298 mso-bidi-font-family:Arial; 299 mso-ansi-language:EN-US; 300 mso-fareast-language:EN-US; 301 mso-bidi-language:AR-SA; 302 font-weight:bold; 303 font-style:italic;} 304p.Style1, li.Style1, div.Style1 305 {mso-style-name:Style1; 306 mso-style-parent:"Heading 4"; 307 margin-top:12.0pt; 308 margin-right:0in; 309 margin-bottom:3.0pt; 310 margin-left:0in; 311 mso-pagination:widow-orphan; 312 page-break-after:avoid; 313 mso-outline-level:4; 314 font-size:12.0pt; 315 mso-bidi-font-size:14.0pt; 316 font-family:Arial; 317 mso-fareast-font-family:"Times New Roman"; 318 mso-bidi-font-family:"Times New Roman"; 319 font-weight:bold; 320 font-style:italic; 321 mso-bidi-font-style:normal;} 322p.Code, li.Code, div.Code 323 {mso-style-name:Code; 324 margin-top:0in; 325 margin-right:0in; 326 margin-bottom:0in; 327 margin-left:.5in; 328 margin-bottom:.0001pt; 329 mso-pagination:widow-orphan; 330 font-size:12.0pt; 331 font-family:"Courier New"; 332 mso-fareast-font-family:"Times New Roman"; 333 mso-bidi-font-family:"Times New Roman";} 334 /* Page Definitions */ 335 @page 336 {mso-footnote-separator:url("JET_Programming_Manual_files/header.htm") fs; 337 mso-footnote-continuation-separator:url("JET_Programming_Manual_files/header.htm") fcs; 338 mso-endnote-separator:url("JET_Programming_Manual_files/header.htm") es; 339 mso-endnote-continuation-separator:url("JET_Programming_Manual_files/header.htm") ecs;} 340@page Section1 341 {size:8.5in 11.0in; 342 margin:1.0in 1.25in 1.0in 1.25in; 343 mso-header-margin:.5in; 344 mso-footer-margin:.5in; 345 mso-footer:url("JET_Programming_Manual_files/header.htm") f1; 346 mso-paper-source:0;} 347div.Section1 348 {page:Section1;} 349--> 350</style> 351<!--[if gte mso 10]> 352<style> 353 /* Style Definitions */ 354 table.MsoNormalTable 355 {mso-style-name:"Table Normal"; 356 mso-tstyle-rowband-size:0; 357 mso-tstyle-colband-size:0; 358 mso-style-noshow:yes; 359 mso-style-parent:""; 360 mso-padding-alt:0in 5.4pt 0in 5.4pt; 361 mso-para-margin:0in; 362 mso-para-margin-bottom:.0001pt; 363 mso-pagination:widow-orphan; 364 font-size:10.0pt; 365 font-family:"Times New Roman"; 366 mso-ansi-language:#0400; 367 mso-fareast-language:#0400; 368 mso-bidi-language:#0400;} 369table.MsoTableGrid 370 {mso-style-name:"Table Grid"; 371 mso-tstyle-rowband-size:0; 372 mso-tstyle-colband-size:0; 373 border:solid windowtext 1.0pt; 374 mso-border-alt:solid windowtext .5pt; 375 mso-padding-alt:0in 5.4pt 0in 5.4pt; 376 mso-border-insideh:.5pt solid windowtext; 377 mso-border-insidev:.5pt solid windowtext; 378 mso-para-margin:0in; 379 mso-para-margin-bottom:.0001pt; 380 mso-pagination:widow-orphan; 381 font-size:10.0pt; 382 font-family:"Times New Roman"; 383 mso-ansi-language:#0400; 384 mso-fareast-language:#0400; 385 mso-bidi-language:#0400;} 386</style> 387<![endif]--><!--[if gte mso 9]><xml> 388 <o:shapedefaults v:ext="edit" spidmax="5122"> 389 <o:colormenu v:ext="edit" fillcolor="none" strokecolor="none"/> 390 </o:shapedefaults></xml><![endif]--><!--[if gte mso 9]><xml> 391 <o:shapelayout v:ext="edit"> 392 <o:idmap v:ext="edit" data="1"/> 393 </o:shapelayout></xml><![endif]--> 394</head> 395 396<body lang=EN-US link=blue vlink=purple style='tab-interval:.5in'> 397 398<pre> 399 Copyright (C) 2009 The Android Open Source Project 400 401 Licensed under the Apache License, Version 2.0 (the "License"); 402 you may not use this file except in compliance with the License. 403 You may obtain a copy of the License at 404 405 http://www.apache.org/licenses/LICENSE-2.0 406 407 Unless required by applicable law or agreed to in writing, software 408 distributed under the License is distributed on an "AS IS" BASIS, 409 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 410 See the License for the specific language governing permissions and 411 limitations under the License. 412</pre> 413 414<div class=Section1> 415 416<p class=MsoTitle align=left style='text-align:left'><a name="_Toc203292246"></a><a 417name="_Toc203298075"><span style='mso-bookmark:_Toc203292246'><span lang=EN-IE 418style='font-size:20.0pt'>JET� Programming Manual<o:p></o:p></span></span></a></p> 419 420<p class=MsoTitle align=left style='text-align:left'><span style='mso-bookmark: 421_Toc203298075'><span style='mso-bookmark:_Toc203292246'><span lang=EN-IE>JET 422Interactive Music Engine</span></span></span></p> 423 424<p class=MsoTitle align=left style='text-align:left'><span style='mso-bookmark: 425_Toc203298075'><span style='mso-bookmark:_Toc203292246'><span lang=EN-IE 426style='font-size:12.0pt'>Vrs 2.0<o:p></o:p></span></span></span></p> 427 428<p class=MsoTitle align=left style='text-align:left'><span style='mso-bookmark: 429_Toc203298075'><span style='mso-bookmark:_Toc203292246'><span lang=EN-IE 430style='font-size:12.0pt'>Authored by SONiVOX<o:p></o:p></span></span></span></p> 431 432<p class=MsoTitle align=left style='text-align:left'><span style='mso-bookmark: 433_Toc203298075'><span style='mso-bookmark:_Toc203292246'></span></span><a 434href="http://www.sonivoxrocks.com/"><span style='mso-bookmark:_Toc203298075'><span 435style='mso-bookmark:_Toc203292246'><span lang=EN-IE style='font-size:12.0pt'>www.sonivoxrocks.com</span></span></span><span 436style='mso-bookmark:_Toc203298075'><span style='mso-bookmark:_Toc203292246'></span></span></a><span 437style='mso-bookmark:_Toc203298075'><span style='mso-bookmark:_Toc203292246'><span 438lang=EN-IE style='font-size:12.0pt'><o:p></o:p></span></span></span></p> 439 440<p class=MsoTitle align=left style='text-align:left'><span style='mso-bookmark: 441_Toc203298075'><span style='mso-bookmark:_Toc203292246'><span lang=EN-IE 442style='font-size:12.0pt'>Copyright 2009 Sonic Network, Inc.<o:p></o:p></span></span></span></p> 443 444<span style='mso-bookmark:_Toc203292246'></span><span style='mso-bookmark:_Toc203298075'></span> 445 446<p class=MsoCommentText><o:p> </o:p></p> 447 448<p class=MsoHeader><o:p> </o:p></p> 449 450<p class=MsoHeader><o:p> </o:p></p> 451 452<h1 align=left style='text-align:left'><a name="_Toc203298082"></a><a 453name="_Toc482161515"><span style='mso-bookmark:_Toc203298082'><i 454style='mso-bidi-font-style:normal'>Introduction</i></span></a><i 455style='mso-bidi-font-style:normal'><o:p></o:p></i></h1> 456 457<p class=MsoNormal>This document contains programmer guidelines for the SONiVOX 458JET Interactive Music System. JET is an interactive music player for small 459embedded devices, including the Google Android platform. It allows applications 460to include interactive music soundtracks, in <st1:place w:st="on">MIDI</st1:place> 461format, that respond in real-time to game play events and user interaction. </p> 462 463<p class=MsoNormal><o:p> </o:p></p> 464 465<p class=MsoNormal>JET works in conjunction with SONiVOX�s Embedded Audio 466Synthesizer (EAS) which is the <st1:place w:st="on">MIDI</st1:place> playback 467device for Android.<span style='mso-spacerun:yes'>� </span>Both the JET and EAS 468engines are integrated into the Android embedded platform as well as inherent 469in <i style='mso-bidi-font-style:normal'>JET Creator</i>, an application for 470authoring JET content files. As such, the JET content author can be sure that 471the playback will sound exactly the same in both <i style='mso-bidi-font-style: 472normal'>JET Creator</i> and the final Android application playing back on 473Android mobile devices.</p> 474 475<p class=MsoNormal><o:p> </o:p></p> 476 477<p class=MsoNormal>The programmer of a JET application will want to work 478closely with the content author in designing how real-time application events 479and music will interactively work together. Once decided, the content author 480will create the content and ultimately save a .jet file for the programmer to 481include in the application.</p> 482 483<p class=MsoNormal><o:p> </o:p></p> 484 485<p class=MsoNormal>Please see �JET Creator User Documentation� for additional 486information on authoring JET content.</p> 487 488<p class=MsoNormal><o:p> </o:p></p> 489 490<h2><a name="_Toc203298084">Abbreviations and Common Terms</a></h2> 491 492<p class=MsoNormal>It is important to use a common set of terms to minimize confusion. 493Since JET uses <st1:place w:st="on">MIDI</st1:place> in a unique way, normal 494industry terms may not always suffice. Here is the definition of terms as they 495are used in this document and in the JET Creator application:</p> 496 497<p class=MsoNormal><o:p> </o:p></p> 498 499<p class=MsoNormal><i style='mso-bidi-font-style:normal'>Channel</i>: MIDI data 500associated with a specific <st1:place w:st="on">MIDI</st1:place> channel. 501Standard MIDI allows for 16 channels of <st1:place w:st="on">MIDI</st1:place> 502data each of which are typically associated with a specific instrument. </p> 503 504<p class=MsoNormal><o:p> </o:p></p> 505 506<p class=MsoNormal><i style='mso-bidi-font-style:normal'>Controller</i>: A <st1:place 507w:st="on">MIDI</st1:place> event consisting of a channel number, controller 508number, and a controller value. The <st1:place w:st="on">MIDI</st1:place> spec 509associates many controller numbers with specific functions, such as volume, 510expression, sustain pedal, etc. JET also uses controller events as a means of 511embedding special control information in a <st1:place w:st="on">MIDI</st1:place> 512sequence to provide for audio synchronization.</p> 513 514<p class=MsoNormal><o:p> </o:p></p> 515 516<p class=MsoNormal><i style='mso-bidi-font-style:normal'>DAW</i>: Digital Audio 517Workstation. A common term for <st1:place w:st="on">MIDI</st1:place> and audio 518sequencing applications such as Logic, SONAR, Cubase and others. </p> 519 520<p class=MsoNormal><o:p> </o:p></p> 521 522<p class=MsoNormal><i style='mso-bidi-font-style:normal'>EAS:</i> Embedded <st1:place 523w:st="on">MIDI</st1:place> Synthesizer. The name of the SONiVOX MIDI 524synthesizer engine.</p> 525 526<p class=MsoNormal><o:p> </o:p></p> 527 528<p class=MsoNormal><i style='mso-bidi-font-style:normal'>JET</i>: Jet 529Interactive Engine. The name of the SONiVOX JET interactive music engine.</p> 530 531<p class=MsoNormal><o:p> </o:p></p> 532 533<p class=MsoNormal><i style='mso-bidi-font-style:normal'>Segment</i>: A musical 534section such as a chorus or verse that is a component of the overall 535composition. In JET, a segment can be an entire MIDI file or a derived from a 536portion of a <st1:place w:st="on">MIDI</st1:place> file.</p> 537 538<p class=MsoNormal><o:p> </o:p></p> 539 540<p class=MsoNormal><i style='mso-bidi-font-style:normal'>SMF-0</i>: Standard 541MIDI File Type 0, a MIDI file that contains a single track, but may be made up 542of multiple channels of <st1:place w:st="on">MIDI</st1:place> data.</p> 543 544<p class=MsoNormal><o:p> </o:p></p> 545 546<p class=MsoNormal><i style='mso-bidi-font-style:normal'>SMF-1</i>: Standard 547MIDI File Type 1, a MIDI file that contains a one more tracks, and each track 548may in turn be made up of one or more channels of <st1:place w:st="on">MIDI</st1:place> 549data. By convention, each channel is stored on a separate track in an SMF-1 550file. However, it is possible to have multiple MIDI channels on a single track, 551or multiple tracks that contain data for the same <st1:place w:st="on">MIDI</st1:place> 552channel.</p> 553 554<p class=MsoNormal><o:p> </o:p></p> 555 556<p class=MsoNormal><i style='mso-bidi-font-style:normal'>Track</i>: A single 557track in a DAW containing a timed sequence of <st1:place w:st="on">MIDI</st1:place> 558events. Be careful not to confuse Tracks with Channels. A MIDI file may contain 559many tracks with several tracks utilizing the same <st1:place w:st="on">MIDI</st1:place> 560channel. </p> 561 562<p class=MsoNormal><o:p> </o:p></p> 563 564<p class=MsoNormal><o:p> </o:p></p> 565 566<h1 align=left style='text-align:left'><a name="_Toc203298085"></a><a 567name="_Toc135723076"></a><a name="_Toc135723793"></a><a name="_Toc135724016"></a><a 568name="_Toc135724241"></a><a name="_Toc135724464"></a><a name="_Toc135724687"></a><a 569name="_Toc135724909"></a><a name="_Toc135725132"></a><a name="_Toc135726607"></a><a 570name="_Toc135727776"></a><a name="_Toc137004452"></a><a name="_Toc135724689"></a><a 571name="_Toc135724467"></a><span style='mso-bookmark:_Toc203298085'>The JET 572Interactive Music Concept</span></h1> 573 574<p class=MsoNormal>Interactive music can be defined as music that changes in 575real-time according to non-predictable events such as user interaction or game 576play events. In this way, interactive music is much more engaging as it has the 577ability to match the energy and mood of a game much closer than a pre-composed 578composition that never changes. In some applications and games, interactive 579music is central to the game play. Guitar Hero is one such popular game. When 580the end user successfully �captures� the musical notes coming down the fret 581board, the music adapts itself and simultaneously keeps score of successes and 582failures. JET allows for these types of music driven games as well.</p> 583 584<p class=MsoNormal><o:p> </o:p></p> 585 586<p class=MsoNormal>There are several methods for making and controlling 587interactive music and JET is one such method. This section describes the 588features of JET and how they might be used in a game or software application. 589It also describes how JET can be used to save memory in small footprint devices 590such as Android enabled mobile handsets.</p> 591 592<p class=MsoNormal><o:p> </o:p></p> 593 594<h2>JET Operation</h2> 595 596<p class=MsoNormal>JET supports a flexible music format that can be used to 597create extended musical sequences with a minimal amount of data. A musical 598composition is broken up into segments that can be sequenced to create a longer 599piece. The sequencing can be fixed at the time the music file is authored, or 600it can be created dynamically under program control.</p> 601 602<h3><span class=Heading2Char><span style='font-size:14.0pt'>Linear Music 603Example<o:p></o:p></span></span></h3> 604 605<p class=MsoNormal><!--[if gte vml 1]><v:shapetype id="_x0000_t75" coordsize="21600,21600" 606 o:spt="75" o:preferrelative="t" path="m@4@5l@4@11@9@11@9@5xe" filled="f" 607 stroked="f"> 608 <v:stroke joinstyle="miter"/> 609 <v:formulas> 610 <v:f eqn="if lineDrawn pixelLineWidth 0"/> 611 <v:f eqn="sum @0 1 0"/> 612 <v:f eqn="sum 0 0 @1"/> 613 <v:f eqn="prod @2 1 2"/> 614 <v:f eqn="prod @3 21600 pixelWidth"/> 615 <v:f eqn="prod @3 21600 pixelHeight"/> 616 <v:f eqn="sum @0 0 1"/> 617 <v:f eqn="prod @6 1 2"/> 618 <v:f eqn="prod @7 21600 pixelWidth"/> 619 <v:f eqn="sum @8 21600 0"/> 620 <v:f eqn="prod @7 21600 pixelHeight"/> 621 <v:f eqn="sum @10 21600 0"/> 622 </v:formulas> 623 <v:path o:extrusionok="f" gradientshapeok="t" o:connecttype="rect"/> 624 <o:lock v:ext="edit" aspectratio="t"/> 625</v:shapetype><v:shape id="_x0000_i1025" type="#_x0000_t75" style='width:431.25pt; 626 height:294.75pt' o:ole=""> 627 <v:imagedata src="JET_Programming_Manual_files/image013.emz" o:title=""/> 628</v:shape><![endif]--><![if !vml]><img border=0 width=575 height=393 629src="JET_Programming_Manual_files/image002.png" v:shapes="_x0000_i1025"><![endif]><!--[if gte mso 9]><xml> 630 <o:OLEObject Type="Embed" ProgID="Visio.Drawing.11" ShapeID="_x0000_i1025" 631 DrawAspect="Content" ObjectID="_1298963236"> 632 </o:OLEObject> 633</xml><![endif]--></p> 634 635<p class=MsoCaption>Figure <!--[if supportFields]><span style='mso-element: 636field-begin'></span><span style='mso-spacerun:yes'>�</span>SEQ Figure \* ARABIC 637<span style='mso-element:field-separator'></span><![endif]--><span 638style='mso-no-proof:yes'>1</span><!--[if supportFields]><span style='mso-element: 639field-end'></span><![endif]-->: Linear Music Piece</p> 640 641<p class=MsoNormal><o:p> </o:p></p> 642 643<p class=MsoNormal>This diagram shows how musical segments are stored. Each 644segment is authored as a separate <st1:place w:st="on">MIDI</st1:place> file. A 645post-processing tool combines the files into a single container file. Each 646segment can contain alternate music tracks that can be muted or un-muted to 647create additional interest. An example might be a brass accent in the chorus 648that is played only the last time through. Also, segments can be transposed up 649or down.</p> 650 651<p class=MsoNormal><o:p> </o:p></p> 652 653<p class=MsoNormal>The bottom part of the diagram shows how the musical 654segments can be recombined to create a linear music piece. In this example, the 655bridge might end with a half-step key modulation and the remaining segments 656could be transposed up a half-step to match.</p> 657 658<h3>Non-linear Music Example</h3> 659 660<p class=MsoNormal style='page-break-after:avoid'><!--[if gte vml 1]><v:shape 661 id="_x0000_i1026" type="#_x0000_t75" style='width:6in;height:291.75pt' o:ole=""> 662 <v:imagedata src="JET_Programming_Manual_files/image014.emz" o:title=""/> 663</v:shape><![endif]--><![if !vml]><img border=0 width=576 height=389 664src="JET_Programming_Manual_files/image004.png" v:shapes="_x0000_i1026"><![endif]><!--[if gte mso 9]><xml> 665 <o:OLEObject Type="Embed" ProgID="Visio.Drawing.11" ShapeID="_x0000_i1026" 666 DrawAspect="Content" ObjectID="_1298963237"> 667 </o:OLEObject> 668</xml><![endif]--></p> 669 670<p class=MsoCaption>Figure <!--[if supportFields]><span style='mso-element: 671field-begin'></span><span style='mso-spacerun:yes'>�</span>SEQ Figure \* ARABIC 672<span style='mso-element:field-separator'></span><![endif]--><span 673style='mso-no-proof:yes'>2</span><!--[if supportFields]><span style='mso-element: 674field-end'></span><![endif]-->: Non-linear music piece</p> 675 676<p class=MsoNormal><o:p> </o:p></p> 677 678<p class=MsoNormal>In this diagram, we see a non-linear music piece. The 679scenario is a first-person-shooter (FPS) and JET is providing the background 680music. The intro plays as the level is loading and then transitions under 681program control to the Searching segment. This segment is repeated 682indefinitely, perhaps with small variations (using the mute/un-mute feature) 683until activity in the game dictates a change.</p> 684 685<p class=MsoNormal><o:p> </o:p></p> 686 687<p class=MsoNormal>As the player nears a monster lair, the program starts a 688synchronized transition to the Danger segment, increasing the tension level in 689the audio. As the player draws closer to the lair, additional tracks are 690un-muted to increase the tension.</p> 691 692<p class=MsoNormal><o:p> </o:p></p> 693 694<p class=MsoNormal>As the player enters into combat with the monster, the 695program starts a synchronized transition to the Combat segment. The segment 696repeats indefinitely as the combat continues. A Bonus Hit temporarily un-mutes 697a decorative track that notifies the player of a successful attack, and 698similarly, another track is temporarily un-muted to signify when the player 699receives Special Damage.</p> 700 701<p class=MsoNormal><o:p> </o:p></p> 702 703<p class=MsoNormal>At the end of combat, the music transitions to a victory or 704defeat segment based on the outcome of battle.</p> 705 706<h3>Mute/Un-mute Synchronization</h3> 707 708<p class=MsoNormal>JET can also synchronize the muting and un-muting of tracks 709to events in the music. For example, in the FPS game, it would probably be 710desirable to place the musical events relating to bonuses and damage as close 711to the actual game event as possible. However, simply un-muting a track at the 712moment the game event occurs might result in a music clip starting in the 713middle. Alternatively, a clip could be started from the beginning, but then it 714wouldn�t be synchronized with the other music tracks.</p> 715 716<p class=MsoNormal><o:p> </o:p></p> 717 718<p class=MsoNormal>However, with the JET sync engine, a clip can be started at 719the next opportune moment and maintain synchronization. This can be 720accomplished by placing a number of short music clips on a decorative track. A <st1:place 721w:st="on">MIDI</st1:place> event in the stream signifies the start of a clip 722and a second event signifies the end of a clip. When the application calls the 723JET clip function, the next clip in the track is allowed to play fully 724synchronized to the music. Optionally, the track can be automatically muted by 725a second <st1:place w:st="on">MIDI</st1:place> event.</p> 726 727<p class=MsoNormal><o:p> </o:p></p> 728 729<p class=MsoNormal style='page-break-after:avoid'><!--[if gte vml 1]><v:shape 730 id="_x0000_i1027" type="#_x0000_t75" style='width:6in;height:116.25pt' o:ole=""> 731 <v:imagedata src="JET_Programming_Manual_files/image015.emz" o:title=""/> 732</v:shape><![endif]--><![if !vml]><img border=0 width=576 height=155 733src="JET_Programming_Manual_files/image006.png" v:shapes="_x0000_i1027"><![endif]><!--[if gte mso 9]><xml> 734 <o:OLEObject Type="Embed" ProgID="Visio.Drawing.11" ShapeID="_x0000_i1027" 735 DrawAspect="Content" ObjectID="_1298963238"> 736 </o:OLEObject> 737</xml><![endif]--></p> 738 739<p class=MsoCaption>Figure <!--[if supportFields]><span style='mso-element: 740field-begin'></span><span style='mso-spacerun:yes'>�</span>SEQ Figure \* ARABIC 741<span style='mso-element:field-separator'></span><![endif]--><span 742style='mso-no-proof:yes'>3</span><!--[if supportFields]><span style='mso-element: 743field-end'></span><![endif]-->: Synchronized Mute/Unmute</p> 744 745<h2>Audio Synchronization</h2> 746 747<p class=MsoNormal>JET provides an audio synchronization API that allows game 748play to be synchronized to events in the audio. The mechanism relies on data 749embedded in the <st1:place w:st="on">MIDI</st1:place> file at the time the 750content is authored. When the JET engine senses an event during playback it 751generates a callback into the application program. The timing of the callback 752can be adjusted to compensate for any latency in the audio playback system so 753that audio and video can be synchronized. The diagram below shows an example of 754a simple music game that involves pressing the left and right arrows in time 755with the music.</p> 756 757<p class=MsoNormal><o:p> </o:p></p> 758 759<p class=MsoNormal><o:p> </o:p></p> 760 761<p class=MsoNormal style='page-break-after:avoid'><!--[if gte vml 1]><v:shape 762 id="_x0000_i1028" type="#_x0000_t75" style='width:6in;height:100.5pt' o:ole=""> 763 <v:imagedata src="JET_Programming_Manual_files/image016.emz" o:title=""/> 764</v:shape><![endif]--><![if !vml]><img border=0 width=576 height=134 765src="JET_Programming_Manual_files/image008.png" v:shapes="_x0000_i1028"><![endif]><!--[if gte mso 9]><xml> 766 <o:OLEObject Type="Embed" ProgID="Visio.Drawing.11" ShapeID="_x0000_i1028" 767 DrawAspect="Content" ObjectID="_1298963239"> 768 </o:OLEObject> 769</xml><![endif]--></p> 770 771<p class=MsoCaption>Figure <!--[if supportFields]><span style='mso-element: 772field-begin'></span><span style='mso-spacerun:yes'>�</span>SEQ Figure \* ARABIC 773<span style='mso-element:field-separator'></span><![endif]--><span 774style='mso-no-proof:yes'>4</span><!--[if supportFields]><span style='mso-element: 775field-end'></span><![endif]-->: Music Game<span style='mso-no-proof:yes'> with 776Synchronization<o:p></o:p></span></p> 777 778<p class=MsoNormal><o:p> </o:p></p> 779 780<p class=MsoNormal>The arrows represent events in the music sequence where game 781events need to be synchronized. In this case, the blue arrow represents a time 782where the player is supposed to press the left button, and the red arrow is for 783the right button. The yellow arrow tells the game engine that the sequence is 784complete. The player is allowed a certain time window before and after the 785event to press the appropriate key.</p> 786 787<p class=MsoNormal><o:p> </o:p></p> 788 789<p class=MsoNormal>If an event is received and the player has not pressed a 790button, a timer is set to half the length of the window. If the player presses 791the button before the timer expires, the game registers a success, and if not, 792the game registers a failure. </p> 793 794<p class=MsoNormal><o:p> </o:p></p> 795 796<p class=MsoNormal>If the player presses the button before the event is 797received, a timer is set to half the length of the window. If an event is 798received before the timer expires, the game registers a success, and if not, 799the game registers a failure. Game play might also include bonuses for getting 800close to the timing of the actual event. </p> 801 802<p class=MsoNormal><o:p> </o:p></p> 803 804<h2>Operational Details</h2> 805 806<p class=MsoNormal>JET uses the standard EAS library calls to manage multiple <st1:place 807w:st="on">MIDI</st1:place> streams that are synchronized to sound like a 808seamless audio track. JET requires the use of the dynamic memory model, i.e. 809support for malloc() and free() memory allocation functions or their 810equivalent. JET also requires the DLS parser and synthesizer module to support 811custom instruments in JET content files.</p> 812 813<p class=MsoNormal><o:p> </o:p></p> 814 815<p class=MsoNormal>JET uses standard <st1:place w:st="on">MIDI</st1:place> 816events for audio synchronization. This simplifies the authoring process by 817allowing content authors to use their favorite tools for developing content. 818After the content has been developed, a simple post-processing tool pulls the 819content together into a JET compatible content file.</p> 820 821<h3>Synchronization Events</h3> 822 823<p class=MsoNormal>JET uses <st1:place w:st="on">MIDI</st1:place> controller 824events to synchronize audio. The controllers used by JET are among those not 825defined for specific use by the <st1:place w:st="on">MIDI</st1:place> 826specification. The specific controller definitions are as follows:</p> 827 828<p class=MsoNormal><o:p> </o:p></p> 829 830<p class=MsoNormal><span style='mso-tab-count:1'>����������� </span>Controllers 83180-83<span style='mso-tab-count:2'>���������������� </span>Reserved for use by 832application</p> 833 834<p class=MsoNormal><span style='mso-tab-count:1'>����������� </span>Controller 102<span 835style='mso-tab-count:2'>���������������������� </span>JET event marker</p> 836 837<p class=MsoNormal><span style='mso-tab-count:1'>����������� </span>Controller 838103<span style='mso-tab-count:2'>���������������������� </span>JET clip marker</p> 839 840<p class=MsoNormal><span style='mso-tab-count:1'>����������� </span>Controllers 841104-119<span style='mso-tab-count:2'>������������ </span>Reserved for future 842use</p> 843 844<p class=MsoNormal><o:p> </o:p></p> 845 846<h4>Controllers 80-83 � Application Controllers</h4> 847 848<p class=MsoNormal>The application may use controllers in this range for its 849own purposes. When a controller in this range is encountered, the event is 850entered into an event queue that can be queried by the application. Some 851possible uses include synchronizing video events with audio and marking a point 852in a <st1:place w:st="on">MIDI</st1:place> segment to queue up the next 853segment. The range of controllers monitored by the application can be modified 854by the application during initialization.</p> 855 856<h4>Controller 102 � JET Event Marker</h4> 857 858<p class=MsoNormal>Controller 102 is reserved for marking events in the <st1:place 859w:st="on">MIDI</st1:place> streams that are specific to JET functionality. 860Currently, the only defined value is 0, which marks the end of a segment for 861timing purposes. </p> 862 863<p class=MsoNormal><o:p> </o:p></p> 864 865<p class=MsoNormal>Normally, JET starts playback of the next segment (or 866repeats the current segment) when the <st1:place w:st="on">MIDI</st1:place> 867end-of-track meta-event is encountered. Some <st1:place w:st="on">MIDI</st1:place> 868authoring tools make it difficult to place the end-of-track marker accurately, 869resulting in synchronization problems when segments are joined together.</p> 870 871<p class=MsoNormal><o:p> </o:p></p> 872 873<p class=MsoNormal>To avoid this problem, the author can place a JET 874end-of-segment marker (controller=102, value=0) at the point where the segment is 875to be looped. When the end-of-segment marker is encountered, the next segment 876will be triggered, or if the current segment is looped, playback will resume at 877the start of the segment.</p> 878 879<p class=MsoNormal><o:p> </o:p></p> 880 881<p class=MsoNormal>The end-of-segment marker can also be used to allow for 882completion of a musical figure beyond the end of measure that marks the start 883of the next segment. For example, the content author might create a 4-bar 884segment with a drum fill that ends on beat 1 of the 5<sup>th</sup> bar � a bar 885beyond the natural end of the segment. By placing an end-of-segment marker at 886the end of the 4<sup>th</sup> bar, the next segment will be triggered, but the 887drum fill will continue in parallel with the next segment providing musical 888continuity.</p> 889 890<p class=MsoNormal><o:p> </o:p></p> 891 892<p class=MsoNormal align=center style='text-align:center;page-break-after:avoid'><!--[if gte vml 1]><v:shape 893 id="_x0000_i1029" type="#_x0000_t75" style='width:350.25pt;height:138.75pt' 894 o:ole=""> 895 <v:imagedata src="JET_Programming_Manual_files/image017.emz" o:title=""/> 896</v:shape><![endif]--><![if !vml]><img border=0 width=467 height=185 897src="JET_Programming_Manual_files/image010.png" v:shapes="_x0000_i1029"><![endif]><!--[if gte mso 9]><xml> 898 <o:OLEObject Type="Embed" ProgID="Visio.Drawing.11" ShapeID="_x0000_i1029" 899 DrawAspect="Content" ObjectID="_1298963240"> 900 </o:OLEObject> 901</xml><![endif]--></p> 902 903<p class=MsoCaption align=center style='text-align:center'>Figure <!--[if supportFields]><span 904style='mso-element:field-begin'></span><span 905style='mso-spacerun:yes'>�</span>SEQ Figure \* ARABIC <span style='mso-element: 906field-separator'></span><![endif]--><span style='mso-no-proof:yes'>5</span><!--[if supportFields]><span 907style='mso-element:field-end'></span><![endif]-->: End-of-segment Marker</p> 908 909<h4>Controller 103 � JET Clip Marker</h4> 910 911<p class=MsoNormal>Controller 103 is reserved for marking clips in a <st1:place 912w:st="on">MIDI</st1:place> track that can be triggered by the JET_TriggerClip 913API call. The clip ID is encoded in the low 6 bits of the controller value. Bit 9146 is set to one to indicate the start of a clip, and set to zero to indicate 915the end of a clip.</p> 916 917<p class=MsoNormal><o:p> </o:p></p> 918 919<p class=MsoNormal>For example, to identify a clip with a clip ID of 1, the 920author inserts a <st1:place w:st="on">MIDI</st1:place> controller event with 921controller=103 and value=65 at the start of the clip and another event with controller=103 922and value=1 at the end of the clip. When the JET_TriggerClip() function is 923called with a clip ID of 1, the track will be un-muted when the controller 924value 65 is encountered and muted again when the controller value 1 is 925encountered.</p> 926 927<p class=MsoNormal><o:p> </o:p></p> 928 929<p class=MsoNormal align=center style='text-align:center;page-break-after:avoid'><!--[if gte vml 1]><v:shape 930 id="_x0000_i1030" type="#_x0000_t75" style='width:369pt;height:275.25pt' 931 o:ole=""> 932 <v:imagedata src="JET_Programming_Manual_files/image018.emz" o:title=""/> 933</v:shape><![endif]--><![if !vml]><img border=0 width=492 height=367 934src="JET_Programming_Manual_files/image012.png" v:shapes="_x0000_i1030"><![endif]><!--[if gte mso 9]><xml> 935 <o:OLEObject Type="Embed" ProgID="Visio.Drawing.11" ShapeID="_x0000_i1030" 936 DrawAspect="Content" ObjectID="_1298963241"> 937 </o:OLEObject> 938</xml><![endif]--></p> 939 940<p class=MsoCaption align=center style='text-align:center'>Figure <!--[if supportFields]><span 941style='mso-element:field-begin'></span><span 942style='mso-spacerun:yes'>�</span>SEQ Figure \* ARABIC <span style='mso-element: 943field-separator'></span><![endif]--><span style='mso-no-proof:yes'>6</span><!--[if supportFields]><span 944style='mso-element:field-end'></span><![endif]-->: Synchronized Clip</p> 945 946<p class=MsoNormal><o:p> </o:p></p> 947 948<p class=MsoNormal>In the figure above, if the JET_TriggerClip() function is 949called prior to the first controller event, Track 3 will be un-muted when the 950first controller event occurs, the first clip will play, and the track will be 951muted when the second controller event occurs. If the JET_TriggerClip() 952function is called after the first controller event has occurred, Track 3 will 953be un-muted when the third controller event occurs, the second clip will play, 954and the track will be muted again when the fourth controller event occurs.</p> 955 956<p class=MsoNormal><o:p> </o:p></p> 957 958<p class=MsoNormal><b style='mso-bidi-font-weight:normal'>Note:</b> Normally, 959the track containing the clip is muted by the application when the segment is 960initially queued by the call to JET_QueueSegment(). If it is not muted, the clip 961will always play until Jet_TriggerClip() has been called with the clip ID.</p> 962 963<h2>JET Programming</h2> 964 965<p class=MsoNormal>The JET library builds on functionality in the EAS library. 966It is assumed that the reader is familiar with EAS and has implemented basic 967EAS audio functionality in the application. Specifically, the application must 968first initialize EAS by calling EAS_Init() and must call EAS_Render() at 969appropriate times to render audio and stream it to the audio hardware. JET also 970requires the use of the dynamic memory model which uses malloc() and free() or 971functional equivalents. </p> 972 973<p class=MsoNormal><o:p> </o:p></p> 974 975<p class=MsoNormal>Most JET function calls return an EAS_RESULT type which 976should be checked against the EAS_SUCCESS return code. Most failures are not 977fatal, i.e. they will not put the library in a state where it must be 978re-initialized. However, some failures such as memory allocation or file 979open/read errors will likely result in the specific open content failing to 980render.</p> 981 982<h3>JET Application Initialization</h3> 983 984<p class=MsoNormal>The JET library is initialized by the JET_Init() function. 985The application must first call EAS_Init() and then pass the EAS data handle 986returned by EAS_Init() to the JET_Init() function. Currently, only a single JET 987application can be active at a time.</p> 988 989<p class=MsoNormal><o:p> </o:p></p> 990 991<p class=MsoNormal>The JET_Init function takes 3 arguments: The first is the 992EAS data handle. The second is a pointer to a configuration structure 993S_JET_CONFIG and the third is the size of the configuration structure. For most 994applications, it is sufficient to pass a NULL pointer and size 0 for the 995configuration data. </p> 996 997<p class=MsoNormal><o:p> </o:p></p> 998 999<p class=MsoNormal>However, if desired, the configuration can be modified to 1000allow the application to monitor <st1:place w:st="on">MIDI</st1:place> events 1001outside the normal range of controllers allocated for JET application events. 1002In this case, a configuration structure should be allocated and the data fields 1003initialized with the appropriate values with the low and high controller 1004numbers to be monitored. The size field should be the sizeof() of the data 1005structure. This is to allow for future enhancement of the configuration data 1006while maintaining compatibility.</p> 1007 1008<h3>JET Application Termination</h3> 1009 1010<p class=MsoNormal>When the JET application terminates, it should call 1011JET_Shutdown() to release the resources allocated by the JET engine.<span 1012style='mso-spacerun:yes'>� </span>If the application has no other use for the 1013EAS library, it should also call EAS_Shutdown(). </p> 1014 1015<h3>JET Audio Processing</h3> 1016 1017<p class=MsoNormal>To start the JET engine, the content must first be opened 1018with the JET_OpenFile() function. Just as with EAS_OpenFile(), the file locator 1019is an opaque value that is passed to the EAS_HWOpenFile() function. It can 1020either be a pointer to a filename, or a pointer to an in-memory object, 1021depending on the user implementation of file I/O in the eas_host.c or 1022eas_hostmm.c module. Only a single JET content file can be opened at a time.</p> 1023 1024<p class=MsoNormal><o:p> </o:p></p> 1025 1026<p class=MsoNormal>Once the JET file is opened, the application can begin 1027queuing up segments for playback by calling the JET_QueueSegment() function. 1028Generally, it is advisable to keep a minimum of two segments queued at all 1029times:<span style='mso-spacerun:yes'>� </span>the currently playing segment 1030plus an additional segment that is ready to start playing when the current 1031segment finishes. However, with proper programming, it is possible to queue up 1032segments using a �just-in-time� technique. This technique typically involves 1033careful placement of application controller events near the end of a segment so 1034that the application is informed when a segment is about to end.</p> 1035 1036<p class=MsoNormal><o:p> </o:p></p> 1037 1038<p class=MsoNormal>After the segment(s) are queued up, playback can begin. By 1039default, the segments are initialized in a paused state. To start playback, 1040call the JET_Play() function. Playback can be paused again by calling the JET_Pause() 1041function. Once initiated, playback will continue as long as the application 1042continues to queue up new segments before all the segments in the queue are 1043exhausted.</p> 1044 1045<p class=MsoNormal><o:p> </o:p></p> 1046 1047<p class=MsoNormal>The JET_Status() function can be used to monitor progress. 1048It returns the number of segments queued, repeat count, current segment ID, and 1049play status. By monitor the number of segments queued, the application can 1050determine when it needs to queue another segment and when playback has 1051completed.</p> 1052 1053<p class=MsoNormal><o:p> </o:p></p> 1054 1055<p class=MsoNormal>When playback has completed and the application is finished 1056with the contents of the currently open file, the application should call 1057JET_CloseFile() to close the file and release any resources associated with the 1058file.</p> 1059 1060<h4>JET_Init</h4> 1061 1062<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_Init 1063(EAS_DATA_HANDLE easHandle, S_JET_CONFIG *pConfig, EAS_INT configSize)</p> 1064 1065<p class=Code style='margin-left:0in'><o:p> </o:p></p> 1066 1067<p class=MsoNormal>Initializes JET library for use by application. Most 1068application should simply pass a NULL for pConfig and 0 for configSize, which 1069means that only controller events in the application range (80-83) will end up 1070in the application event queue. If desired, the application can instantiate an 1071S_JET_CONFIG data structure and set the controller range to a different range. 1072In this case, the configSize parameter should be set to sizeof(S_JET_CONFIG).</p> 1073 1074<h4>JET_Shutdown</h4> 1075 1076<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_Shutdown 1077(EAS_DATA_HANDLE easHandle)</p> 1078 1079<p class=Code style='margin-left:0in'><o:p> </o:p></p> 1080 1081<p class=MsoNormal>Releases resources used by the JET library. The application 1082should call this function when it is no longer using the JET library.</p> 1083 1084<h4>JET_ OpenFile</h4> 1085 1086<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_OpenFile 1087(EAS_DATA_HANDLE easHandle, EAS_FILE_LOCATOR locator)</p> 1088 1089<p class=MsoNormal><o:p> </o:p></p> 1090 1091<p class=MsoNormal>Opens a JET content file for playback. Content must be 1092formatted for use by the JET library, which is typically accomplished with the 1093jetfile.py script (see �Creating JET Content�). Only a single JET content file 1094can be opened at a time. However, since JET can contain many <st1:place w:st="on">MIDI</st1:place> 1095files and DLS libraries, this limitation is normally not an issue.</p> 1096 1097<h4>JET_ CloseFile</h4> 1098 1099<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_CloseFile 1100(EAS_DATA_HANDLE easHandle)</p> 1101 1102<p class=Code style='margin-left:0in'><o:p> </o:p></p> 1103 1104<p class=MsoNormal>Closes a JET file and release the resources associated with it.</p> 1105 1106<h4>JET_ Status</h4> 1107 1108<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_Status 1109(EAS_DATA_HANDLE easHandle, S_JET_STATUS *pStatus)</p> 1110 1111<p class=Code style='margin-left:0in'><o:p> </o:p></p> 1112 1113<p class=MsoNormal>Returns the current JET status. The elements of the status 1114data structure are as follows:</p> 1115 1116<p class=MsoNormal><o:p> </o:p></p> 1117 1118<p class=Code>typedef struct s_jet_status_tag</p> 1119 1120<p class=Code>{</p> 1121 1122<p class=Code><span style='mso-tab-count:1'>���� </span>EAS_INT <span 1123style='mso-tab-count:1'>� </span>currentUserID;</p> 1124 1125<p class=Code><span style='mso-tab-count:1'>���� </span>EAS_INT <span 1126style='mso-tab-count:1'>� </span>segmentRepeatCount;</p> 1127 1128<p class=Code><span style='mso-tab-count:1'>���� </span>EAS_INT <span 1129style='mso-tab-count:1'>� </span>numQueuedSegments;</p> 1130 1131<p class=Code><span style='mso-tab-count:1'>���� </span>EAS_BOOL <span 1132style='mso-tab-count:1'> </span>paused;</p> 1133 1134<p class=Code>} S_JET_STATUS;</p> 1135 1136<p class=MsoNormal><o:p> </o:p></p> 1137 1138<p class=MsoNormal><i style='mso-bidi-font-style:normal'>currentUserID</i>: An 11398-bit value assigned by the application.</p> 1140 1141<p class=MsoNormal><i style='mso-bidi-font-style:normal'><o:p> </o:p></i></p> 1142 1143<p class=MsoNormal><i style='mso-bidi-font-style:normal'>segmentRepeatCount</i>: 1144Number of times left to repeat. Zero indicates no repeats, a negative number 1145indicates an infinite number of repeats. Any positive value indicates that the 1146segment will play n+1 times.</p> 1147 1148<p class=MsoNormal><o:p> </o:p></p> 1149 1150<p class=MsoNormal><i style='mso-bidi-font-style:normal'>numQueuedSegments</i>: 1151Number of segments currently queued to play including the currently playing 1152segment. A value of zero indicates that nothing is playing. Normally, the 1153application will queue a new segment each time the value is 1 so that playback 1154is uninterrupted.</p> 1155 1156<h4>JET_ QueueSegment</h4> 1157 1158<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_QueueSegment 1159(EAS_DATA_HANDLE easHandle, EAS_INT segmentNum, EAS_INT libNum, EAS_INT 1160repeatCount, EAS_INT transpose, EAS_U32 muteFlags, EAS_U8 userID)</p> 1161 1162<p class=Code style='margin-left:0in'><o:p> </o:p></p> 1163 1164<p class=MsoNormal>Queues up a JET MIDI segment for playback. The parameters 1165are as follows:</p> 1166 1167<p class=MsoNormal><o:p> </o:p></p> 1168 1169<p class=MsoNormal><i style='mso-bidi-font-style:normal'>segmentNum</i>: 1170Segment number as identified in the JET content configuration file.</p> 1171 1172<p class=MsoNormal><o:p> </o:p></p> 1173 1174<p class=MsoNormal><i style='mso-bidi-font-style:normal'>libNum</i>: The library 1175number as specified in the JET content configuration file. Use -1 to select the 1176standard General MIDI library.</p> 1177 1178<p class=MsoNormal><o:p> </o:p></p> 1179 1180<p class=MsoNormal><i style='mso-bidi-font-style:normal'>repeatCount</i>: The 1181number of times this segment should repeat. Zero indicates no repeat, i.e. play 1182only once. Any positive number indicates to play n+1 times. Set to -1 to repeat 1183indefinitely.</p> 1184 1185<p class=MsoNormal><o:p> </o:p></p> 1186 1187<p class=MsoNormal><i style='mso-bidi-font-style:normal'>transpose:</i> The 1188amount of pitch transposition. Set to 0 for normal playback. Range is -12 to 1189+12.</p> 1190 1191<p class=MsoNormal><o:p> </o:p></p> 1192 1193<p class=MsoNormal><i style='mso-bidi-font-style:normal'>muteFlags</i>: 1194Specific which MIDI tracks (not <st1:place w:st="on">MIDI</st1:place> channels) 1195should be muted during playback. These flags can be changed dynamically using 1196the mute functions. Bit 0 = track 0, bit 1 = track 1, etc.</p> 1197 1198<p class=MsoNormal><o:p> </o:p></p> 1199 1200<p class=MsoNormal><i style='mso-bidi-font-style:normal'>userID</i>: 8-bit 1201value specified by the application that uniquely identifies the segment. This 1202value is returned in the JET_Status() function as well as by the application 1203event when an event is detected in a segment. Normally, the application keeps 1204an 8-bit value that is incremented each time a new segment is queued up. This 1205can be used to look up any special characteristics of that track including 1206trigger clips and mute flags.</p> 1207 1208<h4>JET_ Play</h4> 1209 1210<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_Play 1211(EAS_DATA_HANDLE easHandle)</p> 1212 1213<p class=Code style='margin-left:0in'><o:p> </o:p></p> 1214 1215<p class=MsoNormal>Starts playback of the current segment. This function must 1216be called once after the initial segments are queued up to start playback. It 1217is also called after JET_Pause() to resume playback.</p> 1218 1219<h4>JET_ Pause</h4> 1220 1221<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_Pause 1222(EAS_DATA_HANDLE easHandle)</p> 1223 1224<p class=MsoNormal><o:p> </o:p></p> 1225 1226<p class=MsoNormal>Pauses playback of the current segment. Call JET_Pause() to 1227resume playback.</p> 1228 1229<h4>JET_ SetMuteFlags</h4> 1230 1231<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_SetMuteFlags 1232(EAS_DATA_HANDLE easHandle, EAS_U32 muteFlags, EAS_BOOL sync)</p> 1233 1234<p class=Code style='margin-left:0in'><o:p> </o:p></p> 1235 1236<p class=MsoNormal>Modifies the mute flags during playback. If the <i 1237style='mso-bidi-font-style:normal'>sync</i> parameter is false, the mute flags 1238are updated at the beginning of the next render. This means that any new notes 1239or controller events will be processed during the next audio frame. If the <i 1240style='mso-bidi-font-style:normal'>sync</i> parameter is true, the mute flags 1241will be updated at the start of the next segment. If the segment is repeated, 1242the flags will take effect the next time segment is repeated. </p> 1243 1244<h4>JET_ SetMuteFlag</h4> 1245 1246<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_SetMuteFlag 1247(EAS_DATA_HANDLE easHandle, EAS_INT trackNum, EAS_BOOL muteFlag, EAS_BOOL sync)</p> 1248 1249<p class=MsoNormal>Modifies a mute flag for a single track during playback. If 1250the <i style='mso-bidi-font-style:normal'>sync</i> parameter is false, the mute 1251flag is updated at the beginning of the next render. This means that any new 1252notes or controller events will be processed during the next audio frame. If 1253the <i style='mso-bidi-font-style:normal'>sync</i> parameter is true, the mute 1254flag will be updated at the start of the next segment. If the segment is 1255repeated, the flag will take effect the next time segment is repeated. </p> 1256 1257<h4>JET_ TriggerClip</h4> 1258 1259<p class=Code style='margin-left:0in'>EAS_PUBLIC EAS_RESULT JET_TriggerClip 1260(EAS_DATA_HANDLE easHandle, EAS_INT clipID)</p> 1261 1262<p class=MsoNormal><o:p> </o:p></p> 1263 1264<p class=MsoNormal>Automatically updates mute flags in sync with the JET Clip 1265Marker (controller 103). The parameter <i style='mso-bidi-font-style:normal'>clipID</i> 1266must be in the range of 0-63. After the call to JET_TriggerClip, when JET next 1267encounters a controller event 103 with bits 0-5 of the value equal to <i 1268style='mso-bidi-font-style:normal'>clipID </i>and<i style='mso-bidi-font-style: 1269normal'> </i>bit 6 set to 1, it will automatically un-mute the track containing 1270the controller event. When JET encounters the complementary controller event 1271103 with bits 0-5 of the value equal to <i style='mso-bidi-font-style:normal'>clipID 1272</i>and<i style='mso-bidi-font-style:normal'> </i>bit 6 set to 0, it will mute 1273the track again.</p> 1274 1275<h4>JET_ GetEvent</h4> 1276 1277<p class=Code style='margin-left:0in'>EAS_BOOL JET_GetEvent (EAS_DATA_HANDLE 1278easHandle, EAS_U32 *pEventRaw, S_JET_EVENT *pEvent)</p> 1279 1280<p class=MsoNormal><o:p> </o:p></p> 1281 1282<p class=MsoNormal>Attempts to read an event from the application event queue, 1283return EAS_TRUE if an event is found and EAS_FALSE if not. If the application 1284passes a valid pointer for <i style='mso-bidi-font-style:normal'>pEventRaw</i>, 1285a 32-bit compressed event code is returned. If the application passes a valid 1286pointer for <i style='mso-bidi-font-style:normal'>pEvent</i>, the event is 1287parsed into the S_JET_EVENT fields. The application can pass NULL for either 1288parameter and that variable will be ignored. Normally, the application will 1289call JET_GetEvent() repeatedly to retrieve events until it returns EAS_FALSE.</p> 1290 1291<h4>JET_ ParseEvent</h4> 1292 1293<p class=Code style='margin-left:0in'>EAS_PUBLIC void JET_ParseEvent (EAS_U32 1294event, S_JET_EVENT *pEvent)</p> 1295 1296<p class=MsoNormal>Parses a 32-bit compressed event code into a data structure. 1297The application passes the event code received from JET_GetEvent(). The parsed 1298event data is returned in the memory pointed to by <i style='mso-bidi-font-style: 1299normal'>pEvent</i>.</p> 1300 1301<h4>JET_GetAppData</h4> 1302 1303<p class=Code style='margin-left:0in'>EAS_RESULT JET_GetAppData 1304(EAS_DATA_HANDLE easHandle, EAS_I32 *pAppDataOffset, EAS_I32 *pAppDataSize)</p> 1305 1306<p class=MsoNormal>Returns the offset and size of the JAPP chunk in the JET 1307file. The application can use the file I/O functions in the eas_host module to 1308retrieve application specific data from the file. </p> 1309 1310<p class=MsoNormal><o:p> </o:p></p> 1311 1312<p class=MsoNormal><o:p> </o:p></p> 1313 1314<h2>Creating JET Content</h2> 1315 1316<p class=MsoNormal>JET uses standard MIDI files and DLS files that can be 1317created with commercially available content tools such as Logic, Cubase, 1318Digital Performer, or SONAR for <st1:place w:st="on">MIDI</st1:place> files and 1319Awave for DLS2 files. These source files are then bundled into a .jet package 1320file suitable for use in a JET application. </p> 1321 1322<p class=MsoNormal><o:p> </o:p></p> 1323 1324<p class=MsoNormal>To create JET file use the �JET Creator� desktop 1325application. The JET Creator application is written in Python and includes a 1326full graphical interface. It is available for MAC and PC platforms. See �JET 1327Creator User Manual� for more information.</p> 1328 1329</div> 1330 1331</body> 1332 1333</html> 1334
