COMMODORE PLUS/4 WORLD
  Home  Search  Games  Tapes  Covers  Cheats  Maps  Software  New Stuff 
 Hall Of Fame  HVTC  Game Endings  Features  Solutions  Remakes  Publications  Magazines  Effects  Top List 
 Members  Groups  Plus/4 Encyclopedia  Hardware  Tools  Options  Forum 
Login
SIDwinder V01.23
Title:SIDwinder V01.23
Category:Utility/Music
Release Date:
Language:English/Hungarian
Size:64K
Device Req.:Disk only (1 side)
Machine:PAL Only
Code Type:Machine code
Distribution:Freeware
Converted by:H., Levente (TLC)
Notes:Original (V01.22, for C64) by Taki/Natural Beat. Also available for C64 and in source distribution. May also work on NTSC machines for single speed tunes.
  Download:
Download from Plus/4 World
Plus/4 World
Download from Rulez.org
Rulez.org
Download from Zimmers
Zimmers
Download from ko2000
ko2000
  Fixed packer:
Download from Plus/4 World
Plus/4 World
Download from Rulez.org
Rulez.org
Download from Othersi.de
Othersi.de
  Source included:
Download from Othersi.de
Othersi.de
  Source:
Download from Rulez.org
Rulez.org
Download from ko2000
ko2000
User Rating: 9/10 (11 votes)
SIDwinder V01.23 Screenshot


Effects
PartEffect nameParametersNotes
SID Support 


Instructions
This is the summary of features file of SIDwinder V01.23

01 Brief list of features
-------------------------

- up to 32 subtunes in one music file
- up to 96 sectors (256 instructions per sector)
- up to 64 different instruments
- up to 16 times music speed (supported by the editor)
- volume register ($1673) and volume control register ($165D) for
independent external volume control


02 Keys
-------

02.01 General
-------------

F1 play/restart actual music
F3 stop any kind of playing
F5 continue stopped playing
F7 fast forward (while held down)
F2 play a single sector
F4 enter liveplay (sfx) mode
F6 select next subtune of $01...$1F
F8 select previous subtune of $01...$1F
<- toggle track+sector screen / sound screen
, . / toggle on/off SID channels 1/2/3

In the Plus/4 version, the keys are mapped to their respective equivalents.

F1 play/restart actual music
F2 stop any kind of playing
F3 continue stopped playing
HELP fast forward (while held down)
F4 play a single sector
F5 enter liveplay (sfx) mode
F6 select next subtune of $01...$1F
F7 select previous subtune of $01...$1F
ESC toggle track+sector screen / sound screen
, . / toggle on/off SID channels 1/2/3


02.02 Editor subparts
---------------------

SHIFT+1,2,3 track editor
SHIFT+4 sector editor
SHIFT+5 glide/slide table edit
SHIFT+6 disk menu
SHIFT+7 music options

In the sound editor:

SHIFT+1 sound editor (main parameters)
SHIFT+2 wave/arpeggio table
SHIFT+3 filter table
SHIFT+4 pulse width table
SHIFT+5 glide/slide table
SHIFT+6 slide/vibrato table
SHIFT+7 track start positions


02.03 Track editor
------------------

+ Tr+XX
- Tr-XX
SHIFT S ...XX (sector number)
SHIFT V VolXX
SHIFT D DecXX
SHIFT I IncXX
SHIFT H HltVS
SHIFT J JmpXX
(Pound) Set subsong start pointer to cursor position
DEL Delete command at cursor position
INS Insert ...00 at cursor position
SHIFT RETURN Enter sector editor (sector selected by the cursor)

INS and DEL updates all affected Start pointers and Jmpxx commands.


02.04 Sector editor
-------------------

SHIFT S Snd.XX
SHIFT D Dur.XX
SHIFT V Gld.XX
- ------
SHIFT H +++
SHIFT F Finish
SHIFT + or ; select next sector of $00...$5F
SHIFT - or : select previous sector of $00...$5F
RETURN copy the whole actual sector to a buffer
up arrow paste the buffer into the actual sector
DEL Delete command at cursor position
INS Insert --- at cursor position


02.05 Sound editor screen
-------------------------

+/- select next/previous instrument of $00...$3F
SHIFT +/- increment/decrement pitch of test note
SPACE test actual instrument (in liveplay mode)
RETURN copy the actual instrument into a buffer
up arrow paste buffer into the actual instrument
SHIFT RETURN enter effect table (selected by the cursor)

INS insert command at current position
DEL delete command at current position

The Ins and Del keys are present in all effect columns; they both update all
affected jumps and other references.


03 Commands
-----------

03.01 Track commands
--------------------

...XX play sector number $00...$5F
Tr+XX transpose up by $00...$3F semitones
Tr-XX transpose down by $00...$3F semitones
VolXX set a constant global volume of $00...$0F
DecXX decremental volume slide at speed $01...$07
IncXX incremental volume slide at speed $01...$07
HltVS halt volume slide, keep the current volume
JmpXX jump to position $XX in the track table

All commands occupy a single byte, except for Jmpxx.

A sector replay may be preceded only by the following ordered list of
instructions:

one JmpXX,
one of IncXX, DecXX, HltVS or VolXX,
one of Tr-XX or Tr+XX


03.02 Sector commands
---------------------

