Tracker V1.5 User Manual & Technical Guide
Total Page:16
File Type:pdf, Size:1020Kb
User Manual & Technical Guide Written by James Pujals (a.k.a. DZ-Jay) Last Updated: March 6, 2021 Revision #4 Copyright © 2020 – 2021, James Pujals Permission is granted to reproduce and distribute this material freely, without restrictions, as long as the original content remains unchanged. i The Intellivision Music Tracker! 1 Introduction!.......................................................................................................................1 Tracker Version 1.5!..........................................................................................................1 Main Features!..................................................................................................................1 I. Overview! 2 The Instrument Synthesizer!..............................................................................................3 Waveform Musical Range Polyphony Envelopes Vibrato Pitch Effects Percussion The Music Player!..............................................................................................................4 Channels Instruments Drum Kits Note Events Sub-Patterns Patterns Song Sequence II. Technical Specification! 5 Tracker Engine!.................................................................................................................5 Execution Flow Keeping Time Minimizing Jitter Tracker Time!.....................................................................................................................6 Ticks Rows Tracker Rows vs. Traditional Note Values Song Tempo Tracker Program Interface!................................................................................................8 ii III. Using The Tracker! 10 Pre-Requisites!................................................................................................................10 Program Use!..................................................................................................................11 1. Set Up Tracker 2. Initialize Tracker 3. Load A Song 4. Update Playback Advanced Configuration!.................................................................................................15 Global Tracker Configuration Playback Volume Control!................................................................................................18 Playback Channel Configuration!....................................................................................19 Channel Priority Active Channel State Impact Of Drum & Noise Effects IV. Tracker Data Format! 21 Data Layout!....................................................................................................................21 Global Definitions!...........................................................................................................22 Pitch Effects Envelopes Drums Song Definitions!.............................................................................................................29 Header Sequence Patterns Instruments Drum Kit Sub-Patterns (Data Record Format) Sub-Patterns (Macro Interface) Automatic Note Packing (NPK Macro Interface) Putting It All Together!......................................................................................................43 Global Music Definitions The Simple Song iii Appendix! 45 A. Library Distribution!.....................................................................................................45 Public Domain Release File Structure B. IntyBASIC Support!.....................................................................................................46 Overview Program Integration 1. Set Up Tracker 2. Initialize Tracker 3. Load A Song 4. Update Playback C. IntyBASIC Supplementary API!...................................................................................49 iv Acknowledgements First and foremost, I would like to thank Arnauld Chevallier for his work in creating the original Intellivision Music Tracker library, and for being so gracious in sharing it with the Intellivision home-brew community. Without Arnauld’s efforts, the Intellivision music we hear in home-brewed games would not be as rich and interesting. Although I do not think my contributions to his software are trivial, in the end the library is still very much Arnauld’s code. Arnauld’s original tracker showed us all that the Intellivision is capable of much more than just mere flat, bleepy tones; and that armed with the proper software, a talented musician can create some beautiful and complex compositions with a wide array of rich and interesting sounds – in spite of the many limitations of the console. Second, I would also like to thank Joe Zbiciak and Óscar Toledo for providing and maintaining the tools that we all depend on for our Intellivision programming efforts. I can state as a matter of fact that I would not have even approached the Intellivision as a programming tool, if it weren’t for the wonderful as1600 assembler and jzIntv emulator and debugger. Even the core of my own development framework is based on, and inspired by, Joe’s SDK-1600 library, and includes many innovations originally suggested or devised by Joe. And, although I personally do not use IntyBASIC, its impact on the Intellivision home-brew community and the democratization of game development it has enabled, cannot be discounted. Next, of course, are my mates Shazz and Zapac (Anders Carlsson), who invited me to assist on their “Voyage” demo for the @Party demoparty back in 2017. I am forever grateful to both for giving me the opportunity to work with them and produce something of which all of us are very proud. My participation on that project lead directly to this effort, and motivated me to delve deep down into the intricate guts of Arnauld’s tracker software in order to extend it and optimize it for our purposes. Several years later, it is now high time to take that work to its natural conclusion: document the enhanced tracker library exhaustively, and share it with the community. Finally, I would like to thank the AtariAge Intellivision community in general – collectors, publishers, musicians, home-brewers, lurkers, et al. – for keeping our lovely little console alive. Let us keep at it in our own ways and share our efforts and experiences. For my part, I hope that my humble contributions are of value to someone, and that they enrich the community in some way. Ultimately, I want to see more and better music and games made for the Intellivision in the future, and that’s what it is all about. – j. December, 2020 v The Intellivision Music Tracker The Intellivision Music Tracker Introduction Several years ago, Intellivision games designer and programmer Arnauld Chevallier implemented a music tracker library to play specially-crafted music files on the Intellivision. He was gracious enough to donate his code to the public domain so that all Intellivision programmers may benefit from it. Because it is freely available -- and because it is so exceptionally useful and easy to integrate -- it has become the de facto method to play music on Intellivision home-brewed games. Using the Intellivision Music Tracker in your own games is a matter of including the library, defining some needed variable labels, and adding a call to update the tracker state periodically from your game loop. You also need to create your own music files in the appropriate data format. This document describes in exhaustive detail the routines available in the library, how to use and integrate them, and the song data format. Tracker Version 1.5 In 2017, Intellivision games designer and programmer James Pujals adapted Arnauld’s music tracker library as part of an independent collaborative project. The main goals at the time were to enhance the tracker to support the three additional sound channels available in the Entertainment Computer System (ECS) expansion module, and to add additional facilities for playing drums. Because the support for twice as many channels essentially doubled the work the tracker had to do on every iteration, James re-factored much of the code to improve its execution performance. Along the way, he made some slight improvements and corrected a few long-standing defects. The result is a more versatile, highly-optimized, and compact tracker library that can play rich and complex musical compositions, while still keeping up with the critical resource demands of an Intellivision game engine. Main Features • Pattern-based song sequencing, with support for an unlimited number of patterns. • Supports up to six independent sound channels, updated and playing simultaneously. • Full 6-note polyphony; 5-note polyphony, with one drum channel; or 4-note polyphony, with two drum channels. • 64-point user-defined software envelopes. • 4-step pitch effects (e.g., arpeggios). • Vibrato effects configurable with 3 levels of depth. • Simple programmable drum sound synthesizer. • Supports up to 85 individual instrument definitions with independent envelopes, and pitch and amplitude modulation effects. • Supports over 40 individual drum instrument definitions per song. • Global master volume control. page 1 I. Overview I. Overview The Intellivision Master Component includes a General Instruments AY-3-8914 sound chip, commonly referred to as the Programmable Sound Generator, or PSG. The PSG contains three separate square-wave tone generators, each of which can be programmed individually to control its frequency and volume. The chip also includes a noise generator, which can be mixed with any of the three tone channels. All three channels, potentially modulated by the