
ADDENDUM 19/8-1995


This text from 1990 was converted from SuperScript on the Commodore 128 (no
easy task since the word processor used $C1-$DA for upper case and no wrap
characters). The editor spread is v3.04. Needless to say, many of the things
in this textfile does not correspond to the newer editor version (especially
concerning the diskette menu which was greatly enhanced in v3.04). However,
I added a few notes here and there to iron out the worst rubbish.




                INSTRUCTIONS for JCH's NewPlayer EDITOR v2.53
                

Typed by JCH 5/12-1990.


THE DISKETTE MENU


To get going is the easiest part really. You just load and run the editor,
and BOING! there you have the diskette menu. The editor consists of only 2
screens you can flick between, the diskette menu and the editor screen
itself. Don't let this lead you to believe that the editor is simple though -
the editor screen has been packed with a huge lot of details, all put
together in one easy-to-view screen. This is one of the main ideas of my
editor; to have all things needed when composing in one and the same screen.
In my opinion, there is nothing as irritating and confusing as having to
switch between several screens in order to f.ex. correct an instrument or
adjust a slide effect. But anyway when you see the diskette menu all is more
or less self explanatory. You can either save or load a tune or the tables,
or you can take a directory, or even send a diskette command. Perhaps you
notice that there is a save command for the music and one for the tables
only, but only one load? That's because the load command in the diskette menu
checks the start adress of the file being loaded to judge whether you're
loading music or tables. If it is music it always starts in $0F00 in memory,
otherwise it MUST be tables of course. What is interesting to know though is
that the load routine for TABLES automatically adjusts it's load adress to
the player current in memory. Whoops, what was that? Yes, here I touched one
of the other powers of the editor, again one of my basic ideas when coding
this editor; the ability to load and use different music routine versions
with the same editor! In the bottom of the diskette menu you can always see
what version you have loaded into the editor - in most cases most versions
are mere updates and improvements to older players, but in some cases you can
even load in a compromise player taking very little raster-time. Every time
you change player system the hexadecimal tables inside the editor might
change their meaning - but never their format. And the commands in the
sequence/tracks will always be the same too. More about player systems later,
to return to the subject of the loading TABLE'S it is, as said, interesting
to know that no matter what player you saved the table's from, you will be
able to load it into 99% of all other types of players - if the adress of the
tables are different, it will simply load using an offset value pointing to
the current player's table location. Sometimes the tables differs so much
from player to player that this is hardly of any use - then again, some table
details rarely change, f.ex. ADSR values are always seated in the same spot
in all players made for the editor.

* ADDENDUM 19/8-1995: The table loading facility was cut out in later versions
* of the editor - it was not really useful.

Players working with the editor, at the time of writing this, is as follows:

Player v05 - starting with 05.02, the first primitive player for the editor.
Player v06 - first player to feature filter in 3 voices.
Player v07 - very bugged player, my first attempt at a "compromise" player.
Player v08 - took $25 scanlines because I didn't skip any frames.
Player v09 - this is the first routine DRAX ever used.

Players v00 to v04 were made before I ever thought of programming this music
editor and cannot be used in it.

The players above is hardly recommended to use. The reason for this is that
it is NOT possible to do game tracks with them - you cannot make multiple
tunes! All players from v10 can be used for games, however the hitech feature
called "hard restart" is first available from v11 (rather bugged, then it was
corrected in player v13), and the "stop jingles" endmark from v14.

Player v10 - first routine to feature multiple tunes option.
Player v11 - first routine with "hard restart", however somewhat bugged!
Player v12 - first really succesful "compromise" player (no hard restart).
Player v13 - proper hard restart this time.
Player v14 - the player that sits in your editor, one of the best players.
Player v15 - features a large number of interesting new functions. Use v15.G6.
Player v16 - still under developement, not yet available...
Player v17 - my most satisfying player, a "compromise" player w. hard restart.

* ADDENDUM 19/8-1995: After this textfile I managed to make three more players
* in the series; player v18 (uses too much rastertime), player v19 (extremely
* cut-down compromise player with no vibrato but only $0D scanlines) and finally
* player v20, which is the most advanced player I ever made. This player is
* available in ED v3.04.