Snd.XX select a sound/instrument of $00...$3F
Dur.XX set note duration to $01...$40 frames
C-1 - A#8 play note (selected instrument, for selected duration)
Gld.XX glide ($01...$0F) or slide ($11...$1F)
------ a delay unit, plus release actual note
+++ hold actual note, stay in sustain stage
Finish End of sector

Like the track commands, the sector commands also must follow a predefined
order.

one Snd.XX,
one Dur.XX,
one of glide, slide, ---, +++ or a single note,
one Finish


03.03 Sound editor
------------------

The 7 digits are denoted like this:

- Attack, Decay
- Sustain, Release
- Gateoff counter
- Wave/arpeggio table position
- Filter table position
- Pulse width table position
- Slide table position

Attack and decay are the respective volume envelope settings for the SID. The
gateoff counter decreases with every frame, and toggles the channel key bit
off when reached 0. The remaining position pointers are pointers to the
appropriate effect program tables.

A $00 in the Filter, Pulse or Slide position means that the effect will be
switched off, whereas entering $ff results in not touching the effect machine
parameters at all (an active effect, if any, will keep on running).


03.04 Wave/Arpeggio table
-------------------------

WF $00...$8F -- current waveform = WF, arpeggio offset = AR
$90...$FE -- repeat last waveform with a new arpeggio offset
$FF -- jump to the position specified by AR
AR arpeggio offset or
jump position


03.05 Filter table
------------------

RP $00...$FD -- repeated addition to frequency and resonance
$FE -- select filtertype specified by FH
$FF -- jump to the position specified by FH
FH addition to cutoff frequency high byte or
filtertype (bits 6 to 4) or
jump position
RL addition to resonance (bits 7 to 4) and
addition to frequency low byte (bits 2 to 0)

When a filtered instrument is initialized, all the filter parameters, including
the filtertype, are set to zero. That means, the initial cutoff frequency and
resonance must be 'added' to these zero values by the filter program. You must
set the filtertype, too, otherwise it will remain zero (which means, the filter
won't pass anything at all). The player will update $D418 with the result of a
logical OR between the current volume and the filtertype you specify, therefore
you should always set the lowest four bits of the filtertype to zero.


03.06 Pulse width table
-----------------------

RP $00...$FE -- repeated addition to pulse width
$FF -- jump to the position specified by PH
PH addition to pulse width high byte or
jump position
PL addition to pulse width low byte

Similarly to the filter effect, whenever the pulse effect is reinitialized, the
pulse width registers will be set to zero. The first line of the pulse program
usually adds an initial pulse width (a larger value), which the next few lines
increase or decrease.


03.07 Slide/Vibrato table
-------------------------

RP $00...$FD -- repeated addition to actual frequency
$FE -- set absolute frequency FH/FL (drum mode)
$FF -- jump to the position specified by FH
FH addition to frequency high byte or
absolute frequency high byte or
jump position
FL addition to frequency low byte or
absolute frequency low byte

While a glide/slide command is executed, the vibrato is inactive, but keeps
in sync.


04 Miscellaneous
----------------

- Please fill the sectors up sequentially. If not, when saving, all sectors
after the first empty one will simply be lost. In the editor save routine,
a sector is considered used if there is at least one Finish command in it.
- If a track contains no JmpXX instruction (preferably, at the end of the
sector list of the track), then it's considered to be unused and thus will
not be saved.


General
(C) 1994-1999 Balázs Takács
(C) 1999-2000 Levente Hársfalvi


Welcome to the documentation of SIDwinder, the ultimate SID music composer
package...

This text holds information about the story and the rather general things
around this editor.


Table of Contents
-----------------

01 The story
01.01 In the beginning...
01.02 Taki's point of view...
01.03 Finally...
02 Thanks...
03 How to start...
04 Detailed info
04.01 The editor
04.02 The packer
04.03 The ASCII viewer
05 Possible improvements...
06 Contact



01 The story
-------------

This is - as you, I think, guessed well without my explanation - a music
composer package with the appropriate tools. Please let me first tell a few
general things behind the development of this package.


01.01 In the beginning...
--------------------------

First, I'm not a C64 SID musician at all. Not even a 'fundamental' C64
programmer and scener. I just like good musics, and good _synth musics in
particular (...whatever good musics in which oscillators, filters, envelope
generators are involved :-)). My past was rather spent on the Plus/4 scene
since I became a Plus/4 programmer. I coded lots of music 'player' routines
on the Plus/4 - these are often referred as 'music converter routines',
since they make play original C64 tunes on the Plus/4 someway. I've dreamt
of coding a good music composer since a long time (...come and read those
20-30 pages of text I wrote back in '94 as plans / parameters / fileformat
etc. of the DreamTracker ;-) ). However, I never got around to code just a
single byte of the editor; the reasons should be all about the fact that I
never had the appropriate hardware (or if so, the knowledge for the
hardware), the examples, not to mention that I used to be lazy :-/. There
were no _real examples for me on the Plus/4 scene - all 'music composer'
packs had problems somehow, or maybe it was just me who was sick of them so
much :-/. From the other hand, I had no real contact to the C64 scene back
then, thus I had no access to the recent C64 SID music editors - so I never
really had example of good editors. I only knew Future Composer, the
Rockmonitor series and the V1.0 Voicetracker - all had their problems IMO, I
never managed to learn their sometimes weird usage - obsolete player
parameters, lack of readable / even correct documents and so on.

