
Full instructions for NewPlayer v17.G1
--------------------------------------

Typed by JCH, 28/11-1990.

The NewPlayer v17.G1 music routine is actually an extension to the old v12
player, featuring hard restart, a better vibrato routine, simplified sliding
and a simplified filter programming routine. This player will take approx $14
scanlines (if the raster-decreasing byte in the packer is set) yet sound much
like a proper hi-tech player. All this makes it the most succesful player of
all the players I have done so far, I think. I hope you will agree too...

Warning: To get the most out of these instructions, it is required that you
have read the instructions for player v14 first.


The 8-byte instrument
---------------------

         00  00  00  00  00  00  00  00
         ------------------------------
         A   B   C   D   E   F   G   H

Byte A & B is ADSR.

Byte C, D and E is the pulsating setting, and works very much like in player
v14. Byte E sets the startpulsating, f.ex. knowing that the puls in the SID
chip can go from $000 to $FFF, a $180 is stated as $81 in byte E. Byte C is
the widths; a $4A means that the puls will travel between puls $400 and $A00
at the speed set in byte D.

Byte F is a filter pointer to the filter-table, accessed with the ";" key. In
player v17.G1 you have some default conditions that cannot be changed as they
are some of the secrets to the low rastertime the player takes. First, you
can only access filtering in voice 1. If you have a filtered instrument put
into either voice 2 or 3 the filtering will disappear. Also, the resonance is
set to $F (the most used anyway) and the filter passband to $1 (normal
setting). While these things are unchangable configurations you can however
decide whether you want the filtering in voice 1 at all or you want it shut
off. Very logically you just set this filter pointer (byte F) to 00 and the
filter will be off. As soon as you state any other pointer value than 00 the
filter will be put on. This is very logical because the first 4 values in the
filter table may not be used anyway as these bytes have been reserved for use
in the packer.

Byte G is the vibrato pointer (as in player v12) to the table accessed with
the ":" key. It is recommended that you always name the vibrato set at
pointer 00 as 80 00 00 00 as this will shut off the vibrato. The reason for
this is that the vibrato routine inside the music-player always has first
priority over the arpeggio routine. Said differently, if a vibrato is going
on then any arpeggio running at the same time will be ignored. More about
this later.

Byte H is the pointer to the arpeggio table. This table works exactly as in
player v14. Player v17 features direct pointer wrapping.


The vibrato table
-----------------

This is the table accessed with the ":" key. All instruments can have a
vibrato effect attached to it, as in player v12 and v14 for example. You
cannot access the vibrato's using a Sxx command inside the sequence, as in
player v15.

         00  00  00  00
         --------------
         A   B   C   D

Byte A is the trigger (or delay) timer. The higher the value, the longer it
takes before the vibrato is actually started after a note has stroke. While
the vibrato is "waiting" to be started, the arpeggio routine can run normally
- however as soon as the vibrato starts up the arpeggio routine is suspended.
Therefore it is advised always to start off at position 00 with 80 00 00 00
as the value 80 is a special case trigger byte that will keep the vibrato
shut off for ever in the instrument where used.

Byte B is the vibrato speed. Try values $03 - $04 for a start.

Byte C is the vibrato width. Notice this width control is handled 16-bit in
player v17 - this is to make up for the lack of a calculated vibrato routine,
as in player v15 (it takes a lot of rastertime!). In other words, even in the
highest used notes you can still put on a vibrato that is very wide.

Byte D is unused in player v17.


The filter table
----------------

As said earlier in these instructions you must always start of your filters
at position $04, hereby not only looking at a certain number of bytes but
also putting the filtering "on" (a value of 00 in the instrument turns OFF
the filtering). The first four bytes has been reserved for use in the packer.
Please remember to ALWAYS keep the 3rd byte in this table at 00, otherwise
your music will sound like a bad joke! I will return to this byte later.

The funny thing with this table is that even though it seems like you must
point to it using pointers at steps of 4, like 04, 08, 0C etc, it is far from
correct. In player v17 there is no certain rules for this. You may start off
at, say, position $0B and type a filter program up to f.ex $17 and then stop
it here! The bytes that you can use here does NOT follow a predefined byte
length or position, it works more like an arpeggio program in the arpeggio
table.

When you start of at Eg, position $04 you start by typing the RAW $D416
values, that is the filter frequence values. When you want to stop the byte
sequence you then enter a wrap-mark, $FF followed by a wrap-to byte. It
cannot be simpler than this! This sure opens up the possibilites of making
strange and different filter sounds - needless to say, every filter byte is
put in $D416 in the SID chip every frame (1/50 of a second).

If you want to have a filter start at $80 and decrease in steps of $10,
ending at $30 you f.ex type:

         04: 80  70  60  50
         08: 40  30  FF  09

As you can see the $FF endmarks points to the $09th position, wrapping to the
$30 byte all the time. The wrap-to byte makes it possible to constantly wave
the filtering all the time. As an example:

         04: 80  70  60  50
         08: 40  30  40  FF
         0C: 07  --  --  --

Here the filtering start at $80, goes down to $30 in steps of $10 and then
runs between $30 and $50 all the time (until a new note is stroke of course).
All because the wrap-to mark after the $FF end-mark points to the $07th byte.

