Sound and Music - All About The IIGS' 5503 Ensoniq DOC

Converted to html - 3/26/96

Status: FreeWare - Copyright (c) 1995 by Charles T. Turley, Ph.D.

SOUND GS - Part 6

One of the most facinating, remarkable and unique features of the Apple IIgs, is
its ability to create incredibly realistic sound effects and music. The IIgs
does this because, its sound system is controlled by the powerful Ensoniq Digital
Oscillator Chip (DOC), the same chip used in the professional-quality Mirage
Digital Sampling Keyboard and the Ensoniq Piano.


The 5503 Ensoniq Digital Oscillator Chip (DOC) has 32 sound oscillators. Each of
them are capable of making an independent sound. Two oscillators paired up are a
generator. The paired generator arrangement is favored by most IIgs sound/music
programs, because that arrangement offers greater flexibility with better sound

The DOC produces 8-bit waveforms, with a center line at $80 (128 decimal).
Reserved for 'stop' is $00 or (0 decimal). If the sample value of 0 is
encountered by a DOC oscillator, it will halt immediately and will not produce
any more sound. The DOC also has an 8-bit volume register for every oscillator
using a linear slope. The dynamic range of the DOC (the 'space' between the
softest and loudest sounds which are produced) being approximately 42 dB.

Each oscillator has a 16 bit frequency register, ranging from 0 to 65535. In the
normal DOC configuration, each step of this frequency register increases the play
rate by 51 Hz.

Oscillator Modes

When oscillators are paired as generators, four possible modes can be used. These
four modes as termed, are listed below.

(1) Free (Free-run) (Loop) : The oscillator simply plays the waveform and stops.
No interaction with it's 'pair' occurs.

(2) Swap (Loop) : Only one oscillator of the pair is active at a time. When one
stops, its pair starts immediately.

(3) Shot : The oscillator plays the waveform and if it reaches the waveforms end
without encountering a zero, it starts over (loops) at the beginning.

(4) Sync (AM): One oscillator of the pair modulates the volume of the other
paired oscillator with the waveform it's playing. Unique and very effective.
But, not commonly used.

Note: To listen and view these four modes (all together), load and play the NTGS
(type2) music module EXAMPLE 'SHt2.4M'. You canload and play it via the
NTGSt2 Player v2.0.1, accessing the control panel during the modules play,
(pressing the keys; Apple-Control-Esc), select the CDA 'EnsoniqPeeker v1.0'.

This EXAMPLE composition (which is a radically enhanced 'NTGSt2' modification of
the original 'FTA Space Harrier DEMO' SoundSmith composition), certainly is not
(at all) presented, for its audio composition beauty (as it presents everyconceivable audio
quirk, taxing the Ensoniq to its limits).

But, rather to show you with audio and visual review, the entire ranges of the
IIgs and the Ensoniq DOC abilities, limits, functions, modes and quirks. You'll
note when viewing it, as it plays via the NTGSt2 Player v2.0.1 and using the
Ensoniq Peeker v1.0 CDA, that it actually commands the Ensoniq DOC to use 31 of
its 32 total ocillators, leaving only one of its 32 oscillators 'Free', for

Current DRAM Restrictions with the IIgs

Oscillators play waves stored in up to 128k of DRAM. The Ensoniq has a refresh
system design, built-in for it's own use. Even though the Ensoniq 5503 DOC is
designed to have and address 128k of DRAM, Apple only supplied 64k of DRAM for
the DOC, in the IIgs (this is known as the DOC RAM).

Note: It's possible to upgrade or replace the 64k DRAM with 128k of DRAM.
However, newly designed software would have to be developed, to address and
efficently use such.

The output of an oscillator can be directed to any one of 16 possible channels.
The Apple IIgs only makes 8 channels avalible (via the 3 bits on the sound
expansion molex connector). All of the IIgs' currently available stereo cards
limit this to 1 bit, or two channels.

With the properly designed software, the Ensoniq DOC can generate up to 32
definable sounds simultaneously. It can also support up to 32 special
(audio/sound) effects. The frequency of these sounds can be varied over a wide
range and their volumes can be set to any of 256 discrete levels.

As a result, it's possible to mimic in detail, the acoustical behavior of any
musical instrument. The DOC is also capable of sampling incoming audio signals,
including voice samples, and converting them to digital form.

Note: Maintaining compatibility with other Apple II models, the GS also lets you
create simple sounds by toggling the GS speaker with a soft switch at $E0C030.
You can use the SysBeep function in the Miscellaneous Tool Set to beep the
speaker using this technique. SysBeep requires no parameters.

Programming and minipulation of the Ensonic 5503 - DOC

