YACH*PMS by shiru8bit




About

YACH*PMS is a music tracker designed for a very obscure sound device 
called MuzCell. 

The tracker comes in two flavors, a MS-DOS build that works with the 
actual device plugged into ISA slot, and a multiplatform SDL port with 
built-in MuzCell emulation that is provided as a Windows build only, but 
can also be compiled from the source code for Linux and other systems. 

YACH*PMS is a short for YACHeika Zvukovogo Sinteza (the original name of 
the device) - Programmable Music System. It was a joke working title of 
this project, and I decided to just stick with it, because I'm lazy yet 
want to be fancy, and because the name does not really matter, but it 
needs to be unique enough to make it more searchable with the search 
engines. I also call it the MuzCell tracker, as at the moment there is 
only this one. 




MuzCell overview

MuzCell is a very obscure sound device, initially designed for a Soviet 
Apple IIc clone by enthusiasts from the Novosibirsk State Conservatory 
of (ex-) USSR, circa 1990. In 2022 an open source replica that has been 
adapted to work with any ISA-bus equipped IBM PC compatible has been 
created by Tronix286, making it much more accessible for a wider 
audience. 

The card was not targeted for multimedia or video games use, it rather 
was intended as a simplistic programmable music synthesizer for 
computerized music education needs. However, its design is really 
uncommon for a computer sound device, it is somewhat in between very 
simple sound chips and some early entry-level digital music synthesizer 
keyboards of the past. So far the attempts to find a similar design that 
could've been the source of the inspiration to the MuzCell creators were 
unsuccessful. 

With its rather limited and very basic resources that take careful 
management to achieve a good sounding result, MuzCell is much closer to 
the chiptune realm than to a big time sound synthesizer. The YACH*PMS 
software has been created to make it possible to apply common chiptune 
and tracking techniques to the card’s resources, and to reveal its 
hidden potential. 

MuzCell is not a sound chip by any means. It is a sound card/board 
rather, made of quite a number of digital chips and analog components. 
Its architecture is mixed digital/analog and can be seen as three 
functional parts: a digital square wave generator, a percussion 
generator, and an analog path with three band filters and a pseudo 
stereo output. 

The digital tone generator at its heart is a couple of the 8253 PIT 
chips that are used to generate a square wave exactly as the PC Speaker 
does. So basically you get six PC Speakers at once, with all of its 
usual limitations - just a square wave without a volume control (unless 
a major software trickery is applied, which is sure potentially possible 
on a PC compatible). 

The sound source then gets into an analog amplitude shaper that creates 
two different volume levels and a few types of very basic volume 
envelopes. There is no direct digital-precise volume control, like in 
all sound chips. However, there is an extra low pass filter that 
presumably adds 5db for the range up to 600 Hz, but in practice it just 
acts as a gain booster with little effect on the timbre. The volume 
envelopes are a short staccato-like sharp attack, short decay one; a 
slow attack one; and a sustained tone. The amplitude accumulates 
similarly to the FM chips, so the slow attack will turn into a constant 
volume if there are no gaps between the notes. 

After the amplitude shaper the signal goes into the most prominent 
feature of the MuzCell, a set of passive analog filters. It is nothing 
like the SID filter, these are not resonant and their parameters not 
software controllable at all. You can only route the outputs of each of 
the tone channels into each of the filter bands - a low pass, mid pass, 
and high pass. So you can route a channel into all three main filters, 
and get a square-ish full tone, or cut any of the ranges, changing its 
timbre quite a lot, which also adds a kind of control over the percepted 
volume. The card never plays a pure square wave, it is always filtered a 
bit due to the fiter. 

Another major feature is the percussion generator. It provides two 
channels of analog-like percussion. It is not fully analog, though, as 
the noise source is a LFSR based one (a very basic single CD4006-based 
implementation, much similar to the TR-909 one actually), which is a 
typical solution for all digital sound chips, but the frequency and 
amplitude shaping path is an analog one indeed. Amplitude shaper is even 
more basic for these channels, it just creates two volume levels and a 
fixed decay envelope that can also be cut early. 