If you want to know my "system" in naming the player versions I can tell you
that the first number in f.ex "15.G6" is the player version, a great lot of
differences have been made to the player in order to update THIS number.
Sometimes, large parts of the player has even been rewritten! The "G" after
the full stop means "game-player". If this "G" is not there then you cannot
make multiple tunes with the player (like player v05 to v09!) - The last
digit is for correction of bugs, in this example ("15.G6") I corrected player
v15 as many as 6 times in order to make the player work as smoothly as
possible. In other words, if you want to use, say, player v15 then always use
the version with the largest number after the "G". This is the most debugged
version.

This more or less does it for the diskette menu so far. Now press F8 to enter
the main editor...


THE MAIN EDITOR


THE TRACK AND SEQUENCE SYSTEM

The first thing I want to describe first of all is the general composing
windows and the ideas behind it all. When you enter the editor screen you'll
notice that the screen has been divided into 3 voices - actually it reminds
you a lot of "soundtracker" as seen on the Amiga. Well, you are more or less
going in the right direction believing this, but I have enhanced the original
"soundtracker" idea a lot more than meets the eye. Let me try to describe you
my general idea in the system, the idea that makes this editor so special and
easy to use.

Most editor's nowadays features a track system and a sequence system and this
editor is no exception. The tracks in a normal editor as the one found in
Future Composer controls the sequences by putting them together in different
ways, repeating them and even transposing them. In FC, you have a seperate
track table where you type the numbers as were you editing a large table for
itself, and whenever you want to edit one of the sequences you press "*" to
enter a seperate window where you can edit the notes in the sequence. For
example a track table could look like this:

8C 01 8C 01 8C 02 8C 02 8E 01 8E 01 8F 03 8F 03 FF

All values starting at 80 is a transpose, so a 8C means that the following
sequence number is transposed C times (an octave) and the table is wrapped
using an endmark called FF. If you pull out all the transpose bytes you have
this line of sequences:

01 01 02 02 01 01 03 03 (end) FF

This is the general power and idea behind this system, to call a bunch of
notes more than one time, thereby not only saving time but also memory. The
sequences called can even change in size to make it all as flexible as
possible. This main idea is good in its own right, but I wasn't satisfied
with just putting it all into a track table on it's own. You see, it is
actually rather difficult to see the main structure of the composition and
you cannot compare the 3 voices directly whenever you want to work with ring
modulation or harmonies. However in this editor that you now possess I have
found a solution to all these moans. What I did was simplicity combined with
complexity - the new system is hard to grasp at first, yet when you get used
to it you will admit it is the easiest and most advantageous way of setting
up the track/sequence system. The "soundtracker" principle have been used
combined with sequences put on top of eachother, showing the voices exactly
as the are played in the music routine, no matter what length the individual
sequences have. Imagine having a sequence, called #01, consisting of the
following notes:

         Dur 3, C-4, Dur 1, D#4, Dur 3, C-4, Dur 5, F-4, End.

This is the FC way of doing it. But instead of defining what length the
following notes has in frames, why not let the sequence be divided up into
the smallest possible frames (0), and then put the notes in the proper spots?

         C-4       If you compare this sequence system with the FC one describ-
         ---       ed before you notice that this has an easier view to it.
         ---
         ---       This system is known as the "soundtracker" principle, it is
         D#4       very well known on the Amiga. If you spread this over all
         ---       voices then the voices will follow eachother - unless you
         C-4       use different sequence lengths. This problem was solved too
         ---       however...
         ---
         ---
         F-4
         ---
         ---
         ---
         ---
         ---
         End

The track table that calls each sequence has been put INTO the "soundtracker"
system along with the sequences themselves! Internally the track table inside
my editor system looks much like FC but the coding puts it up to screen in a
much different manner. Imagine having two small sequence looking like this...
Let's call them #01 and #02.

         C-4       F-4
         ---       ---
         D#4       End
         ---
         End

Then, In a track table like FC's you could call them with...

8C 01 8C 01 8C 02 8C 02 FF (without transposes 01 01 02 02).

