██████████████████████▄ ▄▄████████████████▄▄ █████████████████████▄▄
████████████▀▀▀▀▀▀█████ █████████████▀▀▀▀█████ ▀█████████████▀▀▀▀▀█████
██████████████████████▀ ████████████████████████ █████████████ █████
████████████ █████ █████████████ █████ █████████████ ▄█████
██████████████ ███████ ███████████████ ███████ █████████████████████████
██████████████ ███████ ███████████████ ███████ ████████████████████████
██████████████ ███████ ███████████████ ███████ █████████████████████▀▀
┌────────── ── ─ -∙· Reality ADlib Tracker ♫ Version 2.0a ·∙- ─ ── ──────────┐
│ │
│ (c)1995-2023 by Shayde, Rogue, & Void. │
| -REALITY PRODUCTIONS- │
: │
· |
:
∙
INTRODUCTION
▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀
Why?
~~~~
Why? Well originally, back in 1995, the reason for RAD's existence was due to
the lack of decent Adlib trackers around. When we wanted to put some nice FM
tunes into our productions we just couldn't find a suitable format that was
small enough and came with player source-code to enable easily integration of
the tune into our intros. And so we wrote our own...
Fast forward to 2017, and we'd noticed RAD had gained somewhat of a small cult
following. However, one of the main criticisms of RAD was that it didn't
support the later Yamaha FM chip, the OPL3, and so was stuck in 2-operator mono
hell. So we set out to give RAD a long overdue update to give it that OPL3
sparkle.
Us being a demo-group player code is, of course, included, and what's more
includes an accurate emulation of the OPL3 chip for those of you that no longer
have an OPL3-based soundcard in your PC. And those of you on Macs that
never got to experience the joys of Adlib music, well, we now have a Mac version
of RAD too!
BTW. if you're not familiar with the term "Adlib", this was a company that
originally popularised the Yamaha OPL2 FM sound back in the early 90s and it was
common for gaming PCs to come with these installed. Though sound cards by
other companies (e.g. Creative) later added sample support and upgraded to the
Yamaha OPL3 chip, the FM synthesis parts were nonetheless billed as "Adlib
-compatible". The Adlib company is now long gone but their name is still
used to this day to refer to old-school FM synthesis on the PC. RAD came
out when the original Adlib cards were still popular, hence the name.
What Does It Do?
~~~~~~~~~~~~~~~~
RAD, as with all old-school trackers, is a program that allows you
to author musical arrangements. It was based more-or-less on Protracker (on
the Amiga) which is the model that most music trackers seem to be based on.
Tracker tunes are made up of three main components:
* Instruments
* Order list
* Patterns (tracks)
Essentially your patterns will hold the notes of your tune, where each note is
played using an Instrument, has various Effects applied to them, and are pieced
together into an Order List that orders the play-back of your patterns.
RAD 2 has the following features:
* OPL2 and OPL3 FM support
* Up to 127 separate instruments (up from 31 in RAD 1.1)
* Up to 100 separate patterns (up from 32 in RAD 1.1)
* Up to 128 patterns in the order
* 9 channels
* Compact tune file size (even smaller than RAD 1.1)
* Innovative "riff" system
* Easy to use
INSTRUCTIONS
▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀
Starting RAD
~~~~~~~~~~~~
There are separate executables for each OS supported by RAD 2.0. For MSDOS 3.3+
start RAD as follows:
RAD<enter>
For Windows users, double-click on the RADW or RADW64 icon.
And for our Mac users, just double-click on the RAD app.
You will then see the main RAD screen with credits information in the lower
half. Press a key to clear the credits window.
Obtaining help while using RAD
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Being an old DOS-style application RAD relies a great deal on the keyboard
and you won't get far without learning a few important keys. To make
learning these keys easier you can press "?" or F12 to bring up a quick
help list of the keys recognised by RAD.
However, the non-DOS versions of RAD do have a degree of mouse support. You can
click and drag on parameters to alter them, and you can move between parts of
RAD by clicking. You can also click within a pattern to move the cursor.
Layout of RAD
~~~~~~~~~~~~~
As tracker tunes have three main parts, RAD's screen is also split up into
three areas corresponding to those parts. In the top half of the screen in the
left-hand window is the Instrument Editor. To the right of this window is
another thinner window that is the Order List Editor.
The entire lower half of the screen is (as in most trackers) the Pattern Editor.
The first key to know is the " ` " (back tick) key. This switches between the
three areas of the screen. You can only be using one area at a time.
When you first enter RAD, you start off in the Pattern Editor. You can switch
to a full-screen display of the pattern editor using F11. Pressing F11 again
will return to the original display.
Pattern Editor
~~~~~~~~~~~~~~
The Pattern Editor is where you enter the actual notes that will be played. RAD
allows up to 100 separate patterns and each pattern is made up of 64 lines.
Each line has 9 entries corresponding to the 9 Adlib channels. As RAD plays a
pattern it steps through each line at the given speed (described later)
outputting the note in each column (if there IS one) to the corresponding Adlib
channel. Each entry in the pattern is made up of FOUR items, eg.
C#3 2C30
├┘│ ││├┘
└─┼─┼┼┼────── 1) The NOTE that is played. "#" = sharp, "-" = normal.
│ │││
└─┼┼┼────── 2) The OCTAVE of the note. From 0 to 7.
│││
└┼┼────── 3) The INSTRUMENT the note is played in (in Hex).
││
└┼────── 4) The SPECIAL EFFECT, (if any) to perform.
└───────── and the parameter for the special effect.
The note item follows usual musical notation. There are twelve available notes
per octave:
C, C#, D, D#, E, F, F#, G, G#, A, A#, B
You can write a note in a given position in the pattern by pressing one of the
NOTE KEYS, as set out below:
Actual
Note-► C# D# F# G# A# C# D# F# G# A# C# D#
▐██ ▐█ ▐██▐██ ▐█ ▐█ ▐██▐██ ▐█ ▐██▐██ ▐█ ▐█ ▐██▐██ ▐█ ▐██
Keys-►▐██ S▐█ D▐██▐██ G▐█ H▐█ J▐██▐██ 2▐█ 3▐██▐██ 5▐█ 6▐█ 7▐██▐██ 9▐█ 0▐██
▐██ ▐█ ▐██▐██ ▐█ ▐█ ▐██▐██ ▐█ ▐██▐██ ▐█ ▐█ ▐██▐██ ▐█ ▐██
▐██ ▐█ ▐██▐██ ▐█ ▐█ ▐██▐██ ▐█ ▐██▐██ ▐█ ▐█ ▐██▐██ ▐█ ▐██
▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███
Keys-►▐▌Z█▐▌X█▐▌C█▐▌V█▐▌B█▐▌N█▐▌M█▐▌Q█▐▌W█▐▌E█▐▌R█▐▌T█▐▌Y█▐▌U█▐▌I█▐▌O█▐▌P█
▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███▐███
Actual
Note-► C D E F G A B C D E F G A B C D E
When you write a note, the octave is also written. You can change the current
octave using the "," and "." keys. The currently selected instrument is also
written and you will hear the instrument played at the given pitch.
You can change instruments by pressing "[" and "]".
You can navigate the Pattern Editor by using the CURSOR KEYS, and the following:
TAB - move to the next channel
Shift TAB - move to the previous channel
PgUp - move up 16 lines
PgDown - move down 16 lines
Home - move to the top of the pattern
End - move to the end of the pattern
To add/alter special effects, cursor over to the special effects column and use
one of the following numbers/letters:
1 - Slide note down (pitch bend). Parameter gives the speed of the
slide.
2 - Slide note up (pitch bend). Parameter gives the speed of the
slide.
3 - Slide to note. This slides the LAST note played till it reaches
the note given with this effect. The parameter gives the speed of
the slide. Use parameter "00" in subsequent lines to continue the
slide.
5 - Combined slide to note & volume slide. This command has the same
functionality as effect 3 with parameter "00" and the parameter
performs a volume slide. 1-49 fades the volume of the instrument
down. 51-99 fades the volume of the instrument up.
A - Volume slide. 1-49 fades the volume of the instrument down at the
given speed. 51-99 fades the volume of the instrument up at the
given speed.
C - Set volume. Sets the absolute volume of the instrument. Values
range from 0 (silent) to 64 (loudest).
D - Break. When RAD encounters this command it skips the rest of the
pattern and moves to the next pattern as specified in the Order
List. The parameter, if given, specifies a line in the next
pattern to start from. eg. Effect "D12" would break to line 12 of
the next pattern in the Order List. This command is handy for
"cutting short" a pattern if you don't want to use all 64 lines.
Just place a D00 on the last line you used and the rest of the
pattern will be ignored.
F - Set speed. By default RAD starts up with a speed of 6 but you can
use this command to slow down and speed up the playback rate of
your tune. To understand the speed value, know that RAD uses a
50Hz timer which is delayed by the speed value between each line of
the pattern. What this means is that, say, if you set the speed to
50, (using "F50"), then each line will play at the rate of one per
second. Special effects, however, are modified 50 times a second.
I - Ignore. Used only in Instrument Riffs (see later) to ignore note
transposing for that note. Handy if you want to play an instrument
effect that requires a set note to sound correctly.
M - Multiplier. Used only in Instrument Riffs (see later) to set an
instrument's operator multiplier on the fly. The channel the
effect is in defines which operator is affected. Channel 2 & 6
target operator one. Channel 3 & 7 affect operator two. Channel 4
& 8 affect operator three. Finally, Channel 5 & 9 affect operator
four.
R - Riff. Starts playing a riff (see later) on the channel. The first
digit defines which riff track is used (0 to 9). The second digit
is the channel in the riff track of the riff (1 to 9). If the
second digit is 0 any playing riff is stopped. Only one riff can
be playing at a time (though instrument riffs can also be playing
simultaneously).
T - Transpose riff. As with the R effect, this effect plays a riff.
However it also transposes the notes in the riff using the note
supplied with the effect.
U - Feedback. Used only in Instrument Riffs (see later) to set the
instrument's feedback values on the fly. The first digit is which
value to set (0 to 1), and the second digit is the value (0 to 7).
V - Volume. Used only in Instrument Riffs (see later) to set an
instrument's operator volume on the fly. Refer to the M
(Multiplier) effect for how the operator it affects is chosen.
BACKSPC - Note-off. Insert a note-off at the current position.
To play the current pattern (to see how it sounds) press F6. Pressing F6 again
will stop the playback. To move to a new pattern press "-" and "+/=".
You can use the following editing keys to help you in writing patterns:
INSERT - insert a line in the current channel
DELETE - delete the current line in the current channel
SPACEBAR- wipe the current item only (also stops playback).
F1 - Move to the top left corner of the region you wish to copy and
press F1. Then move to the lower right corner and press F1 again.
The highlighted region will then be moved into a copy buffer.
F2 - Will paste the contents of the copy buffer to the current cursor
location.
F3 - Will copy the entire pattern into the copy buffer.
F4 - Will replace the entire current pattern with the contents of the
copy buffer (be careful!).
F9 - decrement the current speed value
F10 - increment the current speed value
F11 - toggle full-screen display of the pattern editor
F12 - key help
Instrument Editor
~~~~~~~~~~~~~~~~~
To edit your instruments you need to switch to the Instrument Editor. Use the
"`" (back tick) key to switch between windows until you see a highlight
bar appear over the top-left item in the instrument window.
RAD supports up to 127 instruments and it is these instruments that actually
produce the sound. Each note in your patterns specifies an instrument to play.
Instruments can vary significantly in sound from each other and, accordingly,
your tune's mood will change dramatically depending on the instrument mix you
use. Some instruments sound good as lead, other as bass, and others are
only useful as percussion.
To begin with you will probably find it easier just to load in an existing
tune and use the instruments that came with it. You can do this by loading the
tune into RAD and hitting Control-C to clear the patterns leaving the
instruments intact.
To design your own instruments, once in the Instrument Editor you can
interactively alter the currently selected instrument's properties (remember "["
and "]" select instruments). Use Cursor Up and Down to select the property to
alter, and Cursor Left and Right to decrease or increase or toggle the
property's value. Alternatively, you can press ENTER on the parameter you wish
to change, and input the value manually. There isn't much to say regarding how
to correctly set properties, as different things produce different effects.
Simply alter things and press a Note Key to see how it sounds!
The one property's effect you SHOULD be aware of is the CARRIER's volume, which
is usually operator 1. This governs the output volume of the instrument and, in
fact, this is the property that is modified by the Set Volume and Volume Slide
commands.
Other than that, Good Luck! :-)
If you create a cool sounding instrument, you'll probably want to put it aside
somewhere for future use. Use Control-G (Get instrument) and Control-P (Put
instrument) to load and save instruments. Refer to Loading and Saving below on
how to use the interactive directory.
Alternatively you can store your new instrument in the Instrument Library which
is new to RAD 2, described in a later section.
Order List Editor
~~~~~~~~~~~~~~~~~
Once you have created a few patterns you will want to string them together to
create a complete tune. By moving to the Order Editor (use " ` " remember) you
can define when each pattern will be played. Line 00 corresponds to the first
pattern to be played, line 01 the second, etc. By using Cursor Up & Down to
select a line, with Insert or Delete to remove or add a line as necessary, you
can use Cursor Left and Right to set which pattern will be played at that
position in the song. for example, suppose you had the following Order List:
00│03
01│01
02│04
03│01
04│02
05►02
When you start your tune playing (with F5), it will start by playing pattern 03
(specifed by line 00). Once it has played all 64 lines of pattern 03 (or less
if you used a Break command) it will then play the pattern specified by the next
line, in this case, pattern 01. Each line will be played one after the other,
playing the pattern listed for that line.
As you can see in the above example you can re-use patterns (Pattern 01 is used
in line 01 and 03) if there is a chorus or refrain you want to repeat in your
tune.
If you notice in the above example, there is a line that contains a right arrow
between the line and the pattern. This is a JUMP MARKER and it tells RAD to
jump to a new line. So when RAD gets to line 05 in the example, rather than
playing pattern 02 it will instead jump to LINE 02. Hence the list of patterns
that will be played with the above Order List is:
03, 01, 04, 01, 02, 04, 01, 02, 04, 01, 02....
│
└────── Repeat caused by Jump Marker
You can mark the current line as a jump marker by pressing '\' and then using
Cursor Left & Cursor Right to set the line the marker will jump to. A Jump
Marker cannot be placed on line 00.
RAD will repeat the song from line 00 when it gets to the end of the Order List
so you don't need to place a Jump Marker there.
Loading & Saving Tunes
~~~~~~~~~~~~~~~~~~~~~~
Naturally enough, once you have completed your Symphony No. 5, you'll want to
keep a permanent record of it. To save your tune press Control-S. This will
bring up your OS file requester to allow you to select a filename and directory.
If you're using the MS-DOS version, or you press Control-Shift-S, you will be
presented with RAD's built-in file requester. You can select an existing
filename by positioning the highlight bar on it, using Cursor Up and Cursor
Down, and then pressing Enter. By selecting a directory or a device you can
move around your disk structure. If you are saving a new file then you will
need to type a new filename. Press TAB to switch to the filename field and
enter the desired filename, using the editing keys to fix typing mistakes as
necessary. Press Enter to save. If you are saving over an existing file you
will be asked to confirm.
Loading follows a similar procedure. If you're using the Windows or Mac
version, press Control-O to use your OS file requester to select a tune to load.
Alternatively, press Control-L to use RAD's in-built file requester, using
Cursor Up and Cursor Down and Enter to select the desired tune file.
On non-DOS versions of RAD you may also write out a WAV recording of your tune.
Press Control-W and follow the on-screen prompts. The output format is in 16
-bit stereo at 48 KHz.
Adding a Description
~~~~~~~~~~~~~~~~~~~~
Because tracker tunes circulate widely and are often not accompanied by
documentation, traditionally musicians have placed author information and greets
in the instrument name fields of their compositions. Although RAD has
instrument name fields you can add a dedicated description to your tune by
entering the Description Editor. Press Control-D to toggle between editing the
description and editing the Pattern. The Description Editor is a simple free
-form one page text editor. Type whatever you like, where you like, even if
it's just the name of the tune!
Because RAD was written as an intro tune development system, the tune files were
designed to be fairly compact so as not to take up much room in any programs it
was used in. Adding a description to a tune will add to the length of the tune.
In the bottom right corner of the Description Editor is a counter that displays
the number of bytes that the current description text will occupy in the saved
file so you'll always know just how much space your hot air is going to take up.
You may not see much use for a description especially if the tune is ultimately
destined for use in an intro but the fact is module-ripping is a popular past
-time and chances are, if your tune is awesome, it WILL be ripped out of your
intro and spread around. You can at least make sure everyone knows who wrote
the ripped tune because the description will be ripped along with the tune!
Instrument Library
~~~~~~~~~~~~~~~~~~
New to RAD 2 is the Instrument Library. In previous versions of RAD you would
need to use Control-G (Get instrument) and Control-P (Put instrument) to load
and save the current instrument to file if you wanted to re-use it in other
tunes.
You can still do that, but you now have the alternative of using the Instrument
Library. The Instrument Library allows you to store your favourite instruments
in a central repository, and to categorise them.
To bring up the Instrument Library, press Control-I. You start with the cursor
in the left window which lists the categories. Press N (or Insert) to add a new
category, or A to alter the name of an existing category, and Delete to delete a
category. Use Cursor Up and Cursor Down to move within the category list, and
press Cursor Right to enter a category. This will place the cursor in the
right- hand window.
Inside this window are the instruments, and the currently selected instrument
will be displayed in the instrument window ready for you to audition using the
note-keys (see above). Use Cursor Up and Cursor Down to move through the list,
and press Enter to bring the currently highlighted instrument into the current
instrument slot in your tune. Alternatively, you can press L to Load the
current instrument in your tune into the library. Press A to alter the name of
the instrument, and Delete to remove it.
Press Escape or Control-I to exit the Instrument Library. If you made changes
you will be asked whether you want to keep them. The Instrument Library stores
your instruments in a file called "RAD.BNK".
Riffs
~~~~~
Riffs are a new addition to RAD 2. When it came time to update RAD we realised
that previous versions were quite lean in the number of effects you could apply
to your notes compared to standard trackers. But instead of giving you dozens
of new command letters/numbers to remember, and requiring code specific to each
effect to be added to the player, we instead opted to use a system that
would allow you to define your own effects. This is the Riff system.
Riffs are sequences of notes/effects that can be triggered using a single
effect command within your pattern, or by playing a particular instrument.
One of the more basic uses of riffs is to avoid needing to create lots of
repeated content in your tune. For example, the ubiquitous "four on the floor"
drum-loop:
C-4 1---
--- ----
--- ----
--- ----
C-4 2---
--- ----
--- ----
--- ----
C-4 1---
--- ----
--- ----
--- ----
C-4 2---
--- ----
--- ----
--- ----
etc.
A simple sequence like that can end up being copied around a lot in your
patterns. This is especially problematic if you need to modify the sequence for
some reason later.
Instead, you can make a riff. Press Control-R to switch to the riff
patterns. You'll notice the "Pattern:" window will display "R0". This is
riff pattern 0. There are ten riff patterns, selectable with "+/=" and "-",
numbered R0 to R9. Each column in each riff pattern is a separate riff. You
enter notes in the riff pattern just like you would a normal pattern. So put
the above drum-loop into the first column of R0, and press Control-R to return
to normal editing.
In order to play the riff you then need to use one of two riff effects. For
this drum-loop the appropriate effect is "R" for Riff:
--- -R01
This plays the riff in R0 channel/column 1 as if the notes were entered into
your main pattern. This will play the four drum notes once. You could then
trigger it again on line 16 by using the effect "R01" again. Or you could go
back into the Riff Editor (Control-R) and add a D00 (skip to line) effect on
line 8 of the riff. Now when you trigger the riff using "R01" it will keep
playing the two notes over and over until you either play a new riff, or you
cancel the riff playback by laying down the "R00" effect.
But what of notes/effects in the main pattern struck during play-back while a
riff is playing? No problem - they override the riff notes/effects, allowing
you to customise the individual riff play-back. The riff note/effect (if any)
will play, and any parts of the main note specified will overwrite the ones in
the riff. This is handy in the previous example for adding a drum-fill, for
example, without stopping the drum-loop from playing.
If you use a simple bass-line melody that repeats often you can place this into
a riff and trigger it using a single effect, for example:
C-4 ----
--- ----
E-4 ----
--- ----
G-4 ----
--- ----
E-4 ----
--- ----
--- -D00
Note, the riff does not have an instrument associated with it. When you play
the riff, the riff notes will take the instrument used in the note that
triggered the riff, i.e.:
--- 4R01
Of course if you want to play the riff in a different key then this will not
suffice. This is where the T (Transpose) effect comes into play. This is just
like the Riff effect but, as the name suggests, it transposes the riff instead.
The note given with Transpose is the transpose amount relative to C-4. That
is, for example, the following note:
E-4 -T01
Will start the riff playing as usual, but the notes within the riff will be
transposed four semitones up (C-4 -> C#4 -> D-4 -> D#4 -> E-4).
That's one use of the riff system. Sick of entering long strings of 1xx/2xx
effects to simulate vibrato? Put them into a riff and trigger the vibrato riff
on the notes you want it to affect, another handy use for riffs.
One notable omission from earlier versions of RAD was the arpeggio effect (0xx).
Now you can use riffs to simulate this effect. Put the notes of your arpeggio
into a riff, set it to repeat using D00, and trigger it using Transpose. But
traditional chip-style arpeggios run very fast, so put a Set Speed effect (Fxx)
into the first note of your riff arpeggio to set the desired play-back speed;
setting the speed of the riff like this does not affect the main pattern's
speed.
I'm sure once you've played with them a bit you'll find all sorts of new tricks
you can apply them to!
There is a third variation to the riff system which is handy if you're getting
sick of adding vibrato to every instance of a particular instrument, for
example. Every instrument has its own riff accessible by pressing Control-R
while in the Instrument Editor. Placing vibrato effects in here will cause the
vibrato to occur every time this instrument is played. Note, entering notes in
the instrument's riff will, by default, not enter the instrument number as it's
assumed you're playing the instrument itself. However, you can trigger other
instruments here if required.
You'll notice that channels 2 through 9 look a little different in the
instrument riff. All the channels are played simultaneously when an instrument
riff is triggered, but these channels can only hold additional effects. This
allows you to use multiple effects on an instrument per line. Especially when
coupled with the effects that modify the instrument's parameters, this can
create quite dynamic instruments.
MIDI INPUT
~~~~~~~~~~
Another new feature for V2 is the use of external MIDI hardware to help sequence
your RAD tunes. Press Control-M to bring up the MIDI INPUT dialog box (you'll
see an error if you have no MIDI sources available).
From here you can adjust various parameters to suit your needs. Firstly you'll
want to enable some channels for MIDI input to write into by pressing the keypad
keys and/or A (All channels). When MIDI notes are received from the source
they'll be written into the selected channels in round-robin order. If you want
key releases to be recorded press K to enable Key-offs. Finally, you can press
V to toggle velocity input which will be translated into Set Volume effects.
When you're done press Enter to accept the changes, or Escape to cancel.
MIDI OUTPUT
~~~~~~~~~~~
This isn't a fully supported and fleshed out mode, but RAD V2 has the ability to
play external instruments as well, though this isn't really what RAD was built
for. To enable MIDI out select Algorithm 7 on your instrument(s). This will
bring up a set of MIDI options which will be emitted using the MIDI protocol
when playing notes with that instrument. It is expected the port number will
be different on every system and MIDI hardware availability, so likely
instruments will need to be modified before they can be used unless the saved
tune was generated from the same session.
To see some examples of using the MIDI out functionality, refer to the MIDI
directory in the release package. Contained therein are three files:
RAD version of Pachelbel's Canon in D
RAD version of the beginning of Mendelssohn's Fingal's Cave
An MP3 recording of the above Fingal's Cave performance
Both RAD tunes use standard General MIDI mapping for instruments, and the
quality of the result depends massively on the quality of your General MIDI
device. The recording of Fingal's Cave uses VirtualMIDISynth with the Timbres
of Heaven sound-font. If you wish to recreate it then if your MIDI synth is not
on port 0 you will need to edit the instruments first to set the correct port.
These versions of the classic tunes were transcribed directly from the sheet
music and contain no embellishments, so they're not shining examples of the art!
Although these are General MIDI tunes, RAD's MIDI out support is not limited to
that. It's perfectly capable of sequencing external hardware and has been used
successfully to sequence a Roland JD-XA, a Roland TR-8, and a Roland JP-8
synthesiser, as well as to take input from the JD-XA keyboard using the MIDI
input functionality.
CODING NOTES
▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀
Player
~~~~~~
RAD's whole reason for being is as a tool for writing tunes for use in intros.
To this end, the FULL player source-code for playing RAD tunes in your
productions is included. The format follows that traditionally set by trackers
on the Amiga. Previous versions of RAD provided 16-bit assembly player code for
integration into your productions. This being 2018 there isn't so much demand
for that now, so RAD V2's player code is a C++ class. You can find the player
code inside the PlayerSource/ directory in the release package.
First include the player source code:
#include "player20.cpp"
And instantiate the RADPlayer class:
auto rad = new RADPlayer;
You now need to prepare the instance to play your tune. You'll need a pointer
to the raw tune file bytes and a function for applying values to your OPL3
registers:
rad->Init( <tune>, <OPL3-setter>, <OPL3-setter-argument> );
Where <OPL3-setter> has the following prototype:
void OPL3Write(void *argument, uint16_t register_number, uint8_t register_value);
The <OPL3-setter-argument> is not used by the RAD player code; it is there
purely for passing to your <OPL3-setter> function in case it needs tune-specific
data, or maybe just a "this" pointer.
The function rad->GetHertz() returns how many times a second you should call the
RAD update method to keep the tune playing correctly. If your tune does not
have a BPM set, then this value will always be 50, unless it's also a "slow
-timer" tune, in which case you're dealing with legacy stuff and the return
value is unimportant. If you're doing this then you're on your own!
Please note that the player code itself does no checking that the tune file is
valid and goes ahead and assumes it is, as it expects you're giving it a known
tune file. The player code WILL crash if your tune file is bad. But refer to
the Validator section below for a way to check your tune files.
Once Init() has been called you can now update the player a number of times per
second as given in the GetHertz() return value:
rad->Update();
When you're done, stop calling Update() and call Stop() to reset the OPL3 so no
more sound is produced:
rad->Stop();
By default the player includes code to detect when the tune starts repeating
itself. You can disable this code if you're saving bytes in your production by
setting the RAD_DETECT_REPEATS define to 0 before including the player:
#define RAD_DETECT_REPEATS 0
#include "player20.cpp"
When this code is included Update() will return true when the tune beings to
repeat. Another benefit to this code is you also have access to the
ComputeTotalTime() method which returns the time, in seconds, the tune will take
before it starts to repeat. You can see a demonstration of using this
functionality in the example player code. The example uses it to display the
total tune time if you elect not to repeat the tune.
Opal
~~~~
Most of us don't have the luxury of running original Yamaha OPL3 hardware in our
PC, especially if you're a Mac user. For this reason, RAD V2 comes with its own
OPL3 emulator, called Opal, which provides a very close emulation of the
OPL3 chip sufficient to play RAD tunes.
To use Opal in your own productions, first you need to include it into your
source code:
#include "opal.cpp"
Then instance the Opal object:
auto opal = new Opal( <sample rate> );
You can then instance the player code, providing the Opal register interface
and a pointer to the raw tune data:
#include "player20.cpp"
rad->Init( <tune>, [](void *arg, uint16_t reg, uint8_t val) {
auto opal = (Opal *)arg;
opal->Port(reg, val);
}, opal );
Then in your sample playback call-back, you can get the current samples from
Opal:
int16_t left_sample, right_sample;
opal->Sample( &left_sample, &right_sample );
As you'll note from the types, samples are returned as signed 16-bit values.
Validator
~~~~~~~~~
Usually this is all you need for your productions, but it should be noted that
the music player code expects a valid tune to be supplied; if there is bad data
the player will most likely crash your application. Most productions only use
known tunes so this is not a problem, but if your app is designed to load
unknown tunes, such as the supplied example code, then you can use
"validate20.cpp" to check the file for problems before you give it to the
player. This code is not normally needed so is a separate source file to reduce
the code you need to include.
Anyway, if you do need to validate your tune file, you can do it like so:
#include "validate20.cpp"
const char *errtxt = RADValidate( <pointer-to-tune>, <tune-size> );
if (errtxt) {
Fatal(errtxt);
}
A NULL return value is good. Anything else is a pointer to a null-terminated
string decribing the problem.
Example (Windows only)
~~~~~~~
To see an example of how to play a RAD V2 tune, please refer to example.cpp.
This is a source-code example application for Windows that demonstrates how to
play back a RAD tune using Opal and includes tune validation. The example
should be easy enough to adjust for your application and/or OS. An already
compiled version is also supplied. Just run the example from the command line
and supply a list of RAD filenames as arguments to start tune play-back, eg.
example.exe tune1.rad tune2.rad tune3.rad
You can optionally provide the "-norepeat" flag which will prevent the list of
tunes from repeating, or, if a single tune was given, stops the tune from
looping, eg.
example.exe -norepeat tune.rad
TECHNICAL SPECIFICATIONS
▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀
The RAD 2.1 file format, as used by RAD V2, is as follows: (values in hex)
Note: This format is significantly different (and more compact) than the old RAD
V1 file layout. Please refer to RAD V1's documentation for a description of
that format.
█▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█
█ HEADER █
█────────────────────────────────────────────────────────────────────────█
█ Offset 00..0F:"RAD by REALiTY!!" - Use this to recognize a RAD tune. █
█ Just detecting the initial "RAD" █
█ should be sufficient though! ;-) █
█ █
█ Offset 10:BCD - Version of RAD file (not RAD ver.) █
█ Currently 21h for RAD V2.0. █
█ █
█ Offset 11:Bit 6 - Set if it's a "slow-timer" tune. █
█ Bit 5 - Set if BPM is not 125. █
█ Bits 4..0 - The initial speed of the tune. █
█ █
█▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█
█ BEATS PER MINUTE █
█────────────────────────────────────────────────────────────────────────█
█ If Bit 5 of Offset 11h is set then the next value in the file is the █
█ tune's BPM setting: █
█ █
█ Offset 00:Low byte of BPM █
█ Offset 01:High byte of BPM █
█ █
█▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█
█ DESCRIPTION █
█────────────────────────────────────────────────────────────────────────█
█ The description follows next. The description is a null-terminated █
█ string. To save some space in the tune file, the characters mean: █
█ █
█ Char 00 - End of description (null-terminator) █
█ Char 01 - Move to start of next line (Carriage return) █
█ Char 02..1F - Output this many spaces █
█ Char 20..FF - Output this character █
█ █
█▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█
█ INSTRUMENTS █
█────────────────────────────────────────────────────────────────────────█
█ Next come the instruments: █
█ █
█ Offset 00:No. of instrument that follows (or 0 for no more) █
█ Offset 01..?:The instrument definition: █
█ █
█ Offset 00:Length of name █
█ Offset 01..?:Name █
█ █
█ There are currently two types of instruments in RAD; FM and MIDI. The █
█ type affects the remaining bytes. █
█────────────────────────────────────────────────────────────────────────█
█ OPL3 FM instrument: █
█ █
█ Offset 00:Bit 7 - Instrument has a riff █
█ Bit 6..5 - Operator 3 & 4 stereo panning █
█ Bit 4..3 - Operator 1 & 2 stereo panning █
█ Bit 2..0 - Algorithm (0..6) █
█ Offset 01:Bit 7..4 - Operator 3 & 4 feedback value █
█ Bit 3..0 - Operator 1 & 2 feedback value █
█ Offset 02:Bit 7..4 - Detune value █
█ Bit 3..0 - Riff's default speed █
█ Offset 03:Bit 5..0 - Volume █
█ █
█ Followed by four operator definitions (even for the 2-op algorithms): █
█ █
█ Offset 00:Bit 7 - Tremolo on █
█ Bit 6 - Vibrato on █
█ Bit 5 - Sustain on █
█ Bit 4 - Scale rate █
█ Bit 3..0 - Multiplier █
█ Offset 01:Bit 7..6 - Scaling level █
█ Bit 5..0 - Volume (inverted; 0 = loudest) █
█ Offset 02:Bit 7..4 - Envelope attack value █
█ Bit 3..0 - Envelope decay value █
█ Offset 03:Bit 7..4 - Envelope sustain level (inverted) █
█ Bit 3..0 - Envelope release value █
█ Offset 04:Bit 2..0 - Waveform number █
█────────────────────────────────────────────────────────────────────────█
█ MIDI instrument: █
█ █
█ Offset 00:Bit 7 - Instrument has a riff █
█ Bit 2..0 - Algorithm (7) █
█ Offset 01:Bit 7..4 - Port (equipment dependent) █
█ Bit 3..0 - Channel █
█ Offset 02:Bit 7..4 - Version (0) █
█ Bit 3..0 - Octave (0..7) █
█ Offset 03: - Program (1..128, 0 = none) █
█ Offset 04: - Bank LSB (1..128, 0 = none) █
█ Offset 05: - Bank MSB (1..128, 0 = none) █
█ Offset 06:Bit 5..0 - Volume █
█────────────────────────────────────────────────────────────────────────█
█ Following both types of instruments is the instrument riff, if the █
█ riff flag is set: █
█ █
█ Offset 00:Low byte of number of bytes in riff █
█ Offset 01:High byte of number of bytes in riff █
█ Offset 02..:Refer to the PATTERNS section below for the line/ █
█ channel/note encoding. Note, instrument riffs will █
█ not have any notes/instruments in channel 2..9, just █
█ effects. █
█ █
█▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█
█ ORDER LIST █
█────────────────────────────────────────────────────────────────────────█
█ The Order List follows the instruments: █
█ █
█ Offset 00:Length of Order List (up to 128) █
█ Offset 01..nn:List of orders, one byte for each line: █
█ █
█ 00..7F:The pattern to play. █
█ 80..FF:The line to jump to minus 80h (Jump Marker) █
█ █
█▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█
█ PATTERNS █
█────────────────────────────────────────────────────────────────────────█
█ Offset 00:Pattern number, or FFh to indicate no more patterns █
█ Offset 01:Low byte of number of bytes in pattern █
█ Offset 02:High byte of number of bytes in pattern █
█ █
█ For each line in pattern: █
█ █
█ Byte:Bit 7 - Last line █
█ Bit 6..0 - Line number of following notes █
█ █
█ List of notes for that line follow: █
█ █
█ Byte: █
█ Bit 7 - Last channel █
█ Bit 6 - Note/octave byte follows █
█ Bit 5 - Instrument byte follows █
█ Bit 4 - Effect/parameter bytes follow █
█ Bit 3..0 - Channel no. of following note data █
█ █
█ Byte:(if note/octave byte enabled) █
█ Bit 7 - If set use instrument the last note this █
█ channel last used. █
█ Bit 6..4 - Octave value █
█ Bit 3..0 - Note value. This can be one of thirteen █
█ values: 1..12 which indicate one of the █
█ 12 notes from C#(1) to C(12), or 15 for a █
█ key-off. █
█ █
█ Byte:(if instrument byte enabled) █
█ Bit 6..0 - Instrument number (1..127) █
█ █
█ Byte:(if effect/parameter byte enabled) █
█ Bit 4..0 - Effect (0..9, A..V). Not all of these █
█ effect values are used (refer the effect █
█ table given earlier). █
█ Byte:(if effect/parameter byte enabled) █
█ Bit 6..0 - Effect's parameter (0..99). █
█ █
█▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█
█ RIFFS █
█────────────────────────────────────────────────────────────────────────█
█ Offset 00:Riff number, or FFh to indicate no more riffs █
█ Bit 7..4 - riff track (0..9) █
█ Bit 3..0 - riff channel (1..9) █
█ Offset 01:Low byte of number of bytes in riff █
█ Offset 02:High byte of number of bytes in riff █
█ █
█ For each line in riff: █
█ █
█ Byte:Bit 7 - Last line █
█ Bit 6..0 - Line number of following note █
█ █
█ Byte: █
█ Bit 6 - Note/octave byte follows █
█ Bit 5 - Instrument byte follows █
█ Bit 4 - Effect/parameter bytes follow █
█ █
█ Byte:(if note/octave byte enabled) █
█ Bit 7 - If set use instrument the last note this █
█ channel last used. █
█ Bit 6..4 - Octave value █
█ Bit 3..0 - Note value. This can be one of thirteen █
█ values: 1..12 which indicate one of the █
█ 12 notes from C#(1) to C(12), or 15 for a █
█ key-off. █
█ █
█ Byte:(if instrument byte enabled) █
█ Bit 6..0 - Instrument number (1..127) █
█ █
█ Byte:(if effect/parameter byte enabled) █
█ Bit 4..0 - Effect (0..9, A..V). Not all of these █
█ effect values are used (refer the effect █
█ table given earlier). █
█ Byte:(if effect/parameter byte enabled) █
█ Bit 6..0 - Effect's parameter (0..99). █
█ █
█▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█
LAST WORDS
▀ ▀▀▀▀▀▀▀▀▀▀▀▀ ▀
Well we hope you get a lot of use out of RAD. Although RAD started as a simple
project by me (Shayde) it soon turned into something a lot more complex and RAD
would not be what it is without the considerable input from all members of
Reality, with RAD V2 having extensive testing by Louis Gorenfeld (Extent of the
Jam). The graphics and a lot of design ideas were put forward by Rogue (grafix
artist) and Void (musician). Because WE knew want we wanted out of a music
development package, RAD has evolved into something we are very happy to use
for developing our productions. We hope you also discover how to be
RADical...!
RAD V1 was coded in 100% 16-bit assembly language by SHAYDE, which was then
converted to C++ 23 years later and extensively added to to make RAD V2. The
16-bit DOS version of RAD V2 was compiled by the Digital Mars C++ compiler. The
Windows versions were done by good ol' Microsoft Visual-C++ - a very fast
compiler. Finally, the Mac version was provided by GCC/Clang.
RAD's graphics were drawn in 100% ANSI by ROGUE and VOID. The custom font and
intro logo were made by ROGUE.
Documentation by SHAYDE, doc ANSI by ROGUE.
If you'd like to send us any of your quality tunes made with RAD, please do so,
and we'll include them in the next release pack and our web-site! You
can reach us at http://www.3eality.com/
L8'er dudes!
· ∙ ─ ─- ── ─────┤ REALITY PRODUCTIONS - 1995-2023 ├─ ─ ── ───═─══─═══─