Unlike the tone, the percussion channels are not equal in their 
capabilities. The first one is intended for things like a kick or snare 
drum, or a tom, with just a minor amount of noise and 8 pitches. The 
second one sounds something in between a hat and a tambourine, it has a 
much more metallic sound with just 4 pitches for its tone component. The 
pitches are not your typical chiptune pitches, instead some kind of 
filtering is applied to the same white noise source. It resembles some 
of the CR range of analog drum machines sounds. 

Last, but not least, there is a rudimentary stereo enhancer on the 
master output that gives a slight stereo separation with phase inversion 
of the source mono mix that is routed to the left and right channels. To
be honest, I'm not sure if the effect is actually present on the HW, as
it is not heard in the recordings, yet it is certainly implemented in
the output schematics.



Bottom line on the card specs:

- Six channels of tone, with some control over the timbre, and a 
rudimentary control over the volume and amplitude envelope. 

- Two channels of percussion that have a limited control over the timbre 
of the sound and a rudimentary volume control. 

- Pseudo stereo output that is actually a mono one without any extra 
controls. No volume, no stereo panning, sounds questionable, if working
at all.


Tracker software with its precision controls allows control of the pitch 
to create fast arpeggios, slides, portamento, and other typical chiptune 
tricks, including software envelope driven control over the filter 
routing. This helps to create percussive sounds on the tone channels in 
addition to the actual percussion hardware. 

There are software envelopes for the percussion section too, allowing 
you to manipulate the pitch and squeeze a bit more out of it. 

While it is outside of the scope of the YACH*PMS, it is still worth 
mentioning that there is even more potential to unleash. It would 
exploit the power of a PC CPU rather than the card itself, though. 
Basically that’s the good old PCM-through-speaker trick that turns 
8253 into a kind of 6-bit PWM DAC, but in case with MuzCell it could be 
applied to the six independent channels that can then be used to play a 
waveform or a sample with some degree of software volume control, and 
this signal will also pass the analog filters. 




Editor overview

The editor follows the traditional design of a music tracker with a 
pattern editor, an order-list, and an instrument editor. It is 
controlled with the keyboard only, providing many hot keys to perform 
various actions. The mouse is not supported. All numbers in the editor 
are decimal, hex is deliberately left out, just like all my trackers in 
a decade. 

The editor saves song and instrument data in the form of a plain text. 
You can open and edit it with any text editor if needed. Recommended 
file extensions are *.YMD for songs and *.YMI for instruments. You can 
also load a module through the command line when starting the program, 
like YACHPMS SONG.YMD 




Keyboard layout

The editor features numerous hot keys to access various functions:

F1					Quick help page
F2					Save song/instrument			
F3					Load song/instrument
Ctrl+F3				Clear song
F4					Instrument editor
F5					Play song from current order position
Ctrl+F5				Play song from the beginning
Shift+F5			Play current pattern in a loop
F6, Ctrl+Tab		Switch between the pattern editor and order list
F7					Edit song information
F8                  Export WAV file (SDL version only)
F9					Configuration screen
F10					Exit the program

Cursor				Navigate pattern
PageUp/PageDown		Move cursor 16 rows up or down
Home/End			Move cursor to the beginning or end of a pattern

Ctrl+PgUp/PgDown	Navigate the order list up/down

Enter      			Play the song from current row
Esc        			Mute all sounds, if any
Ctrl+1..7			Mute a specific channel
Ctrl+0				Unmute all channels
Ctrl+~				Make current channel play solo

Num */ or Shift+[ ] Change octave
Shift+0..9  		Select octave
~ ~+Shift   		Change autostep
Num/Ctrl +- 		Change global speed
Ctrl+[ ]         	Change measure

Shift+navigation	Make a selection
Ctrl+Z				One-step undo for a recent pattern change
Ctrl+X				Cut a selection
Ctrl+C				Copy a selection
Ctrl+V				Paste a selection
Ctrl+E				Expand a selection by inserting an empty row
                    between all rows