From the other hand, years have passed. Still nobody introduced a _really
useable music editor for the Plus/4. The reasons, if we look for some,
may be behind some facts. The main problem, the good old black (O.K. you're
right - charcoal grey ;-) ) dustbin was introduced without decent sound
capabilities, the TED is really annoying in contrast of the wonderful SID
chip. Really few people made attempts even trying to compose on this machine.
With this, also few people were interested in the tools one could use for
creating tunes on/for the Plus/4. After the early 90's, most Plus/4 sceners
rather used 'converted' musics that were originally composed on the C64. Not
much later, in around 1992, few people (Csory, BSZ and finally, Solder)
designed SID cards to make play the SID tunes better than _any converter
routines could do.

With the presence of the SID card, someone could have also converted a
native C64 music composer package to the Plus/4. ...I don't really know of
such an attempt, maybe, only an old Future Composer version that was slightly
modified to play through the SID card. ...Lack of interest? ...Maybe. Another
reason could be that C64 music editors were really proprietary back then.
Except few known examples, like the above ones and the DMC series, one could
have hardly got just a copy of a good music composer package, still not
speaking of the source code that should have been _impossible to obtain. Facts
are facts, after all. This is sad, but the spirit was rather different to the
one signed with Richard Stallman, the Free Software concept...

As I see, nobody, except few people tried to compose something using native
Plus/4 composer tools. The majority rather took a C64 and did something using
DMC, or - most likely - simply ripped tunes and used them with no permissions
from the authors at all.

Years have passed, again. From my viewpoint, I learnt a lot of practical
knowledge that could have helped me to realise the dream. The most important
one is cross-development: it is much easier to edit sources and compile the
code on a dumb, but powerful PC than on a Commodore platform. Table Driven
Assembler is still my favourite. Later, I coded a small utility, ComLink,
supporting the additional small tasks this method involves. In the meantime,
a lot of C64 programs became accessible for me, because they got uploaded
to various FTP sites (the spirit has changed a lot, after all...).

In the summer of 1998, I started converting Voicetracker, but I soon gave it
up. I reverse engineered the code, but after doing all modifications to make
the stuff compile and made it _start running on the Plus/4, _everytime I
made just the _slightest modification, it crashed :-(. This behaviour shows
that something was wrong, still in the reverse engineering process... (some
indirect memory references should have been missed in the original code).

One year later, Taki announced releasing his SIDwinder V01.22 pack. I
downloaded and checked it - and found it very nice! This was the very first
music composer pack for me that came with full - and _very well written -
documentation, tips and so on coming right from the author. The pack also
included all needed utils and a lot of example songs (composed by Taki) in
loadable source format. ...I still haven't mentioned that Taki's player was
really well optimized and had good effects to play with ;-).

I think the opportunity of converting SIDwinder had some real points I
couldn't have missed: the editor and the player were good, had good
documentation - and after all, I could contact with the author himself and
ask him for the sources, and some help. I simply couldn't resist myself to
do so :-)...


01.02 Taki's point of view...
-----------------------------
(Written by Balázs Takács (Taki / Natural Beat), creator of SIDwinder series
himself)

Some of you might be curious to know how the different versions of SIDwinder
relate to each other. TLC kindly allowed me to waste a few words here about
the background of the development and a bit of history. So here we go...

The original SIDwinder V01.22 is about six years old now, I coded the player
and the tools back in 1994. For various reasons lying in the strange nature
of the old C64 scene, the package remained unreleased over the years. Then,
just about a year ago, a friend of mine asked for the editor -- so I decided
to finally release the SIDwinder V01.22 package to the public.

For a while, I was considering whether I should enclose the assembly source
files or not. I decided not to do so, because I wasn't particularly proud
of the editor and the rest of the tools. Unlike my player, which is highly
optimized, the tools were coded rather in a quick-and-dirty fashion. They
weren't intended to be released ever: back then the only goal I had in mind
was to put those tools together as fast as possible, so that I can finally
do something useful with my player. Besides, I could hardly imagine anyone
willing to tinker with such old and useless stuff.

To make a long story short, I released the binaries with the player source
only, which is the most valuable part after all -- in my opinion. Although
I planned first to release the package under the protection of the GNU GPL
(General Public License), I dropped the idea, since it would have required
the complete source to be included, of course.

A few months later I received an email from TLC. He was planning to create
a Plus/4 conversion of my SIDwinder V01.22, and asked whether I could send
him the source files which I failed to provide with the package. I agreed,
but as soon as I tried to actually collect the sources, I painfully noticed
that those old files simply vanished into the thin air. As it turned out,
somehow I lost a whole disk of source files, including all sources for this
version -- except for the V01.22 player itself, thank goodness.

All I could send TLC instead were the source files of an earlier SIDwinder
(to be precise, V01.20). Although those versions are indeed very similar,
they were certainly different enough to take TLC a month of hard work (not
to mention the bonus of having to mess around with memory layouts, keyboard
mappings and various obscurities I left in there without a single comment).
It must have been a tough nut to crack, but he succeeded in it; I must say,
I was indeed amazed as I saw the first results! TLC didn't only manage to
fully accomplish the Plus/4 conversion, but also improved my editor in many
ways and fixed a few bugs that I overlooked.

My packer has always been some sort of an experimental work; it was rather
spartan, regarding both its functionality and user interface. As my source
files were gone, TLC decided to develop his own packer instead of trying to
reassemble the old binary code -- which was utterly useless anyway. For a
second time, he surprised me and the Plus/4 scene with a fabulous tool: his
packer thoroughly optimizes the memory usage and removes every unnecessary
component while compacting the music data. Furthermore, it comes with lots
of built-in functions which you would normally find in separate tools only:
just look at the various relocation options.

