VIBRANTS MUSIC UTILITIES FOR COMMODORE 64
INCLUDES THE LATEST JCH EDITOR, PACKER, ETC.
UPDATED 18 JULY 1998 BY JENS-CHRISTIAN HUUS

If you want to get the most out of this package, I recommend that you read this entire file
as it contains valuable information about the use of the music editor utilities.

In this package you should find the latest version of the popular JCH NewPlayer editor,
complete with packers, relocators, worktunes, various players, instructions, assembler
sourcecodes for everything (even the editor), and many other related things. In short, I
have tried to collect all the utilities needed to compose and pack tunes on the C64. I did
not include my prototype editor for digitunes, however, as this editor was too awkward to 
use efficiently. All the utilities are available in this package in the form of .D64 files.

You are free to use both the utilities and the sourcecodes in any way you see fit, both in
C64 emulators and on the original Commodore 64. I take no charge, not even for game tracks.

Note that the old 1,3 Mb package from 1995 which contained music utilities, SID tunes, and
D64 files is no longer supported. The contents of this package have been rearranged and
presented in smaller chunks instead - this archive being one of them. This new archive
is superior to the old 1,3 Mb package because I added Syndrom's excellent utilities. Tunes
released for SidPlay by JCH have been moved to different archives especially dedicated to
such tunes. Please pay a visit to our homepage if you wish to download some of this SID
music. Of course, you will also be able to download all our FastTracker II music here, as
well as SID music from other members of Vibrants.

Please check that this archive contains the following files:

	FILE		SIZE		DESCRIPTION

	D64.ZIP		874748		Contains all the .D64 files for C64 emulators
	ED_TEXTS.ZIP	316088		Various instructions for the music utilities
	ED37_SRC.TXT	96170		The entire sourcecode for Editor v3.03
	README.TXT	15237		The file you are reading now

The following sections contains important information about the utilities. If you plan on 
using these utilities, I recommend you read all of it.


THE .D64 FILES

All the files found in "D64.ZIP" can be used with all the excellent C64 emulators for the 
PC. At the time of writing this, I recommend CCS64 by Per Hkan Sundell, but other great
emulators exists such as C64S (discontinued), Frodo, and Vice. The latest version of CCS64
is available at http://www.computerbrains.com. All other emulators can all be downloaded 
from e.g. http://www.commodorezone.com.

If you just want to manipulate and copy from/to the .D64 files (possibly because you want
to transfer the files to a real Commodore 64 later), I strongly recommend that you fetch a
copy of "The Star Commander" by Joe Forster/STA. This is a great "Norton Commander"-clone
which even speeds up the Commodore 1541 drive when used with the X1541 cable.

Here is a list of the .D64 files which can be found in the D64.ZIP archive:

	FILE			DESCRIPTION

        D_DRV_51.D64		Delux Driver v5.1 sources and objects
        ED3_04.D64		Editor v3.04 objects
        JCH_SRC.D64		Sourcecodes for packer and players
        JCH_UTIL.D64		Editor, packer and other utilities
        WORK.D64		A few worktunes for the editor by DRAX and JCH

In "D_DRV_51.D64" you will find all the object- and sourcecode files needed to create a new 
version of the "Delux Driver", a program I used to present all the music packed in my
NewPlayer system. The driver identifies initials in the end of filenames ("....\JCH") and
uses them to display the full name in the driver. Of course, this meant that all composers
who used the editor had to be "registered" for this driver.

The file "ED3_04.D64" contains all the objects which must be linked to form the executable
RUN file found in the bottom of the directory. The actual sourcecode is present somewhere
else in this package, as it is not a C64 editable sourcecode. More about this later.

In "JCH_SRC.D64" you will find the latest sourcecodes of "NP-Packer v5.3" (The latest
packer I made) and of players v17.G1, v19.G1 and v20.G4 (the three best players for the
editor). There are also the sourcecode to the digiplayer I made.

I believe that "JCH_UTIL.D64" will be the most important .D64 file for all those freaks
still working on the C64. Here you will find the latest editor, packer, swapper and other
useful utilities for making music on the C64. More about this later though. Note that this
file now also contains a few interesting utilities from "The Syndrom" - such as e.g. his 
excellent depacker utility.

The file "WORK.D64" contains a few worktunes from DRAX and JCH which you can load into the
editor, and edit or play. These tunes only scratches the surface, however. If you visit our
homepage and download all our SID worktunes (the "unreleased" ones), you will have access
to an impressive library of worktunes, all editable in the music editor. All you have to 
do is to transfer them to .D64 files using e.g. "The Star Commander", and you can then load
them from the usual disk menu in the editor.


