Manual · 6

Music editor

The music editor writes songs for the TIA's two sound channels, or for samples on an ELF cartridge. It plays them the way the console does, shows how far each note is out of tune, and saves the player and the data your program includes.

Create a song with File → New music... A .vcsmusic file is JSON, so it reads well and compares well in version control. It holds the instruments, the patterns, the order, the tuning and the target.

Writing a song

The same pattern is shown twice: as a Tracker grid and as a Piano roll. Write notes in either one.

• In the grid, the computer keyboard works as a piano. In the piano roll, a click on the piano writes the note at the cursor.
• Patterns are played in an Order list, with a loop point.
• Each pattern has its own Speed (video frames per row) and its own Swing (alternating speeds).
• Play follows the cursor. One channel can be heard alone, and Save as WAV writes the song once through.

The sound is made by VCSIDE's own code, counter by counter as the TIA does it, on NTSC or PAL as the project says. It follows Chris Brenner's description of the TIA's counters and of how its two channels mix. A test compares it with Gopher2600.

Instruments

Melodic instruments choose among the tonal sounds of AUDC (square, square ÷6, ÷31, 5 bits, ÷93...). Drum instruments give the AUDC and AUDF of each frame.

• Volume has an envelope with a held loop, and a Release that plays after a note off.
• The pitch envelope moves the note in cents or in AUDF steps.
• An instrument can have several volume envelopes and releases. Pick one in a cell's effect column: V1, R2...
• Any note can be tuned by hand, with its own list of AUDC and AUDF values.

The Registers view shows what the player writes to AUDC, AUDF and AUDV on every frame, which values change and, under the mouse, why. The envelopes per frame and the swing follow the example of TIATracker, by Andre "Kylearan" Wichmann.

Tuning

The TIA only has whole dividers, so most notes land a little off. Every note, piano key and piano-roll bar is coloured by how many cents it is off A440. The Tuning tab lists the AUDC and AUDF of each note, the worst error and the average.

Tune the song tries every transposition and every A4 from -50 to +50 cents, using the sounds each instrument allows. You choose whether it minimises the worst note or the average. Tuning against the song instead of A440 is an idea from Paul Slocum's setups in his Atari 2600 Music and Sound Programming Guide. The frequency formula and the distortions come from Ron Fries' TIASOUND.

Samples on ELF cartridges

In Sound, choose Samples (ELF) to use 1 to 4 voices that the cartridge's ARM mixes into one AUDV0 value per scanline. The pitch is exact, so there is no tuning, only transposition and A4.

• A Waveform can be a square with any duty, a triangle, a sawtooth, a sine, noise, or 32 levels drawn by hand.
• Loudness sets the gain. Voices that sum past the top level clip.
• Songs of up to 3 voices can also be exported for DPC+ and CDFJ.

The mixing follows the TIA's non-linear output, in the form Thomas Jentzsch simplified from Chris Brenner's model. The cartridge's music is DPC+'s, by Darrell Spice Jr. and Fred Quimby.

Sound effects

A sound effect is an instrument and a note on a channel, with a name: a jump, a shot. While it sounds, the song waits on that channel. In a song of samples, an effect marked TIA channel 1 plays there as a TIA sound, noise included, and the song keeps all its voices.

The export gives each effect a constant, such as MUSIC_EFFECT_FIRE, and the game plays it with MusicEffect (assembly) or music_effect(n) (C).

Export and import

Export... chooses where the code goes, and the file is rewritten on every save, in the project's generated/music/ (next to the song in older projects). Every song of the folder exported the same way goes into one file, with one player.

• DASM and batari Basic: music.asm, with VCSIDE's own player (about 400 bytes and 19 bytes of zero page) and the songs. The player writes exactly what the editor plays.
• C: music.h. A TIA song gets a C player you call once per frame, for ELF games and batari Basic's PXE kernel; a song played as samples, one you call once per scanline and once per frame.
• DPC+ and CDFJ: files for each cartridge's own voices.

The players are public domain (CC0), so your game carries no notice. File → Import TIATracker song... (or opening a .ttt) makes a .vcsmusic that plays as TIATracker plays it. The DASM and batari Basic examples play a song with two effects, and the ELF, DPC+ and CDFJ examples play it as samples.