Based largely on the content of 'The ProDOS 16 Operating System - Chapter 11',
this part 6 of 'The GS Sound Continuum' takes a close look at the Ensoniq DOC and
examines ways of manipulating its internal registers to create sound and music.
It discusses using the Sound Manager to communicate with the DOC and to play back
digitized sound patterns. It also relates the Note Synthesizer's ability to play
musical scores using different simulated instruments.


All sound-control commands are sent by a program running in the 65816 Central
Processing Unit (CPU) address space to the Sound General Logic Unit (GLU). The
GLU passes the sound-control commands on to the sound circuitry controlled by the
Ensoniq DOC.

Because the Ensoniq is isolated from the 65816 by the GLU in this way, it can
generate sound independently of the current application running in memory. Thus,
The IIgs has the ability to have background sounds or music playing, as you type
within a word processing application program, for instants. That is, the
application can perform other tasks while sound is playing in the background.

Sound GLU

The SOUND GLU contains four registers for communicating with the DOC as follow by
Register Name and Address; Sound Control ($C03C), Data ($C03D), Address Low
($C03E) and Address High ($C03F).

The Sound Control register is the more complex. The lower four bits control the
output volume level of the audio amplifier. The GS sound tools put the volume
level (as set by the Control Panel) into these bits before they access the DOC.

Bit 7 is a status bit that indicates if the DOC is ready to respond to read and
write operations. It's ready if this bit is zero (0 = DOC is free) and (1 = DOC
is busy).

Bit 6 controls whether the value in the Sound GLU 16-bit address register refers
to an address in the DOC's special 64K RAM waveform buffer (bit = 1) or to DOC
register number (bit = 0).

Bit 5 controls if the GLU address register is to increment automatically after a
data register access (bit = 1) or if it is to stay the same (bit = 0). Setting
the auto-increment bit makes it easier to access a range of registers or RAM

Note: The balance of technical/programming information, concerning the Ensoniq
5503 DOC, continuing with the (Bit 4 controls on down, and all materials of the
contents from 'The ProDOS 16 Operating System' - Chapter 11), will be included in
the next series of SOUND GS - Part 7.

Ensoniq 5503 DOC Swap Mode Anomaly

The IIgs' Ensoniq Digital Oscillator Chip (DOC) will ocassionally perform an
anomaly and insert a spurious zero-crossing byte into the output sample stream.
The properly designed samples waveform might mask the anomaly. If it does not,
you might hear intermittent clicks or a more pervasive "static." This discusses
such situations when the DOC produces this spurious zero crossing, with methods
to avoid or mask this undesirable anomaly.


The Ensoniq DOC in the Apple IIgs as a microprocessor is dedicated to
specifically to producing sound. As such, the DOC constantly scans its sound
oscillators, proceeding from lower numbered to higher numbered ones. The DOC
updates its signal output level for each active one matching such, as indicated
by the oscillator's current sample byte.

An oscillator can operate in any one of several functional modes, as covered
above. However, this concerned only the swap mode, where two consecutive
oscillators are considered as a single generator. The low numbered oscillator in
the pair is always even.

For example, the pairs of oscillators 0 & 1, 2 & 3, ... , 12 & 13, and 14 & 15
are thus constituted generators. The IIgs Sound Tool Set (FFStartSound) call in
particular, configures the oscillators used to operate in swap mode. In swap
mode, the even numbered oscillator plays its waveform first, halts its own
playback, then starts its partner which also plays its waveform, halts its own
playback upon exhausting its waveform, and restarts the even-numbered oscillator.

Any time between the start of any particular FFStartSound call and the time that
oscillator finishes playing a wave, the Sound Tool Set interrupt handler might be
busy, transferring waveform information from the IIgs main RAM to the dormant
oscillator's buffer in DOC RAM. Since one oscillator is producing sound, as the
Sound Tool Set interrupt handler is transferring waveform information to the
other oscillator, you may use a generator pair to produce continuous sound of
arbitrary length, and you are limited only by the amount of memory you can devote
to the waveform in the main RAM.

Each oscillator draws its output samples from a dedicated buffer in DOC RAM, the
size and location are specified by parameters to the FFStartSound call. The
maximum size for an oscillator buffer is 32K. But, because buffers may neither
coincide nor overlap, the practical maximum might be lower, when more than one
generator is active. As an example, if four generators (eight paired
oscillators) are active simultaneously, the maximum buffer size is 8K, since
eight non-overlapping buffers of 8K each would occupy the entire 64K available in
the DOC RAM.

The Problem

Whenever a swap occurs from a higher-numbered oscillator to a lower-numbered one,
the output signal from the corresponding generator temporarily falls to
zero-crossing level (silence). This anomaly does not occur during swaps from
lower-numbered oscillators to higher-numbered ones. The spurious level change
lasts no longer than a single sample period, then the interrupted waveform
resumes. Even this tiny glitch in the output, can be audible as a pop or click.