THE MUSIC UTILITIES

All the very latest versions of all my utilities has been released in this package. It
includes NP-Packer v2.5 (for old players), NP-Packer v5.3 (for new players v10 and up),
Data-Swapper v1.0 (swaps data between different player versions) and of course the Editor
v3.04 with a lot of "+" merge files. Apart from using these in the emulator you can of 
course transfer them to a real C64 and make music there too. Either way, I supplied loads
of DOCS for the editor and players in the "ED_TEXTS.ZIP" file. There are two versions of
all textfiles, TXT for PC usage and SEQ for C64 usage - if you want to print or read the
text from the C64, only transfer the SEQ-files. However, I recommend that you read the
TXT-files on the PC since these are easier to read and has been especially enhanced with
ADDENDUM update text during the production of the collection in 1995. All the documents
were written at the same time the players were programmed, i.e. 1989-91. This means that 
you will be able to catch my enhusiasm for the editor and players of that time, but you
will also have to deal with my questionable grammar and spelling! ;)

You can read all the DOC text for deep information about the details of the editor, packer,
players, keys to use, and so on. However, even though these files were quite thoroughly
written, I still need to add a few things:

* I recommend that you print the MEMO-TEXT documents which was designed to fill
  out exactly one page. These are very helpful when making instruments.

* Although you have a wide range of players available for the editor, always
  choose between v17.G1, v19.G1 or v20.G4. Here are the differences:

        v17.G1 - Good compromise between v19 and v20. Uses only $14 scan-
                 lines, but has a "hardwired" hard restart. Sounds clear.

        v19.G1 - Extremely cut-down player using only $0D scanlines! :)
                 There is no vibrato routine and a very HARD restart.
                 However, the arpeggio is MUCH better than in "Music
                 Assembler" and its clones.

        v20.G4 - Although it only takes approximately $1F scanlines it is
                 the best player I have made. It almost makes coffee! ;)

  If you want to make double-, triple- or quatrospeed tunes, use v17.Q0 which
  is a modified v17.G1 containing the $1006 update routines. This player will
  default to DOUBLE in Editor v3.04. Use the "+" merge files to change the
  speed of this player.

* Editor v3.04 does not like player versions below v05.02. If you try to load
  v04.13 or v05.01 into it, you better reach for that reset button...

* There are two clocks in Editor v3.04. The rightmost is the tuneclock and the
  leftmost clock is measured hours and minutes you have been composing your
  music! :)  This clock will be saved together with your tune on the disk.
  This way you can see how long it has taken a composer to finish a tune.

* The merge programs which the editor can use always starts with a "+". These
  special files will be loaded by the editor without clearing anything. The
  files containing player versions can be used to overwrite a music routine
  with a fresh copy without touching the composition or instruments. This can
  be useful if the player screws up for some reason. The "+SPDC/VOL/TRIPLE"
  files (and similar names) changes the speed of the v17.Q0 player.

* The keyboard DOCS has been written for Editor v3.02 yet the latest version is
  v3.04. Well, the differences are marginal! From v3.02 to v3.03, player v20.G4
  is default and the merge program "+SPDC/VOL/DOUBLE" is default. The "SPDC"
  refers to the ability to change the speed of the "SHIFT-B" mode (FollowPlay)
  while playing. v3.02 did not understand this if the player changed the speed.
  Also, "VOL" refers to the volumen nibble in the top right corner of the screen
  which goes from 0-F in hexadecimal. v3.02 didn't understand this either if
  the tune changed the global volume during a tune. From v3.03 to v3.04 I fixed
  a bug which made the editor crash on a Commodore 128 or a portable SX-64.

* Suppose you only want to play with the editor and you just want a few fast
  instructions on how to do that. Well, read on! Run the editor, insert diskette
  with tunes and press F1 (if you are using the emulator, read the DOCS on how
  to change the diskette). Now cursor up and down through the directory and
  press enter to load a tune. Notice that the version number in the lower left
  corner changes to match the version of the tune you just loaded. Now press
  the F8-key. In the editor, press SHIFT-B to play with "FollowPlay". This mode
  restarts in the top when the tune wraps, so you can always see when the tune
  has ended. Press RUN-STOP to stop and SHIFT-X to enter the diskette menu again.