In my editor system I set up the track table in the voices left margin and
dump out the contents of the sequence to the right, going all the way down to
the end of the sequence - here immediately followed by a new track table
number. So, in my editor system these tracks and sequences looks like this:

         8C 01:C-4      As you can see sequence 01 and 02 are displayed two
               ---      times each, on top of eachother. If I went into the
               D#4      first track number and wrote 8C 02 instead if 8C 01
               ---      then the C-4 --- D#4 --- would be swapped with the
         8C 01:C-4      apperance of F-4 --- instead. It would seem like the
               ---      entire voice was moved up two steps... but this is
               D#4      just because the track numbers just displays what it
               ---      finds in the sequences in memory.
         8C 02:F-4
               ---
         8C 02:F-4
               ---
            FF (End of track table)

As you can imagine the three voices will follow eachother always - no matter
how you change the size of the sequences, the voices will always display
exactly what the SID-chip will play. The system I made is therefore easy to
edit and you can make the harmonies and ring modulation as you want,
comparing the voices all the time. This is exactly how my editor works in
general - now let's have a look at the actual display of the editor with this
system in mind.

THE 3 VOICES IN THE EDITOR

As soon as you enter the editor you notice a cursor blinking beside an 8C00
track number. If you try to cursor down you also discover that you can't!
This is because there is a "stop cursor" function at FF00 endmarks. To start
off with a sequence you must always "open" it up first. Enter F5 to enter the
track table and type "8C01" then F5 again. Better get used to the F5 key, it
is only used for toggling between tracks and sequences, but it is the most
used key in the editor! When in sequence mode again you press SHIFT RETURN to
open up sequence #01 with exactly 16 steps (a nice round number when
composing in 4/4) - you can also use the INST key to open it up. Notice how
the large number of FF00's are pushed downwards - remember this is only a
trick as the track table only jumps to the next track number when the
sequence has ended. Did you wonder why I started off with sequence #01 and
not #00? That's good - because there is a very good reason not to use
sequence #00 ever! You see, you normally have control over as many as $00 -
$70 sequences, but $00 are reserved for special uses. First, whenever you
press SHIFT-C to clear the entire composition sequence #00 is used to clear
all other sequences up to #$70. This way, you can predefine a special looking
sequence #00 before clearing the composition, f.ex. open 4 times SHIFT RETURN
plus filled up with +++ (more about this later) and then, after typing
SHIFT-C, all sequences are looking like this as a default. It is vital though
to avoid editing sequence #00 AFTER clearing, otherwise your music will take
up 146 blocks on the disk - you see, sequence #00 is ALSO used to check how
many sequences have been used when saving a tune to disk!

* ADDENDUM 19/8-1995: In ED v3.04 the saveroutine uses a different (and better)
* way of detecting how many sequences was used before saving the tune.
       
When you have openened sequence #01 with 16 steps you can then begin entering
the notes and commands in the sequence as you like - when done, you then
press F5 again to return to the 8C01 track number. Now you cursor down to the
FF00 following the first sequence and type the sequence to follow the first -
if you type 8C01 again and press RETURN you will see the display change
instantly, showing the same sequence as before, now going two times in a row.
If you want a new sequence you can type, say, 8C02 and start over again;
enter F5 to leave the track and open up the sequence with either SHIFT RETURN
or INST. Warning! Never open up a sequence more than 4 times SHIFT RETURN (64
steps) as the packer that crunches the music that you save onto disk cannot
handle bigger sequences than this. Also, this editor version v2.53 does NOT
have a boundary control build into the opening of sequences - if it gets much
bigger than 6 times SHIFT RETURN some rather odd bugs appears which can only
be fixed by copying another sequence into the damaged sequence (more about
copying later)!  Actually it was my intention to build in a boundary control
when I made this editor version, but as I soon ran out of memory (I used
Turbo-Assembler at that time) I had to wait with luxury details such as this.

* ADDENDUM 19/8-1995: In ED v3.04 there is a built-in boundary control of $60
* steps at the most. Just tap the insert functions as many times as you want.