Ctrl+S				Shrink a selection by deleting every other row

Delete				Clear cursor position or selection
Ctrl+Delete			Clear row
Backspace 			Delete position shifting all following rows up
Ctrl+Ins/Back		Insert/remove row shifting all preceding rows down
Ctrl+UDOK			Transpose a selection a semitone or octave higher
                    or lower

Ctrl+A				Select contents of the whole pattern
Ctrl+L				Select contents of the current channel

Specific for order list:

Insert				Insert a position into the order list with the
                    same pattern number.
Shift+Insert		Insert a new empty position into the order list.
Ctrl+Insert         Insert a copy of current position into the order
                    list.
Ctrl+Up/Down		Drag order list position up/down.


The notes are entered the traditional tracker way. If you never used it, 
imagine that the PC keyboard represents a piano keyboard, or even 
better, an organ. You have two piano registers one above another, 
covering up two and a half octaves range there: 

2 3 5 6 7 9 0 Q W E R T Y U I O P 

S D G H J L : Z X C V B N M < > 

The one at the bottom is the current octave one, it starts with note C. 
Current octave is displayed at the right of the screen. You can change 
it with / * keys, or set it directly using Shift+0..9. The top register 
also starts from C, but it is an octave higher than the current one. 

To enter a Key Off event that stops the currently lasting note, use A or 
1 key, they're both doing the same thing. It will be displayed as R-- in 
the song text. 




Pattern editor

The patterns has a fixed length of 64 steps, but can be cut early.


A row of a pattern has the following format:

Rw Sp Tone 1 Tone 2 Tone 3 Tone 4 Tone 5 Tone 6 PH

.. .. ...... ...... ...... ...... ...... ...... ..

Rw is a row number 00..63, pattern can be cut early
Sp is a row speed, 2 to 99 (fastest to slowest), which remains set for
   all following rows. It can also be xx, which represents a pattern
   break. It is set by pressing the Space key.
   
   
Then six note fields follow, one per channel. Their format is:

NNNEDI

NNM is a note, like C-1, D#2, etc
E  is an effect type, which can be set wit -+UDVP keys
D  is effect depth, it defines strength of an effect
I  is the instrument number, which can be 1..9 and A..Z, making 35
   instruments total

The last column are the two percussion channels, which is Percussion
and Hat. You can just enter an instrument number there to trigger a
percussion sound.




Pattern effects

There is a very basic experimental system for pattern effects 
implemented in the tracker. The effects are used to control the pitch. 
You can make slides up, down, or to a specific note, add vibrato. 

The effects can be displayed by the keys they are entered with, or with 
symbols. It can be changed in the Config window (F9). 


+- detunes this and all following notes by the set number of cents

UD : Slide up or down, it will be applied to all following notes in a
     channel, the depth sets speed of the slide.
   
V  : Enables vibrato of a specified depth on a channel, the vibrato
     speed is controlled inside an instrument/
   
P  : Portamento to a note, pitch will be gradually changed to reach a
     next note, the depth sets the pitch change speed.


To disable an effect, use it with 0 depth. Slide and portamento effects 
are cancelling each other, so disabling a slide will disable portamento 
too, or vice versa. 

Effects can be applied together with a note or without a note, so you 
can enable vibrato after a note lasts for a while. 




Order list editor

The order list defines the order of patterns that will be played in a
sequence to create a lengthy song.

The order list is called with the F6 key. To return back to the pattern
editing use the same key or Enter.

You can enter 00..99 as a pattern number for a position, and reuse this
number if the same pattern needs to be repeated at some place.

A position can be inserted, deleted, or cleared from the order list
using the Insert, Backspace and Delete keys. When a position inserted,
it uses the same pattern number, but a new empty position can be added
using Shift+Insert, or a copy of the current position with Ctrl+Insert.

A position can be also moved up or down by using Ctrl+Up/Down.

The sequence can be loooped either to the beginning or to any position.
The loop point is set by pressing Space.

To navigate in the order list quickly, without switching back and forth
between the pattern and order list editors there are Ctrl+PageUp/PageDown
keys.