* The volume setting in the upper right corner of the screen (use SHIFT-@ and
  SHIFT-* to change) was invented in later players. Prior to player v15 (and
  in compromise players like v17 and v19), this value should not be changed
  since it might screw up the player. Use the volume knob on your monitor or
  loudspeakers instead! ;)

* Although I recommend that you stick with players v17, v19 or v20 if you want
  to make music, it is possible to make music in the older players. If you
  make music in players v5 - v9, use "NP-PACKER v2.5" to compile the music to
  a small, compact block. Are you using v10 - v20, use "NP-PACKER v5.3". This
  packer is much more efficient than v2.5; it removes unused commands and
  sequences apart from pushing the tables together.

* The "Data-Swapper" found on the utility disk is really a ghost from when I
  created the first versions of the editor and packer. I cannot guarantee that
  it will work with later players v17, v19 and v20. In fact, I never really
  used it myself...

* In the "Delux Driver v5" you can find a very sophisticated relocator which
  also splits up the music block into five parts. This "splitter" took me a
  long time to write. However, a faster and more simple relocator can be found
  on the utility disk, made by "Xerox" - a coder I knew on the C64. It only
  relocates the same block - however, it is extremely fast indeed.

* Don't mind the "Ed-Ideas #02" too much. It was a RUN-file I once created on
  a day I was bored, containing some of the ideas I wanted to make - but never
  did. Now that the sources are available in this package, perhaps YOU can use
  some of the ideas? :)


THE SOURCE CODES

As mentioned earlier, I have supplied all the source codes for my editor, packer and
players for you to have fun with. You may transfer them to a real C64 when possible, and
you are free to make any changes you want. All of the sources contains the very latest
versions I did. I won't go into too much detail on how to compile and use the sources. If
you are a cool C64 coder you should know what to do with it. Still, let me point out a
few things anyway.

* Most of the comments in the source codes are in DANISH! I'm sorry for the
  inconvenience this may cause, still it should be possible to figure out what
  goes on! :)

* The "Ed v3.04 objects" only contains the files to be LINKED. No sources here.
  In the file ED37_SRC.TXT, you will find an enormeous source code containing the
  actual code for the editor, which additional comments on the objects in the
  beginning of it. In older versions of the editor (like v2.53), I coded the
  entire editor in "Turbo Assembler" directly on the C64. However, I soon ran
  out of memory space as I got more and more ideas to implement. The only thing
  to do was to buy the Amiga-to-C64 development tool from Einstein/Upfront, a
  coder who made a complete assembler on the Amiga which generates C64 code
  together with the electronic devices necessary for transferring it. Using this
  magnificent system I managed to add more functions to the editor, right up to
  version 3.03/3.04 which is the sourcecode you can find here. Please don't ask me
  how you're going to use it if you don't have a similar equipment, but if you
  do, you are free to make any changes you want! :)  I know that C64-to-C64
  systems exists which should work just as well.

* On the SOURCES diskette you will find the source codes for the three players
  I recommended earlier in this file. The "01.D5" source is for the NMI digi-
  player and "B5.10.B000" is NP-PACKER v5.3.

* In some of the source codes, I often assembled them to a different location
  than it would be when used in the final product. As you may already have
  figured out by yourself, this is caused by the fact that "Turbo Assembler"
  occupies memory location $A000-$FFFF. However, by the ORG commands in the
  source codes I have put comments on the temporary locations. This is true to
  the source codes of "NP-PACKER v5.3" and "DELUX DRIVER v5", but not to the
  players which are assembled to their correct locations.

Have fun with the source codes. If you manage to develope another (perhaps even better)
player, packer or editor using these sources - then why don't you send me a copy? I would
be very happy to see what you have done. 


ABOUT VIBRANTS

We are a group who specializes in music for computers. Visit our homepage
at http://www.vibrants.dk for more information about us. There, you can also
download most of the music and programs we have ever done in Vibrants.

Handle		Real name			Email

Drax		Thomas Mogensen			SORRY, NO EMAIL
Jch		Jens-Christian Huus		jchuus@post8.tele.dk
Jo		Poul-Jesper Olsen		jo@ite.dk
Laxity		Thomas Egeskov Petersen		thoege@udd.aardassem.dk
Metal		Torben Hansen			torben_hansen@sja.dk
Msk		Morten Sigaard Kristensen	msk@post8.tele.dk

Together with Jeroen "Wave" Tel, Drax and Laxity also make music in Maniacs
of Noise. Go to http://xs4all.nl/~mon/ if you want to check it out.