The only limitation to the length of the filter program is the size of the
filter table itself. You can theoretically fill up the entire table from $04
to $FF with just one filter sound if you wish...


The slide table
---------------

This table have been greatly simplified compared to player v12. When you look
at it in this player, the simplicity will seem like an opposite action upon
the complexity of the table in player v15, which had both hard restart, slide
and vibrato in here.

Now, you have only ONE bit to care about, that's all! Look at this...

         01  20 - slide up at speed $0120.
         80  60 - slide down at speed $0060.

As you can see the 7th bit in the first byte decides the direction of the
slide. The rest is entirely defined for stating the sliding speed. You may
wonder where the 5th bit function has gone - the one that defined whether the
slide would appear on a note or on a +++/--- spot - but as I found a way to
program player v17 differently around this problem I found a way to abandon
this rather confusing bit function. So, now you only have to think of where
to go... up - or down! And you can put the Sxx command whereever you like...


Tips and restrictions
---------------------

Before you rush to your screen and start composing in this wonder player (!?)
there is a few things you need to know...

1. The hard restart in this player is implemented inside the player in such a
   way that it cannot be removed. All instruments has a hard restart timer at
   $2, which is the most common used setting anyway. This may seem to "cut" of
   very quick drums sometimes - however this problem can be solved by creating a
   special "quick-drum" instrument in which you loop an arpeggio program
   simulating quick and fast drums-in-a-row.

2. Because of the un-removable hard restart timer at $2 it is impossible to
   use tune speeds lower than $2. If you try to use speeds $0 or $1 don't worry
   that the player will crash, it won't - it just doesn't work properly. This is
   not a bug however. The hard restart coding requires at least 2 frames to
   work.

3. When packing a tune made in this player v17 it is just as recommended to
   set the fourth byte in the packer's "F6" funtion as it was in player v12.
   When you set the byte to $01 the raster-time will approx. be $14 scanlines -
   if you forget it however, the routine will take around $18 - $1B scanlines
   (which still is nice though!). It is strongly suggested to set this byte
   though as it is about time we make music in a routine that takes very little
   time. When composing music inside the editor it is strongly recommended that
   you put +++ after the notes where possible! (+++ is SHIFT SPACE!) The reason
   for this is that most real-time routines may "loose a frame" when passing
   from +++ to --- in the sequence, so to speak. If the instrument used in a
   voice/seq is very arpeggio based (like a chord) then use +++ all the way to
   the next note if possible. If the instrument is more vibrato based (like a
   leader) then this rule is not that important. Sometimes you may however even
   encounter a change in the ADSR behaviour when packing and setting the 4th
   byte in the packer - this again can be cured by setting a lot of +++ after
   the notes in the editor.

4. As you might have guessed now, the first THREE bytes in the filter-table
   is actually not used. It is the FOURTH byte that is used in the packer. If
   your music should happen to sound extremely weird suddenly when working in
   the editor then check if the fourth byte in the filter table (position $03!)
   is a $00 - it should always be this in the editor!

5. Extremely quick (close notes) in the editor at tune speed $2 (notes that
   has no space for +++ or --- between them) will not work in this player,
   because of the hard restart timer at $2. However if you use the tienote
   function (***) you WILL hear them all as the tienote function in player v17
   has been designed to bypass the hard restart effect. Very logically,
   actually.

6. Sometimes when working with music that does not activate all voices right
   from the start you may encounter uninvited "buzzing" from the voices that was
   supposed to be silent. This is easily solved though. Try creating an "empty"
   instrument using ADSR 00 00 and waveform 00 and put it in the other voices
   right from the beginning complete with a note and following +++'es. The
   buzzing should then most certainly disappear.

7. Note that neither the fine-tuning option (normally accessed with SHIFT F)
   nor the volumen option (normally accessed with SHIFT @/*) is available in
   player v17. They were removed to save rastertime.

8. Also note that the actual sliding speed (when using the Sxx commands)
   differs when using vibrato on the instrument. This weird difference, which
   can hardly be called a bug, shouldn't bother you too much though.

This concludes the instructions for the 17th player for the JCH editor. I
hope you will enjoy this player as much as I do, it really cheers me up to
have what sounds like a hi-tech player yet takes very little time - and
memory too! Try doing some music in this player and pack it - then compare
the blocks it fills up on the disk with player v15 - this new player is
surprisingly small. Not only because of a smaller player routine, but also
because you don't have to put all those darn Sxx everywhere to create a hard
restart like you should in player v15... also notice that the hard restart in
this player is much harder and precise than in player v15. All in all I think
I did a good job this time - however it is not impossible that I might
enhance this player in the future with f.ex. the choice of changing the
filter passband.

PS. You may wonder what became of player v16. Why the hole? Well...the player
WAS made, but put on ice because of a surprisingly number of adapting bugs
inside the editor. I might take a look at it again some time as it had some
features not seen in any of my other players. But let's see now...

* ADDENDUM 20/8-1995: As you might guess, I never came around to player v16
* again, and never made any music in it. Of all the music released by all the
* musicians who made music in my system, not ONE of them was made in v16.


JCH of VIBRANTS.

