Houston Tracker
aboutdownloadmanuallinksgithub



Manual

Preface
Requirements
Installing
Usage
    Keys
Menu functions
Composing
Note table


Preface



WARNING: This program is currently in a very early alpha stage, and may crash or even permanently damage your calculator.
Especially the 83+/84+ version has not been thoroughly tested yet.
Use it at your own risk.

Houston Tracker program allows you to compose music on the TI82, TI83/82STATS, and TI83+/84+. It currently features 3 different sound routines with up to 4 channels of tone, 2 simple drum sounds which interrupts playback of the tone channels. The sound is played back through the TI's link port.

The current version is a work-in-progress. Not everything that you see on screen is really implemented yet.


Requirements



To use Houston Tracker, you will need the following:

- A TI82 with ROM version 16.0-19.0 (ROM 19.006/TI82CS will not work), a TI83/82STATS, or a TI83+/84+.
  TI83+SE, TI73, and TI76.fr may also work, though this hasn't been tested yet.
- CrASH 1.6 (TI82), Ion 1.6u (TI83/82STATS), resp. MirageOS 1.2 or any newer shell (TI83+/84+)
- A 2.5mm stereo jack adapter or cable (you can easily build one from a calc-to-calc link cable)
- A link cable, and linking software

Q: Does TI's "SilverLink" USB cable work for TI82?
A: Yes, contrary to what TI and ticalc.org say, it works with TiLP 1.6 and up. Just make sure you install TiLP before plugging the cable into your computer for the first time. Also, do not install any official TI connectivity software, it will break TiLP.


Installing



You can install Houston Tracker on your calculator in three steps.

To install HT on TI82,
1) Reset your calculator by pressing [2nd],[+], then select "Reset" and confirm with "Reset" again.
2) Install CrASH by sending CRASH.82B to your calculator.
3) Install Houston Tracker by sending HOUSTON.82P to your calculator.

To install HT on TI83/82STATS,
1) Reset your calculator by pressing [2nd],[+], then select "Reset" and confirm with "Reset" again.
2) Install Ion by sending ION.83G to your calculator, and running prgmION once.
3) Install Houston Tracker by sending HOUSTON.83P to your calculator.

To install HT on TI83+/84+,
1) Reset your calculator by pressing [2nd],[+], then select "Reset", select "All RAM" and confirm with "Reset" again.
2) Install MirageOS (or a newer shell such as DoorsCS) by sending MIRAGEOS.8xk to your calculator.
3) Install Houston Tracker by sending HOUSTON.8XP to your calculator.

Alternatively, you can simply pull a backup from another calculator with the same rom version.

PLEASE NOTE: It is not recommended to install/run any other programs
             while Houston Tracker is installed on your calculator.
             Most importantly, do not attempt to run any programs that
             place a custom interrupt routine in APD_BUF (aka saferam1).


Usage



Houston Tracker works more or less like any other music tracker, except for two things:
- It uses hexadecimal values instead of note names.
- It uses continuous note data, rather than pattern sequences.

On TI83, HT takes a few seconds to start up and shut down, so be patient ;)


Keys


Some keys have secondary functions, these are used while in Menu mode and/or Playback mode.

0-F      Enter data - no need to switch to Alpha Mode 
         for letters.

[GRAPH]  Go to Menu/Select Menu entry

[Y=]     Copy (same as menu option)
[WINDOW] Cut (same as menu option)
[ZOOM]   Quick Copy current row to buffer
[TRACE]  Quick Paste buffer to current row/
         Switch copy mode  

         The temporary buffer is occasionally destroyed.
         You can also use [.] instead of [ZOOM].  

[LOG]    Set block start to current row # (for Copy/Cut)   
[LN]     Set block end to current row #
[STO>]   Set target row # (for Jump/Insert/Paste)

[x²]     Mute current channel (works for Play Row only)

[+]      Increase song tempo value (=> speed down)
[-]      Decrease song tempo value (=> speed up)

[*]      Select next engine
[÷]      Select previous engine
         During playback: Loop current row

[^]      Hold (pause) playback
[.]      Play current row
[(-)]    Play from current position
[ENTER]  Play from start
[CLEAR]  Stop playback/Abort

         All playback related keys are only checked 
         between notes.

[MODE]   Exit Houston Tracker

In case you haven't already guessed it, the direction keys move the cursor around.



Menu functions

JMP      Instantly jump to a specified location in song data.
 - You will be prompted for a song row to jump to.
 - You cannot jump directly to the last 9 rows of the work area.
 - Instead of editing the target row number manually you can also
   set it directly from the main editor view by pressing [STO>].
 - The target row # setting is shared with the Copy/Paste values.

CPY Copy a block of song data to a new location.
 - Only unmuted channels are copied.
 - You will be prompted for start/end points, mode, and target row.
 - Copy mode can be switched with the [TRACE] key.
 - There are two modes: You can either INSert or PaSTe the block.
 - You must copy at least 2 lines.
 - You cannot paste/insert into the source block.
 - You cannot copy from the last 10 rows of the work area.
 - Instead of editing start/end/target manually you can also
   set them directly from the main editor view. To copy the
   current row number to start/end/target fields, press [LOG]/
   [LN]/[STO>] accordingly.
 - So once you have set valid numbers for all required fields,
   you can simply press [Y=] three times to do a quick copy ;)

CUT Delete selected block and move consecutive data up.
 - You must cut at least 2 lines.
 - All channels are cut, regardless of Mute status.
 - You cannot cut the last 10 rows of the work area.
 - You can manually edit start/end points, or use [LOG]/[LN].
 - To do a quick cut, press [WINDOW], then [Y=],[Y=].

