1 <html xmlns:v="urn:schemas-microsoft-com:vml" 2 xmlns:o="urn:schemas-microsoft-com:office:office" 3 xmlns:w="urn:schemas-microsoft-com:office:word" 4 xmlns:st1="urn:schemas-microsoft-com:office:smarttags" 5 xmlns="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> 17 v\:* {behavior:url(#default#VML);} 18 o\:* {behavior:url(#default#VML);} 19 w\:* {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> 73 st1\:*{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";} 96 h1 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;} 109 h2 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;} 122 h3 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;} 133 h4 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;} 148 p.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";} 159 p.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";} 173 p.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";} 187 p.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";} 201 p.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";} 210 p.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";} 219 p.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";} 228 p.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;} 241 span.MsoCommentReference 242 {mso-style-noshow:yes; 243 mso-ansi-font-size:8.0pt; 244 mso-bidi-font-size:8.0pt;} 245 p.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;} 261 a:link, span.MsoHyperlink 262 {color:blue; 263 text-decoration:underline; 264 text-underline:single;} 265 a:visited, span.MsoHyperlinkFollowed 266 {color:purple; 267 text-decoration:underline; 268 text-underline:single;} 269 p.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;} 281 p.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";} 289 span.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;} 304 p.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;} 322 p.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;} 347 div.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;} 369 table.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 417 name="_Toc203298075"><span style='mso-bookmark:_Toc203292246'><span lang=EN-IE 418 style='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 422 Interactive 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 426 style='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 430 style='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 434 href="http://www.sonivoxrocks.com/"><span style='mso-bookmark:_Toc203298075'><span 435 style='mso-bookmark:_Toc203292246'><span lang=EN-IE style='font-size:12.0pt'>www.sonivoxrocks.com</span></span></span><span 436 style='mso-bookmark:_Toc203298075'><span style='mso-bookmark:_Toc203292246'></span></span></a><span 437 style='mso-bookmark:_Toc203298075'><span style='mso-bookmark:_Toc203292246'><span 438 lang=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 442 style='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 453 name="_Toc482161515"><span style='mso-bookmark:_Toc203298082'><i 454 style='mso-bidi-font-style:normal'>Introduction</i></span></a><i 455 style='mso-bidi-font-style:normal'><o:p></o:p></i></h1> 456 457 <p class=MsoNormal>This document contains programmer guidelines for the SONiVOX 458 JET Interactive Music System. JET is an interactive music player for small 459 embedded devices, including the Google Android platform. It allows applications 460 to include interactive music soundtracks, in <st1:place w:st="on">MIDI</st1:place> 461 format, 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 SONiVOXs Embedded Audio 466 Synthesizer (EAS) which is the <st1:place w:st="on">MIDI</st1:place> playback 467 device for Android.<span style='mso-spacerun:yes'> </span>Both the JET and EAS 468 engines are integrated into the Android embedded platform as well as inherent 469 in <i style='mso-bidi-font-style:normal'>JET Creator</i>, an application for 470 authoring JET content files. As such, the JET content author can be sure that 471 the playback will sound exactly the same in both <i style='mso-bidi-font-style: 472 normal'>JET Creator</i> and the final Android application playing back on 473 Android 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 478 closely with the content author in designing how real-time application events 479 and music will interactively work together. Once decided, the content author 480 will create the content and ultimately save a .jet file for the programmer to 481 include 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 486 information 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. 493 Since JET uses <st1:place w:st="on">MIDI</st1:place> in a unique way, normal 494 industry terms may not always suffice. Here is the definition of terms as they 495 are 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 500 associated with a specific <st1:place w:st="on">MIDI</st1:place> channel. 501 Standard MIDI allows for 16 channels of <st1:place w:st="on">MIDI</st1:place> 502 data 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 507 w:st="on">MIDI</st1:place> event consisting of a channel number, controller 508 number, and a controller value. The <st1:place w:st="on">MIDI</st1:place> spec 509 associates many controller numbers with specific functions, such as volume, 510 expression, sustain pedal, etc. JET also uses controller events as a means of 511 embedding special control information in a <st1:place w:st="on">MIDI</st1:place> 512 sequence 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 517 Workstation. A common term for <st1:place w:st="on">MIDI</st1:place> and audio 518 sequencing 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 523 w:st="on">MIDI</st1:place> Synthesizer. The name of the SONiVOX MIDI 524 synthesizer 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 529 Interactive 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 534 section such as a chorus or verse that is a component of the overall 535 composition. In JET, a segment can be an entire MIDI file or a derived from a 536 portion 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 541 MIDI File Type 0, a MIDI file that contains a single track, but may be made up 542 of 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 547 MIDI File Type 1, a MIDI file that contains a one more tracks, and each track 548 may in turn be made up of one or more channels of <st1:place w:st="on">MIDI</st1:place> 549 data. By convention, each channel is stored on a separate track in an SMF-1 550 file. However, it is possible to have multiple MIDI channels on a single track, 551 or multiple tracks that contain data for the same <st1:place w:st="on">MIDI</st1:place> 552 channel.</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 557 track in a DAW containing a timed sequence of <st1:place w:st="on">MIDI</st1:place> 558 events. Be careful not to confuse Tracks with Channels. A MIDI file may contain 559 many tracks with several tracks utilizing the same <st1:place w:st="on">MIDI</st1:place> 560 channel. </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 567 name="_Toc135723076"></a><a name="_Toc135723793"></a><a name="_Toc135724016"></a><a 568 name="_Toc135724241"></a><a name="_Toc135724464"></a><a name="_Toc135724687"></a><a 569 name="_Toc135724909"></a><a name="_Toc135725132"></a><a name="_Toc135726607"></a><a 570 name="_Toc135727776"></a><a name="_Toc137004452"></a><a name="_Toc135724689"></a><a 571 name="_Toc135724467"></a><span style='mso-bookmark:_Toc203298085'>The JET 572 Interactive Music Concept</span></h1> 573 574 <p class=MsoNormal>Interactive music can be defined as music that changes in 575 real-time according to non-predictable events such as user interaction or game 576 play events. In this way, interactive music is much more engaging as it has the 577 ability to match the energy and mood of a game much closer than a pre-composed 578 composition that never changes. In some applications and games, interactive 579 music is central to the game play. Guitar Hero is one such popular game. When 580 the end user successfully captures the musical notes coming down the fret 581 board, the music adapts itself and simultaneously keeps score of successes and 582 failures. 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 587 interactive music and JET is one such method. This section describes the 588 features of JET and how they might be used in a game or software application. 589 It also describes how JET can be used to save memory in small footprint devices 590 such 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 597 create extended musical sequences with a minimal amount of data. A musical 598 composition is broken up into segments that can be sequenced to create a longer 599 piece. The sequencing can be fixed at the time the music file is authored, or 600 it can be created dynamically under program control.</p> 601 602 <h3><span class=Heading2Char><span style='font-size:14.0pt'>Linear Music 603 Example<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 629 src="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: 636 field-begin'></span><span style='mso-spacerun:yes'></span>SEQ Figure \* ARABIC 637 <span style='mso-element:field-separator'></span><![endif]--><span 638 style='mso-no-proof:yes'>1</span><!--[if supportFields]><span style='mso-element: 639 field-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 644 segment is authored as a separate <st1:place w:st="on">MIDI</st1:place> file. A 645 post-processing tool combines the files into a single container file. Each 646 segment can contain alternate music tracks that can be muted or un-muted to 647 create additional interest. An example might be a brass accent in the chorus 648 that is played only the last time through. Also, segments can be transposed up 649 or 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 654 segments can be recombined to create a linear music piece. In this example, the 655 bridge might end with a half-step key modulation and the remaining segments 656 could 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 664 src="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: 671 field-begin'></span><span style='mso-spacerun:yes'></span>SEQ Figure \* ARABIC 672 <span style='mso-element:field-separator'></span><![endif]--><span 673 style='mso-no-proof:yes'>2</span><!--[if supportFields]><span style='mso-element: 674 field-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 679 scenario is a first-person-shooter (FPS) and JET is providing the background 680 music. The intro plays as the level is loading and then transitions under 681 program control to the Searching segment. This segment is repeated 682 indefinitely, perhaps with small variations (using the mute/un-mute feature) 683 until 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 688 synchronized transition to the Danger segment, increasing the tension level in 689 the audio. As the player draws closer to the lair, additional tracks are 690 un-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 695 program starts a synchronized transition to the Combat segment. The segment 696 repeats indefinitely as the combat continues. A Bonus Hit temporarily un-mutes 697 a decorative track that notifies the player of a successful attack, and 698 similarly, another track is temporarily un-muted to signify when the player 699 receives 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 704 defeat 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 709 to events in the music. For example, in the FPS game, it would probably be 710 desirable to place the musical events relating to bonuses and damage as close 711 to the actual game event as possible. However, simply un-muting a track at the 712 moment the game event occurs might result in a music clip starting in the 713 middle. Alternatively, a clip could be started from the beginning, but then it 714 wouldnt 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 719 the next opportune moment and maintain synchronization. This can be 720 accomplished by placing a number of short music clips on a decorative track. A <st1:place 721 w:st="on">MIDI</st1:place> event in the stream signifies the start of a clip 722 and a second event signifies the end of a clip. When the application calls the 723 JET clip function, the next clip in the track is allowed to play fully 724 synchronized to the music. Optionally, the track can be automatically muted by 725 a 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 733 src="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: 740 field-begin'></span><span style='mso-spacerun:yes'></span>SEQ Figure \* ARABIC 741 <span style='mso-element:field-separator'></span><![endif]--><span 742 style='mso-no-proof:yes'>3</span><!--[if supportFields]><span style='mso-element: 743 field-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 748 play to be synchronized to events in the audio. The mechanism relies on data 749 embedded in the <st1:place w:st="on">MIDI</st1:place> file at the time the 750 content is authored. When the JET engine senses an event during playback it 751 generates a callback into the application program. The timing of the callback 752 can be adjusted to compensate for any latency in the audio playback system so 753 that audio and video can be synchronized. The diagram below shows an example of 754 a simple music game that involves pressing the left and right arrows in time 755 with 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 765 src="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: 772 field-begin'></span><span style='mso-spacerun:yes'></span>SEQ Figure \* ARABIC 773 <span style='mso-element:field-separator'></span><![endif]--><span 774 style='mso-no-proof:yes'>4</span><!--[if supportFields]><span style='mso-element: 775 field-end'></span><![endif]-->: Music Game<span style='mso-no-proof:yes'> with 776 Synchronization<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 781 events need to be synchronized. In this case, the blue arrow represents a time 782 where the player is supposed to press the left button, and the red arrow is for 783 the right button. The yellow arrow tells the game engine that the sequence is 784 complete. The player is allowed a certain time window before and after the 785 event 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 790 button, a timer is set to half the length of the window. If the player presses 791 the button before the timer expires, the game registers a success, and if not, 792 the 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 797 received, a timer is set to half the length of the window. If an event is 798 received before the timer expires, the game registers a success, and if not, 799 the game registers a failure. Game play might also include bonuses for getting 800 close 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 807 w:st="on">MIDI</st1:place> streams that are synchronized to sound like a 808 seamless audio track. JET requires the use of the dynamic memory model, i.e. 809 support for malloc() and free() memory allocation functions or their 810 equivalent. JET also requires the DLS parser and synthesizer module to support 811 custom 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> 816 events for audio synchronization. This simplifies the authoring process by 817 allowing content authors to use their favorite tools for developing content. 818 After the content has been developed, a simple post-processing tool pulls the 819 content 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 824 events to synchronize audio. The controllers used by JET are among those not 825 defined for specific use by the <st1:place w:st="on">MIDI</st1:place> 826 specification. 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 831 80-83<span style='mso-tab-count:2'> </span>Reserved for use by 832 application</p> 833 834 <p class=MsoNormal><span style='mso-tab-count:1'> </span>Controller 102<span 835 style='mso-tab-count:2'> </span>JET event marker</p> 836 837 <p class=MsoNormal><span style='mso-tab-count:1'> </span>Controller 838 103<span style='mso-tab-count:2'> </span>JET clip marker</p> 839 840 <p class=MsoNormal><span style='mso-tab-count:1'> </span>Controllers 841 104-119<span style='mso-tab-count:2'> </span>Reserved for future 842 use</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 849 own purposes. When a controller in this range is encountered, the event is 850 entered into an event queue that can be queried by the application. Some 851 possible uses include synchronizing video events with audio and marking a point 852 in a <st1:place w:st="on">MIDI</st1:place> segment to queue up the next 853 segment. The range of controllers monitored by the application can be modified 854 by 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 859 w:st="on">MIDI</st1:place> streams that are specific to JET functionality. 860 Currently, the only defined value is 0, which marks the end of a segment for 861 timing 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 866 repeats the current segment) when the <st1:place w:st="on">MIDI</st1:place> 867 end-of-track meta-event is encountered. Some <st1:place w:st="on">MIDI</st1:place> 868 authoring tools make it difficult to place the end-of-track marker accurately, 869 resulting 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 874 end-of-segment marker (controller=102, value=0) at the point where the segment is 875 to be looped. When the end-of-segment marker is encountered, the next segment 876 will be triggered, or if the current segment is looped, playback will resume at 877 the 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 882 completion of a musical figure beyond the end of measure that marks the start 883 of the next segment. For example, the content author might create a 4-bar 884 segment with a drum fill that ends on beat 1 of the 5<sup>th</sup> bar a bar 885 beyond the natural end of the segment. By placing an end-of-segment marker at 886 the end of the 4<sup>th</sup> bar, the next segment will be triggered, but the 887 drum fill will continue in parallel with the next segment providing musical 888 continuity.</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 897 src="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 904 style='mso-element:field-begin'></span><span 905 style='mso-spacerun:yes'></span>SEQ Figure \* ARABIC <span style='mso-element: 906 field-separator'></span><![endif]--><span style='mso-no-proof:yes'>5</span><!--[if supportFields]><span 907 style='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 912 w:st="on">MIDI</st1:place> track that can be triggered by the JET_TriggerClip 913 API call. The clip ID is encoded in the low 6 bits of the controller value. Bit 914 6 is set to one to indicate the start of a clip, and set to zero to indicate 915 the 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 920 author inserts a <st1:place w:st="on">MIDI</st1:place> controller event with 921 controller=103 and value=65 at the start of the clip and another event with controller=103 922 and value=1 at the end of the clip. When the JET_TriggerClip() function is 923 called with a clip ID of 1, the track will be un-muted when the controller 924 value 65 is encountered and muted again when the controller value 1 is 925 encountered.</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 934 src="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 941 style='mso-element:field-begin'></span><span 942 style='mso-spacerun:yes'></span>SEQ Figure \* ARABIC <span style='mso-element: 943 field-separator'></span><![endif]--><span style='mso-no-proof:yes'>6</span><!--[if supportFields]><span 944 style='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 949 called prior to the first controller event, Track 3 will be un-muted when the 950 first controller event occurs, the first clip will play, and the track will be 951 muted when the second controller event occurs. If the JET_TriggerClip() 952 function is called after the first controller event has occurred, Track 3 will 953 be un-muted when the third controller event occurs, the second clip will play, 954 and 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, 959 the track containing the clip is muted by the application when the segment is 960 initially queued by the call to JET_QueueSegment(). If it is not muted, the clip 961 will 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. 966 It is assumed that the reader is familiar with EAS and has implemented basic 967 EAS audio functionality in the application. Specifically, the application must 968 first initialize EAS by calling EAS_Init() and must call EAS_Render() at 969 appropriate times to render audio and stream it to the audio hardware. JET also 970 requires the use of the dynamic memory model which uses malloc() and free() or 971 functional 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 976 should be checked against the EAS_SUCCESS return code. Most failures are not 977 fatal, i.e. they will not put the library in a state where it must be 978 re-initialized. However, some failures such as memory allocation or file 979 open/read errors will likely result in the specific open content failing to 980 render.</p> 981 982 <h3>JET Application Initialization</h3> 983 984 <p class=MsoNormal>The JET library is initialized by the JET_Init() function. 985 The application must first call EAS_Init() and then pass the EAS data handle 986 returned by EAS_Init() to the JET_Init() function. Currently, only a single JET 987 application 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 992 EAS data handle. The second is a pointer to a configuration structure 993 S_JET_CONFIG and the third is the size of the configuration structure. For most 994 applications, it is sufficient to pass a NULL pointer and size 0 for the 995 configuration 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 1000 allow the application to monitor <st1:place w:st="on">MIDI</st1:place> events 1001 outside the normal range of controllers allocated for JET application events. 1002 In this case, a configuration structure should be allocated and the data fields 1003 initialized with the appropriate values with the low and high controller 1004 numbers to be monitored. The size field should be the sizeof() of the data 1005 structure. This is to allow for future enhancement of the configuration data 1006 while maintaining compatibility.</p> 1007 1008 <h3>JET Application Termination</h3> 1009 1010 <p class=MsoNormal>When the JET application terminates, it should call 1011 JET_Shutdown() to release the resources allocated by the JET engine.<span 1012 style='mso-spacerun:yes'> </span>If the application has no other use for the 1013 EAS 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 1018 with the JET_OpenFile() function. Just as with EAS_OpenFile(), the file locator 1019 is an opaque value that is passed to the EAS_HWOpenFile() function. It can 1020 either be a pointer to a filename, or a pointer to an in-memory object, 1021 depending on the user implementation of file I/O in the eas_host.c or 1022 eas_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 1027 queuing up segments for playback by calling the JET_QueueSegment() function. 1028 Generally, it is advisable to keep a minimum of two segments queued at all 1029 times:<span style='mso-spacerun:yes'> </span>the currently playing segment 1030 plus an additional segment that is ready to start playing when the current 1031 segment finishes. However, with proper programming, it is possible to queue up 1032 segments using a just-in-time technique. This technique typically involves 1033 careful placement of application controller events near the end of a segment so 1034 that 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 1039 default, the segments are initialized in a paused state. To start playback, 1040 call the JET_Play() function. Playback can be paused again by calling the JET_Pause() 1041 function. Once initiated, playback will continue as long as the application 1042 continues to queue up new segments before all the segments in the queue are 1043 exhausted.</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. 1048 It returns the number of segments queued, repeat count, current segment ID, and 1049 play status. By monitor the number of segments queued, the application can 1050 determine when it needs to queue another segment and when playback has 1051 completed.</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 1056 with the contents of the currently open file, the application should call 1057 JET_CloseFile() to close the file and release any resources associated with the 1058 file.</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 1068 application should simply pass a NULL for pConfig and 0 for configSize, which 1069 means that only controller events in the application range (80-83) will end up 1070 in the application event queue. If desired, the application can instantiate an 1071 S_JET_CONFIG data structure and set the controller range to a different range. 1072 In 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 1082 should 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 1092 formatted for use by the JET library, which is typically accomplished with the 1093 jetfile.py script (see Creating JET Content). Only a single JET content file 1094 can be opened at a time. However, since JET can contain many <st1:place w:st="on">MIDI</st1:place> 1095 files 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 1114 data 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 1123 style='mso-tab-count:1'> </span>currentUserID;</p> 1124 1125 <p class=Code><span style='mso-tab-count:1'> </span>EAS_INT <span 1126 style='mso-tab-count:1'> </span>segmentRepeatCount;</p> 1127 1128 <p class=Code><span style='mso-tab-count:1'> </span>EAS_INT <span 1129 style='mso-tab-count:1'> </span>numQueuedSegments;</p> 1130 1131 <p class=Code><span style='mso-tab-count:1'> </span>EAS_BOOL <span 1132 style='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 1139 8-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>: 1144 Number of times left to repeat. Zero indicates no repeats, a negative number 1145 indicates an infinite number of repeats. Any positive value indicates that the 1146 segment 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>: 1151 Number of segments currently queued to play including the currently playing 1152 segment. A value of zero indicates that nothing is playing. Normally, the 1153 application will queue a new segment each time the value is 1 so that playback 1154 is 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 1160 repeatCount, 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 1165 are 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>: 1170 Segment 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 1175 number as specified in the JET content configuration file. Use -1 to select the 1176 standard 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 1181 number of times this segment should repeat. Zero indicates no repeat, i.e. play 1182 only once. Any positive number indicates to play n+1 times. Set to -1 to repeat 1183 indefinitely.</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 1188 amount 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>: 1194 Specific which MIDI tracks (not <st1:place w:st="on">MIDI</st1:place> channels) 1195 should be muted during playback. These flags can be changed dynamically using 1196 the 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 1201 value specified by the application that uniquely identifies the segment. This 1202 value is returned in the JET_Status() function as well as by the application 1203 event when an event is detected in a segment. Normally, the application keeps 1204 an 8-bit value that is incremented each time a new segment is queued up. This 1205 can be used to look up any special characteristics of that track including 1206 trigger 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 1216 be called once after the initial segments are queued up to start playback. It 1217 is 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 1227 resume 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 1237 style='mso-bidi-font-style:normal'>sync</i> parameter is false, the mute flags 1238 are updated at the beginning of the next render. This means that any new notes 1239 or controller events will be processed during the next audio frame. If the <i 1240 style='mso-bidi-font-style:normal'>sync</i> parameter is true, the mute flags 1241 will be updated at the start of the next segment. If the segment is repeated, 1242 the 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 1250 the <i style='mso-bidi-font-style:normal'>sync</i> parameter is false, the mute 1251 flag is updated at the beginning of the next render. This means that any new 1252 notes or controller events will be processed during the next audio frame. If 1253 the <i style='mso-bidi-font-style:normal'>sync</i> parameter is true, the mute 1254 flag will be updated at the start of the next segment. If the segment is 1255 repeated, 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 1265 Marker (controller 103). The parameter <i style='mso-bidi-font-style:normal'>clipID</i> 1266 must be in the range of 0-63. After the call to JET_TriggerClip, when JET next 1267 encounters a controller event 103 with bits 0-5 of the value equal to <i 1268 style='mso-bidi-font-style:normal'>clipID </i>and<i style='mso-bidi-font-style: 1269 normal'> </i>bit 6 set to 1, it will automatically un-mute the track containing 1270 the controller event. When JET encounters the complementary controller event 1271 103 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 1273 the 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 1278 easHandle, 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, 1283 return EAS_TRUE if an event is found and EAS_FALSE if not. If the application 1284 passes a valid pointer for <i style='mso-bidi-font-style:normal'>pEventRaw</i>, 1285 a 32-bit compressed event code is returned. If the application passes a valid 1286 pointer for <i style='mso-bidi-font-style:normal'>pEvent</i>, the event is 1287 parsed into the S_JET_EVENT fields. The application can pass NULL for either 1288 parameter and that variable will be ignored. Normally, the application will 1289 call 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 1294 event, S_JET_EVENT *pEvent)</p> 1295 1296 <p class=MsoNormal>Parses a 32-bit compressed event code into a data structure. 1297 The application passes the event code received from JET_GetEvent(). The parsed 1298 event data is returned in the memory pointed to by <i style='mso-bidi-font-style: 1299 normal'>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 1307 file. The application can use the file I/O functions in the eas_host module to 1308 retrieve 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 1317 created with commercially available content tools such as Logic, Cubase, 1318 Digital Performer, or SONAR for <st1:place w:st="on">MIDI</st1:place> files and 1319 Awave for DLS2 files. These source files are then bundled into a .jet package 1320 file 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 1325 application. The JET Creator application is written in Python and includes a 1326 full graphical interface. It is available for MAC and PC platforms. See JET 1327 Creator User Manual for more information.</p> 1328 1329 </div> 1330 1331 </body> 1332 1333 </html> 1334