All in all, TLC has done a great job; I'm sure that both sides of the 8-bit
scene will value his efforts highly. Now I'm handing the microphone back to
the author himself. Thanks for your attention.


01.03 Finally...
----------------

As Taki said, I had to re-generate the sources from the previous editor
code and the disassembled V01.22 editor code, using some smart (Recomment...
thanks to Jouko Valta and André Fachat) and some simpler (self-coded
quick-and-dirty Pascal diff) routines. Then I slightly edited the source
- partially to make it compile to Plus/4, and partially to eliminate a few
features that I considered annoying; why not to do it, if I was right in the
business ;-).

(As a short remark to Taki's kind words regarding the work I did: it was all
some kind of a second or third division league game compared to his work of
creating this series, doing his experiments, the player, the editor and so
on...).

I then coded a new packer, because of the reasons mentioned above. It is still
also much likely an experimental work, so please excuse its sometimes strange
behaviour - rather, you're encouraged to report bugs if you find some ;-).

While coding, I kept my eyes on _not doing anything that causes the code not
to compile to C64 anymore. This raised a question - I asked Taki because I
wanted to do a Plus/4 conversion, but then I had _both a C64 and a Plus/4
editor with the slightly modified code; the SIDwinder V01.22 I had became
_not V01.22 inside anymore. Then what? I asked Taki if I should release the
editor also for the C64 platform; he kindly agreed, and after some talks
about the version name/numbering/marking of the 'new' series, this became
the SIDwinder V01.23 pack you just hold in your hands ;-).

Finally, in agreement with Taki's opinion, I decided to make _all sources
available to the public, since this makes sure that whoever wants to fiddle
with the editor code - this way, may implement valuable features -, can
definitely do this.


02 Thanks...
------------

- Balázs Takács (Taki / Natural Beat) - for making this all possible
- Luca Carrafiello (Luca / Fire) - beta testing and demosongs
- Jouko Valta, André Fachat - Recomment reassembler
- Pasi Ojala - PUcrunch
- Speech Technology, Inc. - Table Driven Assembler
- Ettore Perazzoli, Daniel Sladic, ...the VICE team - VICE
- Mike Dailly - Minus4 1.6.2
- Balázs Kovács (Joe / STA) - Star Commander
- RIT Research Labs - DosNavigator V1.42
- Peter Schepers - 64Copy
- Borland Inc. - Borland Pascal and C

Special HiYa! goes to Coyote / Coroners.


03 How to start...
------------------

In general, the editor is almost the same as you may know as SIDwinder V01.22.
I only changed really a few things - you'll only notice that I fixed a few of
those bugs / drawbacks Taki mentions in his well written document of the
original editor.

For this reason, please read Taki's document that I decided to include to the
pack in original, with no modifications at all :-). Another document that will
probably help you in the first steps is the summary of features file. After
thinking it over again, I'd _strongly suggest to print out both documents and
keep them by hand. (You can do this either on a PC (or rather _any ASCII
compatible printer/computer/operating system) or your funky MPS series PETSCII
Commodore printer ;-). In this latter case, use the viewer routine's print
function.)


04 Detailed info
----------------

04.01 The editor
----------------

Well, really not much to tell about this part, since Taki documented it well
already (have I told you to go and read it? ;-) ). There are just a few things
you should know to avoid surprises.

First, there is no support for saving / loading bare memory images, as it was
present in all previous versions. The reason is simple: they became not
neccessary anymore. Until V01.22, the bare memory image was used for the
packer (it could load only this form). The V01.23 loads the same short
fileformat you used to save your musics.

(BTW, implementing them would have been hard anyway, because of the new
(different) memory map of the editor.)

You can load and edit songs created in the editors V01.2x (well, probably
V01.22 because the others were not public). The song data format was not
touched in any ways, except for the identity field (V01.22 --> V01.23).

When you're composing multispeed music, especially 4x and above, you'll notice
that the player calls are spread around the frame (approximately equal time
intervals between the calls).

Some other issues. The first few lines in the arpeggio table are not reserved
for the channel off function of the editor anymore. This function was
implemented with gate bit masking in the player instead. You can now use all
rows in the arpeggio table, plus you'll hear no awful clicking when you
switch off a channel.

Similarly, the last sector, $5f is no longer reserved for the liveplay function
- you're free to use it for your own purposes. When talking about this
function, I must mention that it was also recoded a bit - you'll hear no
clicks when you test your instruments.

Just one more thing to note: the editor was designed for PAL machines only.
The SID frequency value tables are for the PAL clock(s), and so are the IRQ
handler routines. The editor is not intended to run in NTSC machines for the
moment, though, it may start and run on them. Porting the editor to NTSC
won't be a hard work - just a matter of some coding.


04.02 The packer
----------------

This is an entirely new part of the package. When I was at the point of
reconstructing the old program code, I rather decided to rewrite everything
from scratch instead. This way, it was possible for me to keep the whole
mechanism under control - I could start with the loader, the memory map and
so on. I could also implement all features I wanted instead of tinkering with
the original - separate - relocator code.

Packer V01.23 loads the compact data format the editor handles. You can also
load and pack songs created in the previous editors of the V01.2x series.