Instrument system

There are 35 user defined instruments in a song, numbered as 1 to 9 and 
A to Z. Each instrument may be used as a tone channel instrument or a 
percussion channel instrument, there are independent sections of 
settings in each instrument for tone and percussion. 

Most instrument parameters are controlled with software envelopes that 
are programmed as text strings in the MML style, much similar to the 
FamiTracker sequences. Although it may seem very hacky and complicated 
at a first glance, it is in fact a very simple and convenient way to 
define instruments. Using it, you can define various interesting 
instruments very quickly, the system is much more flexible than the 
classic ADSR. 

Besides the envelopes, there are some single number parameters.


A quick overview of parameters in an instrument for the tone channels:


Arp   : Semitone-based arpeggio envelope, can be relative to a note
        or absolute.
Pitch : Cent-based (1/20 of a semitone) relative pitch offset envelope,
        useful for vibratos and slides.
Gate  : Turns the PIT oscillator on and off, 1 to enable sound, 0 to
        disable.
LF    : The low pass output, 1 to enable, 0 to disable.

MF    : The mid pass output, 1 to enable, 0 to disable.

HF    : The high pass output, 1 to enable, 0 to disable.
Loud  : Loudness flag, 1 is loud, 0 is quiet.

Vib.Speed : Sets up the pattern effect-controlled vibrato speed (the
            depth is set from the pattern text).
			
Amp.Shape : Selects one of the HW amplitude shapes, in the range of 1..3.
            1 for a sharp attack with short decay; 2 for slow attack;
			3 for sustained tone that has a short decay from a sharp
			attack.
			
Cut early : Sends a key off after a specified number of frames, to create
            shorter sounds (0 to disable). It may come handy to make short
			loud staccato tones with the amp shapes 1 and 3, or quiet slow
			in slow out notes with the amp shape 2.


Percussion channels settings:


Freq : Frequency spectrum envelope, 0..7 for the percussion channel,
       0..3 for the hat channel.
Loud : Loudness flag, 1 is loud, 0 is quiet.

Cut  : The same as Cut early of the tone channels.


You can test instrument sound inside the instrument editor by pressing note
keys for notes and [ ] keys for percussion channels.




Envelopes

Text string of an envelope may contain any decimal numbers, L or | to 
set a loop starting point. Numbers can be followed by *N (N is a number) 
to repeat the same number N times. Envelope timings can be also easily 
scaled with xN, each following number will be duplicated N times. 


Examples for a 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


Arpeggio envelopes contain offsets in semitones relative to the note in 
the song text. The purpose is to create typical chiptune arpeggio-like 
effects, such as one-note chords. It may also have # in front of a 
value, but in this case it means absolute note number in semitones. This 
way you can create pitch independent instruments, like a kick drum that 
plays the same regardless of note. Traditional fast major arpeggio would 
look like this: 


| 0 4 7

Or a slower minor one:

| 0 0 4 4 7 7

Previous one can also be defined like this:

x2 | 0 4 7


Pitch envelope contains pitch changes in 'cents', which considered to be 
1/20 of a semitone in YACH*PMS. It may be used to create vibrato, or 
slides for percussion instruments. This envelope accumulates the offset 
value, so a short looped sequence will produce constantly changing 
output value. 


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

To create a delayed vibrato with the pitch envelope, you can use
something like this:

0*30 | -4*8 4*8

This means keep zero pitch offset for 30 ticks, then decrease pitch by
4 cents for 8 ticks, then increase it by 4 cents for 8 ticks, then loop
back to the pitch decrease. You can think of it like: 


0*delay | -depth*speed depth*speed



The gate and filter envelopes only use zero and non-zero values to
control corresponding bits of the hardware.

The frequency envelope of the percussion channel acts like the arpeggio
envelope, but it is always in the absolute mode. I.e. 0 always means the
lowest pitch.

If there is some syntax error in an envelope, it will be highlighted
with the red color, and an error message will be displayed at the bottom
of the instrument window.




Config

