Documentation for Pulse Dream v1.06
(C) Fredrik "Eagle" Larsson 2006, 2007

"Cooler than Tetris, more ol' school than Space Invader
and more pulse than C64! - Pulse Dream, PC Speaker Synth!"

Table of contents:
-------------------------------------
(Help from Pulse Dream)
Keyboard Help
Synthesizer Help
Config Help
Generic Help
FAQ
Troubleshooting
Version History

(Exclusive for this help document)
Suggestions to Arpeggio Synthesis
Known Bugs
System Requirements
Hacking the Frequency Table
Bug Reports

Help from the Program itself:

-------------------------------------
Keyboard Help

The keyboard has 2 modes and looks different depending on your
current configuration and synthesizer setup.

The two modes are ModPlug Jazz and the standard Piano setup.
The ModPlug Jazz mode is for those who are used to ModPlug
Tracker and puts the keys of one octave on a single row.
ModPlug Jazz mode supports two 2 octaves at once, although the
second octave only stretches up to A.

The default piano mode places the keys on the keyboard the
same way it does on a real piano.

By pressing shift, you can transpose the keys one octave up.
It will only work in Piano Mode due to performance reasons.
As result, you may not use Caps Lock or Shift when using
the ModPlug Jazz mode. Sorry!

Pressing the 1-7 keys will switch the current octave.

In case you have the Effect Generator or the Drum Generator
turned on, press Q, W and the keys further to the right to
play those silly bleep drums and laser beam sounds.

While in the keyboard mode, press 0 to exit back to main menu.

-------------------------------------
Synthesizer Help

With the synthesizer, you can customise the synth to sound the
way you want it. The synth can handle glissando, arpeggio,
vibrato, drum/effect generator, ticks and hold key. An advanced
arpeggio synthesizer is also available. Check page 4 for this.

Click A, B, C... et cetera to change the settings on related
option. Some features can't be activated simultanously, so
in case you activate something while a feature, that can not
simultanously with the newly activated is activated, the last
feature will be deactivated to make room for the new feature.

Glissando will slide the pitch to the next note. Depending on
your current tick setting, this will be in different speeds.
Current octave also affect the sliding period.

Arpeggio will shift the note upwards or downwards depending on
your settings. Chord will simulate a chord and triple octave
will jump upwards 1 octave on 2 steps and back to current note.
With the advanced menu you can customise your own arpeggio.

Vibrato will vibrate the pitch, like a violin or singer can do.

Turning on the Effect/Drum generator will allow you to play
sound effects/drums of varying quality. These are aligned on
the row of keys which starts with QWERTY. Press these and try
the out the various sounds. 

The duration/ticks option sets the global duration of every
sound. However, the lower the duration, the more obvious the
note delay is on slow machines (4Mhz and so on).

Key Hold, when turned on, will keep playing the note until
a drum is played or a new note is played.


Here comes an exciting part of this synth, the arpeggio
synthesizer! This feature can be accessed by press the 1 key.
The arpeggio synth can be turned on by pressing A in this
menu. A slight vibrato can be used together with this synth.

The arpeggio synth has 4 sliders. These sliders determine
transpose the arpeggio does upwards. Changing these values
can result in all kinds of nifty results, so don't be afraid
to experiment with them.

An additional slider determines the vibrato depth.
However, this is only a slight vibrato and is not as noticeable
as the standard vibrato keyboard is but can still provide with
a nice effect. You must turn vibrato on for this value to have
any effect.


With v1.03, a custom drum generator was included to be used
together with the arpeggio synthesis. Press 2 to go to this
menu.
 
There are one button to turn on this feature and 10 knobs
for changing the 5 frequencies in the drum. Pressing the key
for these knobs will increase the frequency value with 10 until
this value is more than 4000.

The global duration/tick settings affects the speed of these
custom drums to allow for experimentation.

-------------------------------------
Config Help

The config page has two options: Key Allocation Mode,
the Sliders Option, save and load config file.

The Key Allocation Mode option allows you to config how the
Piano keys will be put on your keyboard. Default is your
standard virtual piano key setup. The ModPlug Jazz however
uses the key allocation known from ModPlug Tracker where the
keys of a whole octave has been put on one single row.
This setup can be very useful for some while most people will
find the piano setup more familiar and easy to use. Try which
fits your taste best.

The save and load config option allows you to save your current
settings, drums and arpeggios.

-------------------------------------
Generic Help

Can't figure out what all these sliders and knobs means in
the synthesizer? Don't understand what arpeggio and the
other music jargon means? This section will try to explain
all that beginning with the synth part.

On an ol' school analog synth, configurations to the sound
done through sliders, knobs and sometimes buttons. Pulse
Dream attempts to simulate this unless you have turned this
feature off in the config screen.

Off (/) On <- This is a knob, a round button that could
turned clockwise or counter-clockwise to set things on
or off. Currently, this knob is set to On.

----[]---- <- This is a slider. By moving it to the left
or right you could e.g. control the volume of the synth.
This is quite self-explainating what it does.