The packing starts with some passes of parsing the data. In the packer code,
this is implemented with 'full' data examination (infos on the algorithm
can be found in the programmers info file).

This packer is a bit more forgiving to the composer regarding loose data,
instruments and so on than the predecessor packer routine was. You don't have
to edit all unnecessary data out from your music by hand before packing -
the packer will do that.

From the other hand, the packer needs a bit of precaution from you, because of
these tricks.

- First and most important, if you compose soundtracks containing more
subsongs, take care of NEVER letting your track tables overlap each other.
Overlapping can occur in every 8th subsongs, by mis-aligning the
appropriate start pointers of the subsongs (check Taki's SIDwinder document
on the purpose of Start pointers). If you do this, the packer will fail to
determine the length of the track tables of the subsongs, and this will
lead it to crash. So, before saving your song that you'll pack, always
check the start pointers in the sound editor screen - if your song contains
only one subsong, be sure to set all of them to 0.
- Take care of 'closing' your tables correctly - always place a JMPxx to the
end of your song data in the track tables, FINISH to the end of the sector
datas (these are BTW also needed by the editor I/O routines) and jump
commands to the end of the last effects of the effect tables.

If you follow these suggestions, you'll most probably have no problems with the
packer.

Since it is a new routine and still hasn't been under intensive testing,
you may find bugs when you use it. If you experience such behaviour, please
contact me.

The user interface of the packer is rather spartian; the same feeling as it
was coded in the good old BASIC ;-). From the other hand, it should do all
tasks you need in such a subject.

- Filename. Should be obvious. You have to enter the filename of your song
(the data file you saved from SIDwinder), or you can ask for directory
(of the current disk) by '$'.

- Number of subsongs (mostly, '1' :-) ).

- Start address in memory. The address you want the packed song to start at.
The value must be given in hexadecimal, without prefix (e.g. '1000').

- Reserved zeropage word. The player uses just one pointer on the zeropage,
and this is the $fb-$fc pair in the original SIDwinder player. Usually,
you don't have to do much with this setting - just enter 'fb'. Sometimes,
if your program, e.g. a demopart uses certain areas in the zeropage, you
can select another for the player to make them not to hurt each other.
(Thanks to Taki for suggesting me this feature).

- SID baseaddress. This doesn't seem to be much useful for a C64 musician -
just enter 'd400'. For the Plus/4 users, you should select it to $fd40 by
default (...I suggest to read the other file ('Plus/4 users'...)).

- Freqtable. This has also something to do with the platform you want your
song to be played on. Regardless to what platform you used when you
created the song, you should select the appropriate table for the _target
platform.
(The C64 SID and the SID in the Plus/4 SID card runs at a slightly
different clock - that's why they need different frq table. For more info
see the 'chapter' I mentioned above).

- Identity field edit. You have 32 chars to describe your handle, the title
of the song or whatever you find important to note in the music data :-).
The packer copies this text in screencode to the player start address +
$20 ($1020 by default). You find a 'ruler' above the input line. ...Well,
really minimal user interface, but it works.