Config screen is a bit different between the DOS and SDL versions.


Common settings:

[E]ffects       - display pattern effects as their corresponding
                  letter, or use pseudographic symbols instead.
[F]ollow song   - follow the order list when cursor moves outside
                  of a pattern boundaries.
[M]ove at play  - move the cursor to the row that is currently
                  playing while song plays.
[R]estore pos   - return cursor back to its original position
                  after stopping the play.
[V]GA 80x25     - switch between CGA 80x25 and VGA 80x50 video
                  modes.


DOS-specific settings:

[P]ort - select a port address of the MuzCell device


SDL-specific settings:

[S]mpRate    - sample rate of the output (affects the WAV export).
[B]ufLen     - audio buffer length, increase if there are gaps or
               static in the sound.
[W]ide sound - stereo enhancer simulation (affects the WAV export).



Emulation

While the MS-DOS version of the tracker is aimed to be used with the 
actual MuzCell card on a MS-DOS machine, there is a SDL version for 
those who are interested in MuzCell, but can't get their hands on the 
hardware. It includes a software emulation of the device, which is 
actually a sample based simulation at the moment. 

The normal way of emulation of the sound hardware with proper digital 
oscillators and filters has been attempted, and it worked in general, 
but due to its analog nature, the sound was much different. It would 
require a lot of tweaking that would take an uncertain amount of time to 
get the sound exactly right. So a simpler but generally less precise 
solution was implemented instead. Still, it sounds much similar to the 
hardware. 

The way the simulation works is that all the filter bands have been 
sampled for a single cycle waveform as a resolution of 4 notes per 
octave. This data gets interpolated between neighbor waveforms, and this 
allows to cover up the filter response range well enough. The bands then 
get added together, just like the real hardware does, and a software 
emulated amplitude shaping is applied. This approach is rarely seen in 
other digital-analog synth emulators, because it is only applicable for 
a very specific design of the sound hardware, and the MuzCell card just 
happens to have one. 

Attention! As the pseudo stereo effect implemented in the actual HW 
sounds questionable, and even more so does my software emulation that
is trying to recreate the intended effect judging by the schematics,
it is disabled by default. You can enable it at the Config screen.

Beware! This piece of music hardware has been never pushed to the 
extremes, so the simulation may be off at some edge cases. 

Beware! Simulation is not perfect. It gives a simiar sound, but it is
not a totally faithful recreation of the harware, it is a first step
towards it rather. You can judge how close it is by the test audio
recordings provided in the /extra/ folder.




License

All my original code in this project comes under the WTFPL license,
which basically applies to the whole MS-DOS build. The SDL build uses
a third party component, though:

dirent.h (c) - Copyright (C) 1998-2019 Toni Ronkko, MIT license




History

v1.02 18.05.22

- Follow song mode was moving the order cursor in a wrong direction.
- When a copied selection is full pattern wide, it inserts regardless
  of the horizontal cursor position.
- Inserting an empty position or copy of current position into the
  order list using Shift+Ins and Ctrl+Ins.
- Dragging an order list position with Ctrl+Up/Down.
- Cursor stays inside the current pattern while making a selection.
- Dots in the pattern replaced with short dash symbol to make it
  less busy and easier to follow the row by the eye.
- VGA 80x50 mode support.
- Cursor pattern transition logic tweaked to make its movements
  easier to follow.

v1.01 15.05.22
 
- Stereo effect has been unintentionally enabled by default in the
  SDL version.
- Percussion levels weren't displayed on the meter.
- UTF8 file paths that include non-latin characters are supported.
- Windows build migrated to VS2017.
- Delele key to delete a selection contents.
- Percussion emulation corrected to properly handle the Key Off.
- WAV export corrected to produce a clean loop transition.
- Minor/cosmetic UI changes. 

v1.0 12.05.22

- Initial release, with all necessary features.
- A MS-DOS version with the direct HW support.
- SDL version with a sample-based MuzCell simulation.




Contacts

mailto:shiru@mail.ru
http://shiru.untergrund.net
https://www.patreon.com/shiru8bit