(_)  _
|_| (#) <- This is how the buttons looks in Pulse Dream.
The left button is off and the right is on.

Now, here comes the glossary:
Glissando: This is the effect of sliding the pitch of an
instrument. A common feature on string instruments.

Arpeggio: Arpeggio is the action of transposing a note
up or down in a short period, often to simulate a chord.
This was common practice on old sound card as these could
handle more than perhaps 3 sounds at voice like e.g. the
SID chip in the Commodore 64 did.

Vibrato: The vibrating of a sound. Pulse Dream simulate
this effect by changing pitch up and down a bit.

Ticks: This is the duration timer used in your PC. In
one second, there are 18 ticks. 18 ticks = 1 second.

Here comes an explanation of what the various effects and
drums are supposed to sound like.

Drum Q = Bass Drum -- Effect Q = Something going up
Drum W = Snare -- Effect W = 'Where did my parachute go?'
Drum E = Pedal Hi-hat -- Effect E = Rocket
Drum R = A very realistic cymbal --  Effect R = Funny siren
Drum T = Closed Hi-hat -- Effect T = Pinball score!"
Drum Y = Low tom -- Effect Y = Wind (think Final Fantasy VI (JP))
Drum U = High Tom -- Effect U = Laughter (Huahuahuahua!)

-------------------------------------
Frequently Asked Questions

Q: Is Pulse Dream good for Live performance?
A: Maybe, maybe not. When doing live performance, you are likelly
to need to change a lot of configurations while playing. Pulse
Dream was alas not programmed for that, my intentions were to
create a PC Speaker synth for playing around back home.

Q: Will Pulse Dream be ported to MacOS X?
A: Haha, yes. In fact, it has already been done. However the
Mac version runs by using Kindley Rat BASIC and does not
produces Pulse waves. Instead it's called Sine Dream and
plays sine waves, which kind of lacks a bit of charm...

-------------------------------------
Troubleshooting

Prob: You can't hear anything.
Solut: You either have no PC Speakers or your PC Speakers are
of piazo models, which are not compatible. Try downloading
DOSBox and drag and drop Pulse Dream on it.

Prob: There's this delay between every note, what do I do?
Solut: You're CPU can't handle this program (amazing!). Upgrade
your CPU or, in DOSBox, press Ctrl+F12 a couple of times.

Prob: Your synth is pure crap!
Solut: Your brain is too small to understand the power of
the monophonic pulse wave of the PC Speaker. >:P

-------------------------------------
Version History

v1.00 - Initial release!

v1.01 - Added a wind effect and fixed the problem with the
vibrato of the arpeggio synth.

v1.02 - Removed duplicates of code and replaced them with
subroutines, which reduces RAM usage and size.

v1.03 - Included custom drums, fixed spelling/gramar errors
in the help section and fixed a synth menu problem.

v1.04 - Allowed decreasing/reseting custom drum values and
included effects/drum generator and custom drums with all
settings. Eliminated a problem with the glissando.
Fixed several minor bugs and added a page in Generic Help.

v1.05 - Fixed a well-known playing bug.
Added 3 more keys in the piano.
Added a laughter effect and two toms.
Added save/load config support.

v1.06 - Response delay now halved.
Glissando and vibrato now reacts directly to new note.
Added a frequency table (can be modified, go go h4xx0rz!).
Program now smaller thanks to optimisations.

-------------------------------------
Suggestions to Arpeggio Synthesis

If you'd like some hints to what the Arpeggio synthesizer can
do, try following combinations of Arpeggio:

Hard Strings:
C-12 D-7 E-0 F-2

Flute:
C-1 D-3 E-3 F-0

70's Chord:
C-0 D-12 E-9 F-5

Things running around:
C-12 D-1 E-3 F-10

SID Snare:
C-3 D-4 E-11 F-0

Bird Twittering:
C-3 D-1 E-2 F-0

Space Men Talking:
C-3 D-4 E-5 F-0

-------------------------------------
Known bugs:

* Loading a config before having saved one will generate an error and stop execution.
* If the PDMFQTAB.CFG is missing, the program will generate an error and quit upon start.

-------------------------------------
System Requirements:

PC Speakers or PC Speaker emulation
A 8086 CPU or compatible/later with at least 4Mhz
64kB RAM
A screen and a keyboard

-------------------------------------
Hacking the Frequency Table.

The frequency table used in Pulse Dream to ensure that when you play the tone C4 actually is C4 is stored in a file called PDMFQTAB.CFG. The table is stored in simple text with 4 spaces for each value. This means you can easily alter the frequency table to allow for strange sounds just using NotePad or any other text editor you have lying around.

However, if you choose to alter the frequency table, you are also taking a risk. The first risk is that your new frequencies may be illegal and will therefore crash the program. The second is that you may save the config incorrectly or otherwise corrupt it which will also generate an error. The third is that you may lose the original frequencies.

For your safety make sure you read my short guide to toying with the frequencies step-by-step.

1. Open the config file in preferably an hex editor or Notepad if you must. If you have not already, save a backup copy of the original unmodified frequency table.

2. The frequencies are stored as 4 blanks or numbers followed by carriage return and line feed (new line, simply put).

When you've opened the file in a text editor it should look like this:
Pulse Dream Frequency Table
v1.06
  37
  37
  37
  39
  41
  44
...

3. You may alter the frequencies however you want given that you only enter legal values. Legal values are 37-16000. But for your safety and to spare your ears, use a maximum value of 9999 as your frequency. To enter a 5 digit value, you just have to add that extra number. Don't worry, Pulse Dream uses text mode and not binary mode.

4. Don't alter the two first lines with the version numbers as Pulse Dream check these numbers to ensure that it has not loaded e.g. a Pulse Tracker config file. Also, don't enter anything but numbers or blanks as values as Pulse Dream will generate an error and crash if it finds e.g. a "T" in the middle of a numeric value.

5. When you have entered the values you want, save the file and run Pulse Dream. However, you may get an error if you don't have an EOF character (looks like an arrow in NotePad) in the end of the file.

6. Go nuts on the keyboard and notice how Pulse Dream has gone mad. Or alter your friend's frequency table and see how he or she reacts!

-------------------------------------
Bug Reports:
Send any bug reports (read the known bugs section first, please)
to: chessmasterz89[at]hotmail[dot]com
Also, check http://www.eagleworld.tk for possible more info.