But as said, if you should ever open up a sequence with more than the
allowed maximum then you can save your skin simply by copying another
sequence into it. The symptoms to a messed up sequence like this is that the
cursor suddenly appears to be in the left-most side of the voice (the track)
but without any grey track number... and when you cursor up, you'll find a
"1010" number instead of the usual track number. Enough about sequence
opening.  One of the first things I want you to do is to get used to the
cursor system made around the three voices. When you enter the grey
tracknumbers with F5, always keep in mind that you cannot cursor into another
voice like you can inside the sequences. When you cursor left/right in the
tracks, the cursor will always appear on the same track number all the time.
If you then want to go from, say voice 1's track number into voice 2's track
number you have to press F5 to enter voice 1's sequence, cursor over to voice
2 and then press F5 again to enter voice 2's track number. This may sound
awkward at first but you'll soon get the hang of it, believe me. Cursoring up
and down in your composition is very logical too, you can go straight down
through the different sequences in sequence mode, however if you enter the
track numbers you can move around in your composition at a much greater speed,
as the cursor here will jump from sequence to sequence instead. In both cases
you will always stop at the FF00 endmarks however, as this marks the wrapping
of a tune.

Typing in commands and track numbers is also something that needs a word or
two. Whenever you want to type a new track number it is always necessary to
either press RETURN or LEAVE the typed number in order to make the editor
"accept" the number. With LEAVE I mean every activity that makes the cursor
disappear from the number - such as leaving with F5, going into one of the
instrument tables, cursoring up/down in the composition and so on. In the
sequence, it is also very important to know that a COMMAND is first accepted
by the editor when you cursor away from it! COMMANDS are the ones typed in
the left-most row of minuses (---), I00-I1F, S00-S3F and "***". However, the
command row HAVE been made fool-proof; you cannot type anything else than the
commands available to the editor, any other text will be erased as you cursor
up or down - and if you cursor away with only an "I" typed, the editor will
automatically write "I00", which actually can be quite handy sometimes (this
goes for the "S" and "*" commands aswell). In the right-most line of minuses
in the chosen voice things are quite different concerning the interpretion of
the keyboard. Here, you type a note using the two-octave keyboard "Q2W3ER5
etc" and the note that appears will immediately be put into memory unlike all
other commands in the voices. The octave can be adjusted using the F7/F8
keys, and you can always see what octave you're currently using by looking at
the "O" mark in the bottom right corner of the screen. Octaves 0-7 are
available in this editor, which should be enough for most purposes! Whenever
you want to erase a command or a note, simply tap a SPACE on the command's
first character (and cursor up/down) or on the note (depending on what you
want to erase). You can also use the DEL key, but this is hardly recommended
as it will decrease the length of the sequence. As a special key command you
can also press SHIFT SPACE in the note column to "hold a tone" so to speak, a
"+++" then appears.

Anyway, at first I fully recommend that you load some of our work-tunes and
cursor around in them. Please feel free to change some commands here and
there and play the music again to hear the difference. Practise makes
perfect, remember that! As soon as you feel ready you can then press SHIFT-C
to clear the composition (but not the instruments) and then try for yourself
using some of our old instruments...

THE AVAILABLE COMMANDS IN THE TRACK TABLE

As soon as you've achieved some understanding in how the compose mode works
AND how you move around, open sequences, write commands etc it is time for
you to get some information in exactly what commands you may type and what
they mean.