ZAP Delete the current tune before and including the end marker.
 - Deletes entire song if no end marker is set.

LD Load a previously saved tune.
 - Will be ignored if no saved tunes are found in memory.

SAV Save the current work-in-progress tune.
 - If not enough memory is free, a "mem full" error will be generated.
 - If a $fe byte is found, or no end marker is set, a "bad data" error will be generated.

DEL Delete a previously saved tune.
 - Will be ignored if no saved tunes are found in memory.


Composing

All data has to be entered in hexadecimal format. All values between $01 and $fd are valid notes. See the table below for a rough translation between hex values and pitches. Notes from the 4th octave upwards are likely to be detuned. Note length is fixed to 1 row, to make a longer tone simply repeat notes.

HT includes three different sound routines, aka engines. The data layout, overall pitch, and average speed depend on the sound routine you are using.


Engine 1 (TIM-4)
Engine 2 (TIM-FX)
Engine 3 (Mark-2)


General features (same for all engines)

Songs are limited to a maximum length of 2000 rows on TI82, 1800 rows on TI83, resp. 1600 rows on TI83+/84+. For all "light" versions, the maximum song length is 1000 rows.

$00 inserts a rest.

Drums are the same for all engines. Possible values are $01 (kick), $02 (snare/hihat), and $03 (rimshot).

$ff on drum channel sets an end marker. When the player encounters an end marker, it will loop back to the start. You must set the end marker in order to use COPY and CUT.

You can set the tempo with keys [+] and [-]. The actual number of internal sound loop iterations (and thus the speed) is calculated as 257 + tempo + (tempo * 256).

Some useful tempo chains:

Tempo   Loops     Tempo   Loops  
$01  514 ($0202)     $02  771
$03 1028 ($0404)     $05 1542
$07 2056 ($0808)     $0b 3084
$0f 4112 ($1010)     $17 6168

You can also set the tempo on the fly. Usually this is done by changing the first nibble of the drum channel. However, each engine interprets this a little differently.


Engine 1-specific features

Engine 1 does not use any additional special commands. It simply uses one channel for drums and 4 tone channels.

Any tempo change written to the first nibble of the drum channel is temporary, meaning the player will return to normal tempo setting on the next row.

Btw, the engine is called TIM-4, which stands for Texas Instruments Music. And, of course, it's also a reference to the legendary Tim Follin.



Engine 2-specific features

Engine 2 features a number of special effect commands, as well as full speed control from within the song data.


FX #   FX parameter   Effect   Reset  
$01 $nn Slide up; nn = speed per row
$02 $nn Slide down; nn = speed   per row

$08 $00
$01
$02
$03
Set panning: center
             left
             right
             split

manual
$0e $nn Retrigger $nn times per row
$0f $nn Set speed to $nn per loop or manual

+$10 n/a Set volume to "quiet" level.
Can be added to other fx commands.  
per row

Drums are not affected by any of the fx settings.

Unlike with engine 1, the tempo setting is maintained until you reset it, or the player loops back to the start of the song. Setting the tempo via the effect command will override on-the-fly changes in the drum channel. The highest valid tempo value is $fe.



Engine 3-specific features

Engine 3 offers 3 square wave channels. The engine is rather fast, so you'll need to use higher than usual tempo values.

There is a slight volume difference between channels - ch1 is the quietest, ch3 is a tad louder (barely noticable), and ch2 is a fair bit louder than the others.

The first nibble of the drum channel does not change the tempo - instead it toggles the stereo mode. Normally the engine is in mono mode. If you enter a non-zero value here, it will switch to stereo mode - ch1 is panned left, ch2 stays in the center, and ch3 is panned right. The engine resets to mono mode after each row. Unfortunately, stereo mode suffers from a more noticable parasite tone.

Changing the tempo can be done by writing a value to the last channel. The highest valid value is $fe. The engine will revert back to normal tempo on the next row.

The kick drum ($01) is pretty useless for this engine, you can make a better kick by putting a low note in all 3 channels and set the tempo to a value around $02 for that row.

Btw, the engine is called Mark-2. It's a reference to Mark Alexander, who discovered the xor-based 1-bit synthesis method, and who wrote the first ZX Spectrum beeper music editor back in 1985.



Note Tables

Below you'll find some note to hex conversion tables. These are by no means the only possible tuning. It might well be possible to make more efficient tables by tuning the reference note away from 440 Hz. If you come up with an alternative table, send it in and it'll be included in this documentation.

In some very rare cases, treble notes may cancel out bass notes. To work around this, you can set the bass note to a different channel (Engine 1), detune it by $01 (all engines), or activate split panning (Engine 2). Engine 3 doesn't have this problem.


Engine 1 (Table by Akareyon)  

                 c-3   $bd
c#1   $03        c#3   $c0
d-1   $11        d-3   $c4
d#1   $1f        d#3   $c7
e-1   $2b        e-3   $ca
f-1   $37        f-3   $cd
f#1   $43        f#3   $d0
g-1   $4d        g-3   $d3
g#1   $57        g#3   $d5
a-1   $61        a-3   $d7˜$d8 
a#1   $6a        a#3   $da
b-1   $72        b-3   $dc

c-2   $7a        c-4   $de
c#2   $81        c#4   $e0
d-2   $88˜$89    d-4   $e1˜$e2
d#2   $8f        d#4   $e3
e-2   $95        e-4   $e5
f-2   $9b        f-4   $e6
f#2   $a1        f#4   $e7˜$e8
g-2   $a6        g-4   $e9
g#2   $ab        g#4   $ea
a-2   $b0
a#2   $b4
b-2   $b9

Engine 1 (Table by TylerBarnes)  

note table E1
Engine 3 (Table by TylerBarnes)

note table E3