Then hopefully, your song gets packed (if the packing doesn't finish in _few
seconds, that's bad luck since it crashed. Please contact me). Enter the
filename you want your packed file to be saved to. That's all.


04.03 The ASCII viewer
----------------------

I haven't wasted much words regarding this piece of code, although I think it
has its valuable features.

- Standard ASCII compatibility. Nonstandard ASCII chars are either converted
to space or their respective equivalents in the standard charset (e.g.
Hungarian accented letters).
- Can both view and print texts (printing on standard PETSCII printers, not
well tested).
- 80 columns display. 4x8 charset.
- End of line is determined by linefeeds ($0a). CR's ($0d) are skipped.
- TAB capability (TABs are converted to spaces)
- Standard file I/O, not well buffered (except for printing; a 256 byte
buffer is used).
- Runs on a C64, or a Plus/4 (even with 16K of RAM, so C-16 owners can also
use it).

In the viewer screen the Return, Space, Home and <- (on Plus/4: ESC) keys work
(page down, line down, go top and back to load text, respectively).


05 Possible improvements...
---------------------------

Well, there are so much I can't even count :-(.

- First of all, the player should not use absolute frequency data for the
effects at all.

- Digi channel(s). ...Would imply a lot of things to do, like:

- The above one (frq value independent effects)
- Reorganized editor (at least, track editor - to edit more than 3
channels, and new sound editor)
- Dynamic memory allocation in the editor (since it won't fit into the
memory anyway)
- A completely new NMI routine, in order to make those sounds play...

- Reorganized code for subsongs (because I hate 'start pointers')

- A lot of things in the editor code, to make it more user friendly. New
editor features, colors...

- Play native Plus/4 sounds through the TED (maybe simultaneously with the
SID channels).

...And so on.

Please don't seriously count on me to do these improvements. I like this
editor, but I think I should find some better use of my time... But you can
do all improvements, if you found the appearance of this pack promising.


06 Contact
----------

- Balázs Takács (Taki/Natural beat)

E-mail: [---cut---] (presumably available until 2001)
S-mail: Balázs Takács, [---cut---], Hungary

- Levente Hársfalvi (sometimes, but not really often, known as TLC / Coroners)

E-mail: [---cut---]
S-mail: Levente Hársfalvi, [---cut---], Hungary


Hopefully this pack, the sources and possible later versions will be available
at:

- Natural Beat's homepage: http://www.sch.bme.hu/~takinb
- The c64.rulez.org ftp site:
ftp://c64.rulez.org/pub/c64/Tools/Music/Editor/
ftp://c64.rulez.org/pub/plus4/Tools/Music/

- The Funet ftp site:
ftp://ftp.funet.fi/pub/cbm/c64/audio/editors/
ftp://ftp.funet.fi/pub/cbm/plus4/Tools/Music/


Specific Plus/4 Notes
Information for Plus/4 users
----------------------------

(I think I should have written this doc a bit earlier - I mean 'several
years ago', to give it real practical use :-(. I seriously doubt that even
despite the advantages of this editor, it could count on more than a few
users. But after all, it is here. It is here, it is powerful, and it is free.
Be it late or not... )

Here you can find infos on the use of the editor on Plus/4. You'll also find
this 'chapter' useful if you want your SIDwinder V01.2x musics (composed on
C64) be played on this platform.

Also a quick note for Plus/4 users: because of this whole lot of ASCII junk,
there was no space on the disk for including the GNU General Public License.
Please also obtain either the C64 or the source distribution.


Table of contents
------------------

- The platform
- The SID card
- SIDwinder for Plus/4
- When you finished composing a song...
- Some short notes
- And finally: how to redirect a player to a new base address?
- When moving a C64 tune to Plus/4...
- When moving a tune created on Plus/4 to C64 platform...


The platform
-------------

Before going deep into the editor and the player related things, we should
take the _reason of all differences, the hardware itselves. If you're a
Plus/4 programmer, you should know these properties I'll speak about - but
it's still neccessary to talk these out, to know the reasons of all.

First of all, a stock Plus/4 doesn't have such a good synthesizer chip that
the SID is. The built-in sound generators (included by the 8360 TED) are
rather cripple, and are rather similar to the soundgenerators of the old
VIC-20.

To play SID-originate musics on the black dustbin, you must either emulate
the properties of the SID chip by software (--> music converter routines) or
you should have a real SID chip interfaced to the Plus/4 (--> SID cards).
Both methods are possible - but the real hardware is definitely better than
any software based solutions, if the subject is the SID, and the emulating
computer is the Plus/4. (Emulating the SID correctly by software is a very
hard task indeed, just see _any SID music players on the PC).

Here I'll rather deal with the SID card, since I considered implementing a
music converter routine to the editor both hard and inappropriate.
(Implementing one would have costed me a lot of work, since it implied to
reorganize the IRQ routines and some of the memory map - and it would have
caused a lot of trouble, since no music converter routines emulate the SID
correctly. This latter is just annoying if you try to get a demopart to
work, but it becomes something more serious if you're using your computer
for composing music - a music that may thus fail to play correctly on a real
SID).

As speaking of SID cards, I know of three attempts, of which two were really
useable and just one that was spread 'widely'. The editor code assumes this
latter, the Synergy SID card (by Solder) to be present (at $fd40).

O.K. now we have a SID chip interfaced to the computer, what's next?

The another thing you should be aware of, that the processor clock of the
C64 and the Plus/4 are different. This should not be significant in such a
subject, but it turns out to be so if the subject is the SID chip and this
card. Unfortunately, the counters inside the SID are based on the same
processor clock the one the chip is synced to the processor bus. The C64 runs
at 17.734472Mhz / 18, whereas the Plus/4 single clock is 17.734472Mhz / 20
(PAL machines). A SID, running at the Plus/4 single clock runs at 9/10 times
the C64 clock, resulting in everything you should suspect: lower frq of the
voices (about one note) and longer Attack / Decay / Release times (ADSR).

I think these were the two main reasons of all problems you may experience
when you're composing something.

There are some less important differences between the computers, at least,
in the scope of this program. I could mention the keyboard, the memory
mapping and so on, but they're not significant (at least not from the users
point of view).


The SID card
------------

Since this is the 'base' of all music composing in this editor, I thought I
should write some words regarding this device. In short, the card is a
clear, compact design; for example, the address decoding is based on a GAL.


- The card contains a 8580 SID (Solder told me, the 5v to 9v DC-DC
transverter is not able to supply the 12v Vdd to the 6581 SID. I know
this chip, since I also used it for my design (thanks Christian!), and it
can for sure generate 12 volts from a single 5v supply, but maybe not that
current the 6581 SID would need at its Vdd input).

- The clock of the SID, as I mentioned, is the single clock of the Plus/4.
Regardless of the actual processor clock, the card always supplies this
frequency to the SID (thus making it possible to run your programs with
twiee clock enabled. Not an obvious feature as you'd expect - the card
has a dedicated chip (the 4520) for the task).

- The card has both an audio input and an audio output 3.5 jack connector.
The input is fed to the audio input of the SID, the same way it is seen
in the C64. The output can go directly to your stereo amplifier system
:-). The SID output can be also fed to the computers audio input, thus
mixing the SID voices to the TED sounds (can be selected by a switch).

- The audio output level can be adjusted by a trimmer on the card.

- There is a full featured joystick port on the card, including the SID
paddle (A/D) inputs.

- All SID registers are accessible, even the read-only registers of voice
3 and the paddle registers.

- Somehow, the SID on the card plays digis back correctly. This issue is
also not obvious, since C64s equipped with 8580 SIDs tend not to play
digi sounds at all. Something must be around the audio in circuit. I
haven't checked it, but one thing is for sure - the digis work O.K.


Now, some disadvantages (or rather disappointing things):

