Overview

PETCB2 is a VSTi plugin, a counter part for PCSPE, but for Commodore
PET and other 6522 VIA equipped computers rather than classic PC Speaker.
Basically it allows to use a modern DAW to create single channel music
within limitations of the Commodore PET computer's CB2 sound output.
End result can be used in the DAW like usual, or exported as data to be
used in actual PET programs.



Usage

To make work easier, setup your project in a way that many MIDI tracks 
get routed to the same instance of the plugin, using different MIDI 
channels. You can then assign an instrument to a MIDI channel from the 
plugin UI. You can use Program Change messages in any MIDI channel as 
well. 

Any MIDI channel can play only one note at once. You can make 
arpeggiated chords using the arpeggio envelope. For better convenience, 
you may employ my ChipArp auto arpeggiator plugin to be able to work 
with normal chords in the piano roll. 

An instrument consist of four envelopes - tone enable/disable, arpeggio,
pitch slide. and waveform. They're defined via text strings, similar to 
MML or FamiTracker. String may contain any decimal numbers, L or | to 
set loop starting point. Numbers can be followed by *N to repeat the 
same number N times. Envelopes can be scaled with xN, each following 
number will be duplicated N times. Examples for better understanding: 


1 2  		>	1 2 
1*2 2*3 	>	1 1 2 2 2
1 x3 2 3 	>	1 2 2 2 3 3 3
1 L 2 3 	>	1 then constantly repeating 2 3


Music is played by 'frames' or 'interrupts', which is usually tied to 
the display refresh rate. In case with PET it is normally 60 times per
second, so the plugin is fixed to use this value.

Volume envelope simply enables or disables the tone generator. To cram 
multiple music channels into single monophonic tone generator, a simple 
priority system based on the virtual volume value is implemented. Only 
instruments with greater volume in current 'frame' will take control on 
the generator, and all others won't play. So if your bass instrument has 
volume 1, and your kick and snare drums has volume 2, they're will cut 
through the bass, disabling it while they're playing. 

Arpeggio envelope contain offsets in semitones relative to the note 
pressed. The purpose is to create arpeggio like effects, such as 
one-note chords. It may also have # in front of a value, which means 
absolute value (note number in semitones). This way you can create pitch 
independent instruments, like a kick drum that plays the same regardless 
of note. 

Pitch envelope contains pitch changes in cents. It may be used to create 
vibrato, or slides for percussion instruments. Unlike other envelopes, 
it accumulates the value. If you loop -1, it will decrement pitch by one 
every interrupt. Example: 


L -10		>   -10 -20 -30 -40 -50 and so on


Waveform envelope affects to the pitch and sometimes the octave of the
sound. Each entry should be in the range of 1..15. 0 will produce no
sound, and greater values would produce just inversions of the others,
so they're clamped. 15 creates a normal square wave, 7 gives a thinner
sound, 3 even thinner, and 1 thinnest possible. Other values will add
higher harmonics into the sound.


There is also Multi mode that is mostly useful for fixed-pitch 
instruments, such as kick or snare drum. In this mode a note played gets
ignored, instrument always played at C-4, but offset from C-4 selects
another instrument in the list. I.e. C#4 will play next instrument, B-3
will play the previous instrument in the preset list. 


MOS6522 aka VIA that is used for the CB2 sound output in the original
Commodore PET features a 8-bit clock divider, so frequency range and
resolution is severely limited, with the lowest possible note at
~245 Hz. It makes it very difficult to use for musical purposes.
There is a way to improve this via software trickery, basically
emulating VIA shift register with the timer-driven interrups. These
modes are represented in the plugin with the Range buttons. The Standard
range uses 8-bit divider and limits the lowest end of the frequency
range, the Extended range opens any lower notes. These buttons also
affect to the log format.



Logging

You can make a recording of MIDI data converted into PC Speaker data 
stream that can be then used in a real MS-DOS program, or for other 
similar purposes. It works like a log of everything what happens during 
playing back the song in the DAW. You need to start log, then play the 
whole song, then stop log. Data will be saved into one of three 
text-based formats - CSV, QBasic data, or C header. You can manually 
edit exported file later to cut out silence at beginning and end of the 
log. 

There is also an Auto Cut feature that helps to make a cleaner export.
Enable  it with the AC button. Mark beginning of the song with any change
of the controller 20 (normally an unused one), mark end of the song with
a change of the controller 21 (unused as well). Start log like usual,
then start playback - only a portion of the song between these two
controller changes will be logged, and the logging will stop automatically
when it will reach the controller 21 change. 

There is also controller 22. It can be used for time sync markers in the 
external software, outputting 255 into log. 

There is also controller 15. It can be used to split exported stream into
multiple files. When such controller is reached in the track, currently
open log file closes, and a new one under the same filename with a part
number added gets opened.

The log format is:

a byte of number of frames (0 end of track, 1..254 frames, 255 marker)
a byte of waveform, 0 means rest note
a byte or two of frequency divider (only when waveform is not 0)

The number of bytes for the frequency divider depends on the frequency
range mode (8 or 16 bit).



License 

The plugin and its source code comes without any warranty. You can
redistribute it and/or modify it under the terms of the WTFPL. See 
http://www.wtfpl.net/ for more details. 



History

v1.1 20.10.22 - Controller #15 support for multipart logging
v1.0 19.08.22 - Initial release




Mail:	 shiru@mail.ru
Web:     http://shiru.untergrund.net
Support: https://www.patreon.com/shiru8bit