The further away the waveform is from zero crossing when the swap interrupts it,
the louder your ear can perceive the pop or click. When high to low swaps occur
with great frequency, the pops and clicks happen so often that they are perceived
as gentle, but pervasive, static.


There is no ideal solution to the problem of signal interruption in swap mode.
This problem is an anomaly of the DOC design. No DOC updates are coming from
Apple, for the IIgs. We just have to find methods to work around thisvDOC design
problem. So, three logical solutions follow, for mitigating the audible damage
to the output waveform caused by this Ensoniq 5503 DOC design problem.

Minimize Oscillator Swaps per Unit Time

The more often swaps from high numbered oscillators to low numbered ones occur,
the more obtrusive the brief signal interruptions will seem. To minimize these
signal interruptions, make the oscillators play for longer periods of time before
swapping to their partners.

That way, they will play at slower output sample rates, use larger buffers in DOC
RAM, or use the two in tandem. Commensurate with the number of active generators
you wish to use and the level of output signal fidelity that you desire. Always
specify the largest DOC buffer size and the lowest output sample rate that you
possibly can.

A large number of active generators implies a very small maximum buffer size for
any particular oscillator. So you should always try to minimize the number of
generators that are active at any one time. The clicks of signal interruption
begin to blend into highly audible static when you specify buffers smaller than
8K for use at the maximum-fidelity output sample rate of about 26 kHz.

Note: The DOC supports greater sample rates, but these rates are limited by the
output filtering on the IIgs. This currently, permits no greater signal fidelity
than 26 kHz rate. Thus, output fidelity must suffer, or signal noise must
increase, when more than four generators (eight oscillators in swap mode) are
operating together.

Avoid Silent or Quiet Passages

The signal content of properly designed waveforms, can hide the additional noise
caused by the "swap-mode anomaly." The more complex and louder a waveform, the
less your ear will perceive the brief interruption that occurs as a higher
numbered oscillator swaps to a lower numbered one. Like it or not, pop and rock
music is far less susceptible to this problem than classical, folk, or jazz
pieces. Because of their composition and standard music style/design, the
classical, folk, or jazz pieces, include many quiet passages.

Using signals, that naturally contains a large amount of "pink noise," as
examples; rainstorms, waterfalls or the surf at the beach, can mask the anomalous
noise altogether.

Arrange Swaps to Occur at or Near Zero Crossings

If the high-to-low swap occurs at times when normal output signal levels sits at
or near the zero crossing, a swap will cause little or no audible damage to the
waveform. When reproducing arbitrary sampled sound, it's almost impossible, to
insure the output signal level is near the zero crossing.

When constructing long waveforms for playback, you may sidestep the chip's
anomalous behavior. Ensure waveform values lie at or near $80 at the end of every
waveform segment, where a waveform segment spans twice the length of one
oscillator buffer.

For example, if you specify a buffer size of 4K, make sure that your constructed
waveform crosses the baseline after every 8,192 samples, and for 16K buffers,
make sure that the waveform makes a zero crossing after every 32K.

The length of the waveform segment should be twice the buffer length, only if
you're going to reproduce the waveform exactly once per FFStartSound call. It
may be advisible shortening the length of the waveform segment. Do it to exactly
the specified DOC buffer length if you use the nextwave_start parameter in the
FFStartSound parameter block.

This invokes automatic looping of the waveform. So, you may need to arrange for
twice as many zero crossings in your constructed waveform in the looping case, as
under normal circumstances. Since, subsequent repetitions of the waveform during
the single FFStartSound call may begin with either the even or odd oscillator.

This, is dependant on which member of the pair was active, when the previous such
repetition ended. If the playback of a waveform starts with the odd oscillator,
then the odd to even swaps will occur at different points in the waveform than
they would, when the playback starts with the even oscillator.

Final Note: The use of larger buffers causes a progressively longer disabling of
interrupts while the Sound Tool Set moves the waveform into the DOC RAM. A music
player (such as the NTGSt2 Player v2.0.1), which enables 31 of the total 32 DOC
(available) oscillators, using buffers of 2k or 4k and has absolutely no
interrupts, is the best modeled and designed player, to take advantage of, mask
or correct all the DOC design anomalies and problems.

Even such a unique designed player, can still allow some of these anomalies and
problems to be noticable. Because, the Ensoniq 5503 DOC, as designed and used
within the IIgs, never presents and plays music and/or sound exactly the same,
every time!

Further Reference; Apple IIgs Toolbox Reference, Volume 2 Apple IIgs Hardware
Reference The ProDOS 16 Operating System, Chapter 11

For Additional Technical and/or Development Support call Apple's following
numbers; 1-800-257-1439 or (408) 974-4897

Return to the GS WorldView Index 'Parent Directory'

All brand and product names are the trademarks and/or registered trademarks of
their respective holders.