- The most serious one is, the output analog signal amplifier stage has
strong DC distortion. The higher output level you set on the trimmer, the
stronger clipping distortion you get. Obviously, you hear the effect more
if the output level is higher, e.g. all channels are on, the volume is
set to $0f and you use (resonant) filtered bass. Once I asked Solder
about the reason and the solution, and he answered that it is due to the
needed high level on the Plus/4 analog input.

Unfortunately, there is just one way to step this problem over: connect
the SID card directly to your hi-fi equipment and turn the trimmer on the
card lower (middle position will do). You'll hear much less distortion
from the card, however, this is still not enough to get rid of the strange
effect completely. Even after turning the trimmer down, you'll still
experience fall-out and distorted waves if a strong sound comes in. I know
no correct solution for the problem, the card's audio amplifier part should
be modified but I didn't want to modify Solder's design.

- The card's filters sound a bit different than the original, even the
C64-II that BTW has the same SID. The reason: the SID is mostly an
analog design; at least its filters are. Because of the nature of these
circuits, even the slightest differences in the used parts can result in
different sound. The SID filters use two external capacitors, that mostly
determine their response. Now, the SID-card has exactly the same
capacitor value as the C64 SID has. ...But the manufacturing is
different: Solder used new small 'micro' ceramic capacitors, whereas
Commodore used 'standard', round-type capacitors. I replaced the
capacitors by two originals I picked out from an old C64 board and now it
sounds the same :-)

Another reason is: people used to play C64 tunes with simply redirecting
the original C64 tune to the new baseaddress (sometimes with a copying
loop that is even worse, but it's an other issue), without correcting
the SID frequency values to the 'slower' SID. This results in playing all
notes at about one note lower frequency than the original, but with the
same filter settings - the filter cutoff remains the same, since this
analog part is not affected by the oscillator frequency in any ways. This
can cause different sound - but not because of the filter in particular,
rather the 'wrong' oscillator settings.

IMO the sound caused by the different filter caps is not so much serious
that you should, like me, also replace them - the strange sound is rather
caused by the wrong (not corrected) original C64 music replay and the
card DC distortion together.

- After few minutes of operation, the SID on the card gets very hot. I
won't mention this one, since I know Commodore's chips and I know that a
lot of them get hot while in operation, but I certainly haven't
experienced this in the subject of the 8580 SID. Should this be because of
wrong analog interfacing or bad syncing, I don't know, but I hope it won't
kill the SID (haven't done that so far BTW).


SIDwinder for Plus/4
--------------------

Now a few words about the way SIDwinder operates on Plus/4.

First of all, there is no significant difference between the C64 and the
Plus/4 code. The editors are very same to each other, to the point of all
possibly equal code parts. Some constant values and some I/O register
references are replaced by their equivalents on the Plus/4 (color values,
TED registermap and so on).

The keys are mapped to their respective equivalents - as you'll see, I
decided to map the F-keys to the ones at the same _place, not name. Also,
the <- key was mapped to the ESC key (...but you can also use the left arrow
pressing Shift + '=' :-) ).

The editors include the very same music player routine, of course with the
above differences: the player in the editor assumes the SID at $fd40, and
includes a note-to-frequency-value-table generated for the nominal clock of
the Plus/4 SID card.

Well... that's all.

As speaking of the other utilities, the packer and the ASCII viewer, they
needed even less efforts to behave the same on both machines.


When you finished composing a song...
-------------------------------------

Well, you should decide what you want to do with the song.

- If you want the song to be included to your product as native SID-card
music, in the packer select $fd40 as SID-baseaddress and Plus/4 frequency
table.

- If you rather want it to be like a native C64 music, pack the song like
the above but select $d400 as SID base-address and C64 frequency table.

You should also decide with this latter option if you want your song to be
distributed in a collection together with native C64 musics (the HVSID
collection is a good example). But at this point, I'd suggest to read the
appropriate section later in this document before submitting the entry ;-).

Important note for the packing process. The default zeropage word assigned
to the SIDwinder player is $fb-$fc. On the Plus/4, $fb stores the actual
ROM configuration. If your product has to co-operate with the Kernal ROM and
the Kernal IRQ, you should rather select for example, $fc in the packing
process, to avoid unexpected crashes (it also made me spend a few hours in
hunting for bugs, when the Plus/4 version of the packer hanged with no
understandable reason :-\ ).


BTW, I'm sure, a lot of Plus/4 coders want their product to be
'configurable' in the subject of the sounds. This is a clever thought, since
even if the SID card was spread quite 'widely' and can still be ordered from
Solder, the majority of Plus/4 people doesn't have this pretty sound device
- some even never heard of it :-(. So, no doubt - if it's possible, your
program should also play music and/or sound fx through the TED sound output.

The theory is quite simple: there is the packed SID music linked into your
program (at this point, this is no matter if it was composed in SIDwinder or
not). Somehow, either by auto detecting the SID card or asking the user, you
should determine the used sound output (TED or SID card). And when it's
done, something has to be done in order to redirect the music to one or
another sound source.

This 'something' could be the following

- By default, you generate the packed music file with the above mentioned
parameters (base=$fd40 and Plus/4 frq table) and link this file into your
program. If the determined playing is 'SID card', you don't touch
anything in your programs init, you simply call the player each frame and
it plays as it's expected.
If the user selected 'TED', or your auto-detect routine detected no SID
cards, the player must be redirected to a 'phantom' SID address and you
also have to use a music converter routine (using the same 'phantom' SID
base address) to make the music play. The phantom SID address used to be
$d400 by default (since all C64 musics write to this address, and most
music converter routines read SID data from this address).

You can also do the opposite (have a music with $d400 SID base address,
don't touch it if the TED was selected, and redirect it to $fd40 if SID was
requested).


Some short notes
----------------

- If you play a music through the SID card, you're strongly suggested to
use a native 885Khz based frequency table (that one note difference seem
to cause the music to sound _awful, especially if filters were used). The
frq table type is not serious in the subject of the music converter
routines - they tend to f*** up the exact frq values anyway, and also
don't provide SID filter emulation. So you can also play the native
Plus/4 frq table music through a music converter routine with no
problems.

If you use a music _not created in SIDwinder, but also want to correct
its note frequency values, you'll most probably find a similar frq table
in the original C64 player as you can find in the SIDwinder player from
$1040 to $10ff. So, it should be easy to replace the original frq value
tables by one you simply picked out from a SIDwinder player that was
generated with the Plus/4 frq table ;-).