Let's start with the track table. This is the row of grey numbers that
controls what sequences, as you know, but let's look closer at this "word"
which actually should be split up into two BYTES, the transpose and the
sequence number. If you see a "8C02" it actually says, "Show sequence number
#02 and transpose it an octave". The first byte can start at "80" and this is
the base tranposing of a sequence. Or to put it differently, if you have some
"C-2" notes in the sequence and the tranposing byte says "8C" the "C-2" will
be played as a "C-3" instead. The range of transposings can be from "80" and
all the way up to "FD" (theoretically). WARNING! Don't EVER type any number
below "80" or you will play TWO sequences in the same track number. This is
very dangerous, not to the routines or data in memory but to YOUR view of the
composition! The second byte, the actual sequence number, will always be
displayed on screen as a full sequence but as the first byte has been
designed as a transpose info you cannot "see" a sequence typed here. I
therefore strongly advice you NOT to put any sequence numbers in here - you
might even confuse the packer when it has to crunch your tune if you break
these rules. No boundary control have been made, simply to make the system
expandable in the future. OK, now that you cursor over to the second byte,
the sequence number, you should know that it is vital to be careful here too.
The sequence numbers reserved for YOUR use is hexadecimal #$00 up #$70, which
should be MORE than enough for most peoples use! BUT, because there is a but
here too, you may NEVER type any number higher than #$70 - again, no boundary
control is present to prevent this in this editor version, but remember that
the editor will always print the sequence number's data on screen - and if
the #$00'th sequence start at around $2A00 in memory and the #$70'th sits at
around $9F00 AND the editor's machine code program resides in $A000 (and up)
you should be able to see the danger! IF you type, say, "8C80" and type F5 to
both enter the track number and go into the sequence you'll see a very
strange sequence, filled up with all sorts of weird and confusing music-data
- this is the editor's machine code you're looking at! If you change any of
it, you might crash the entire system - so PLEASE KEEP below sequence #$70!
(Looks like "8C70" for example.)

* ADDENDUM 19/8-1995: Needless to say, you cannot type illegal sequences in
* v3.04 of the editor - they are replaced by an 8C00 command. :)

Two last commands available in the track table remains to be explained, the
wrap-mark and the optional end-mark word. The wrap-mark is, as the transpose
and sequence bytes just explained, available in ALL player's made for this
editor, the ONLY thing which doesn't appear in all player's is the end-mark
"FE00". Everything else is standard. Right, the wrap-mark is the "word"
you'll see scattered all over the screen whenever you clear a tune with
SHIFT-C or just enter the editor without any tunes loaded - it is very simple
to understand, as soon as the music routine encounters these marks it will
immediately wrap to the beginning of the voice. Notice I said VOICE, and not
composition! The JCH player's have been designed to have independent wrap-
and end-marks, you can actually put in a wrap-mark way before some other
voices - this may get your music out of synchro, then again you can make use
of it to your advantage, f.ex in making a short, repetitive bassline which
wraps all the time and, in another voice, a much longer leading melody.
However, there is ONE reason why I'd want you to keep the wrap- and end-marks
aligned EVEN THOUGH it is possible to do this - whenever the tune has been
crunched and you load it into the "Delux driver" the driver here will check
for the end of the tune by looking at the apperance of wrap/endmarks. As you
might guess, it is impossible for the driver here to see if it really IS the
end or just you wrapping a voice earlier than another, so the "Delux driver"
will always plot the end-time no matter what you did. Of course you can
choose to ignore this anyway, but if you have ever wondered why the "Delux
driver" sometimes messes up this "end-time" clock, you now know why! Enough
about the wrap-mark's meaning, the end-mark "FE00" will, yes you guessed it,
stop the tune completely, very useful in jingles for games and the like. But
remember, it is only available in SOME player's, as for example v14 and v15,
but not v17.

* ADDENDUM 19/8-1995: The endmark is also available in later player versions.

A little detail pops up when typing end-marks - you then notice that the
editor's cursor routine WON'T stop at them when cursoring past them - why is
this, when it stops at the normal "FF00" wrap-marks? Simple, because when I
first coded this v2.53 editor I didn't have the "FE00" end-mark in mind, it's
as simple as that! Another extra thing I want you to know is that the
music-routines made for the editor always looks at the "FE" or "FF" byte when
determining whether to stop or wrap the voice - so, the sequence number "00"
is actually totally ignored, it doesn't matter if you type f.ex "FF34" or
"FE02" or whatever. The sequence will then of course be displayed, but it
will not be played.

HOW TO MAKE MULTIPLE TUNES

Now before discussing the commands in the sequence I will have to babble a
little about how you make more than ONE tune in one and the same work-source.
Actually it is very logical and straight-forward once you master it, the only
difficult part is HOW to pass those damned "FF00" wrap-marks! Now remember
this is something that will only work in player's v10 and up (Though I don't
think you'd ever want to get any of the older player's anyway but there you
go...)!

