     ██████████████████████▄      ▄▄████████████████▄▄    █████████████████████▄▄
      ████████████▀▀▀▀▀▀█████    █████████████▀▀▀▀█████   ▀█████████████▀▀▀▀▀█████
      ██████████████████████▀   ████████████████████████   █████████████      █████
      ████████████      █████   █████████████      █████   █████████████     ▄█████
     ██████████████    ███████ ███████████████    ███████ █████████████████████████
     ██████████████    ███████ ███████████████    ███████ ████████████████████████
     ██████████████    ███████ ███████████████    ███████ █████████████████████▀▀

     ┌────────── ── ─ -∙· Reality ADlib Tracker ♫ Version 2.0a ·∙- ─ ── ──────────┐
     │                                                                            │
     │                   (c)1995-2018 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.

    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)        █
      █────────────────────────────────────────────────────────────────────────█
      █ 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-2018 ├─ ─ ── ───═─══─═══─