- If, and _only if TED was assumed, you must also call the music converter
routine.

- NEVER NEVER NEVER NEVER do such lame work I've seen in many early
SID-card 'compatible' demos and games: the original C64 music player is
called, then the resulting values are simply copied to $fd40 with a loop.
This causes all bad things to happen together - since the original music
player can write - and you can be sure, does write! - the SID registers
more than once in a run, the copying loop, and finally the SID will miss
all except the very last register changes. If you did such try, and you
heard the music to sound suspicious (missing notes, chaotic ADSR of the
sounds and such things), you found the answer here, right now :-).

Not to mention that this is the _only correct solution, redirecting the
player runs also much faster than running a copying loop each frame, after
each call of the player...

- You could ask, and you should be right - if this is true, then _all music
converter routines should suffer from the same problem. This is true. I
used to step over this problem with a little modification in the player.
But this needs the presence of one of _my music converter routines.
Mostly, the ADSR - and especially, the KEY bit of the SID control
register(s) in particular - causes problems. So, I used to replace _every
$d404 reference in the player by a call to a short routine:

sta $d404,x ;store the value, as expected
and #$01
bne end
sta $0204,x ;Internal variable of my music converter
end rts

(One thing to note: most players address the SID registers with indexed
addressing mode, either x or y is used (in SIDwinder, it is x).

- As speaking of the phantom SID base address, it doesn't have to be $d400,
it may certainly be anything you want - just make sure, the music and the
music converter routine assumes the same base address. Sometimes, using
$d400 is inappropriate - it is well in the anyway useable memory area,
well inside everything. I've seen in many converted games that $0400,
$ff40 and similar addresses were used (so does my Leonardo game ;-) ).
You can anyway use my SID base relocator routine to also redirect your
favourite music converter routine to a new base address, instead of
going through the code in monitor and replace every occurences by hand.


And finally: how to redirect a player to a new base address?
------------------------------------------------------------

This is simpler than you'd expect. I've written a small routine back in
1992 to do the task. I revised the code a bit, to make it simpler. You find
it in the distribution in ASCII source format, and you should also find a
compiled version. You can fiddle with both, I hope the routine is obvious.
You can relocate the routine to anywhere in the memory (since it consists of
no absolute jumps and references), just set the appropriate constants and
call it if it is neccessary.

(In short: you must set the start and end addresses of the code to be
redirected, ie. the start and end address of the player code. You must also
set the old (present) SID base address and the new base address. The code
goes through the whole code, and whenever it finds an absolute, or indexed
absolute reference to the old SID address area, it replaces the address by
the appropriate equivalent in the new area.)


When moving a C64 tune to Plus/4...
-----------------------------------

If you have a tune composed in the C64 version of the editor, and you want
it to be used in a Plus/4 program (with SID card), you should do a few final
steps before assuming everything to be O.K.

(Regardless to say, this final precaution is not caused by the programs, but
rather the little-bit-incompatible SID card hardware).

There are two points your tunes can go mad when playing on a Plus/4, and
both come from the different SID clock.

- Since the SID is slower, one needs higher values to achieve the same
output frequency (~ the same note). This is not a problem - the frq
table is the right one to address this one. But there is still a problem.
The SIDwinder player uses absolute frequency values for the glide/slide
instructions. If your tune uses glide/slide, the speeds can be slow
occassionally. (Theoretically, you can fix the problem if you multiple
all glide speeds in the glide table by 10/9).

The difference can also cause problems in the slide/vibrato table. The
solution is the same: if you experience problems, just multiple all
absolute values by 10/9.

- Since the SID is slower, also all ADSR speeds are slower. This causes
further problems in your instruments. Unfortunately, you have almost no
chance to make everything sound perfect, because of the raw resolution
of the SID ADR time settings (Sustain is not involved, of course). Just
check the instruments by ear; if you notice that something is wrong, go
and correct the appropriate ADSR value in the sound editor.


When moving a tune created on Plus/4 to C64 platform...
-------------------------------------------------------

You should do simply the opposite of the previous section. You can simply
assume that all speeds are faster by a factor of 10/9 and modify your song
- however nothing makes it sure that everything will sound correct, so it's
best to take the C64 editor and make the needed corrections if any (or
listen to the tune in a PC SID emulator, after you packed it - all in all,
check your tune before releasing it, to avoid surprises).

Copyright © Plus/4 World Team, 2001-2017