Multiple tunes can only be achieved in one very simple but in some terms
admittedly a little awkward way - by splitting up the tunes with
wrap/endmarks! The splitting does not necessarily have to be aligned in three
voices, but it is strongly recommended as the music packer will start all
music parts immediately after the wrap/endmarks. The splitting of tunes this
way is not hard to understand (well, I sure hope not!), the bad news is how
to bypass the FF00 wrapmarks. As said earlier in these instructions there is
no problem at all when dealing with FE00 endmarks, as the cursor can wander
straight pass them without stopping - but the cursor automatically stops at
the FF00 wrapmarks, so how do you get past them? Ok, let's assume you have
made a full, say, a titletune, and now you want to have a hiscore ditty right
behind it's FF00 wrapmarks. What you then do is as follows:

         1. Enter the tracktable (F5) and cursor down to the FF00 wrapmark in
            voice 1. The cursor now refuses to go any longer.

         2. Now type "8C00" on the "FF00" and cursor down.

         3. Here, at the second FF00 you write the first track and transpose
            you want in the hiscore ditty. If you've used f.ex #$24 seq's in
            the titletune and you want the first hiscore transpose to be "8C",
            then just write "8C25".

         4. Standing on your "8C25" you now cursor up again to the "8C00" you
            typed before and type "FF00" again.

         5. Now exit the "FF00" with F5, cursor over to voice 2 and press F5
            again to enter voice 2's "FF00" wrapmark. From this point you just
            repeat the same procedure from step 2.

When you have prepared the first three sequences you want for the hiscore
ditty it is a little easier to bypass the FF00 wrapmarks from now on - going
up past a FF00 wrapmark from the hiscore ditty won't stop the cursor at all,
and when you're wandering down inside the tracktable a stop by the FF00 is
quickly bypassed with a tap on the F5 (enter sequence), cursor down, and F5
again to re-enter the tracktable again. If you have tried this a few times
you'll soon master the rather clumsy stop function by the FF00 wrapmarks - a
function I made way before I even thought about making a multiple tunes
function, which is the reason for all this trouble.

* ADDENDUM 19/8-1995: I know you hope I improved this in ED v3.04, but as a
* a matter of a fact I didn't! ;)  You still have to use the same method.

Now that you have learned how to split up the worksource, there's a few more
things you need to know about splitting it up. The use of multiple tunes are
hardly of any use in demo's and the like, it was mainly designed for use in
games which often requires a huge lot of different music in the same block -
such as a title screen tune, hiscore, get ready jingle, game over jingle and
so on... But WHEN you want to split up your source into more tunes, then
always consider these important details:

1. Never ever split up a voice with more than ONE "FF00" or "FE00" mark between
   two different pieces of music. The ONLY place it is allowed to have a lot of
   these marks in a row is a the absolute end of the entire musicblock. The
   reason for all this is that the music-packer tests for the maximum number of
   tunes in your block by checking for more than ONE wrap/endmark in a row.
   This will make the packer KNOW how many tunes there is, which it needs to
   know when setting up some functions in the packer's menu. Also, when the
   packer saves the music to disk it will put in an info-byte inside the player
   to let the "Delux driver" know how many tunes there are too, which then can
   be accessed with the numeric keys "1" and up to the maximum number of tunes.

2. The maximum number of tunes you can split up your musicblock is 31 different
   tunes and jingles, which should be more than enough!!

3. The music-packer not only knows how many tunes you made, it will also let
   you define independent music speeds for every single tune in the block! Of
   course you can't set up different speeds for the tunes in the editor as
   there is only ONE speed control here, so I'd advice you to get a piece of
   paper and write down your intentional speeds for the tunes. Then, when you
   pack your music you can grab your piece of paper and tell the packer what
   speeds you want the tunes to be using.

4. ....

I'm sorry but this was as far as I got with these instructions! You must
guess your way to the rest, but remember to have a copy of the key-info's
beside you and try all key-commands.

JCH, update epilogue 27/8-1991.


* ADDENDUM 19/8-1995: Read the player specific textfiles to gain information
* on the settings available in the editor tables.

