SIDedit - A Perl/Tk GUI based application to read and edit binary SID files.
This Perl/Tk GUI application allows the user to read, write and edit binary SID files, which are music player and data routines converted from the Commodore-64 computer with an additional informational header prepended. SIDedit has become a useful tool for people ripping SID tunes out of Commodore-64 executables.
Most of the application's common functions should be obvious, and for some of the less obvious ones tooltips provide additional hints.
This tool is intended for programmers, SID rippers, or other people with reasonable background. It is not suitable for newbies who have never before used hexadecimal numbers, who are not familiar with the Commodore-64 computer's internals or with the SID file format (click Help - SID file format> on the menu for the format specification).
Let's say you just ripped a SID tune and it's sitting on your hard drive as a Commodore-64 executable and you want to turn it into a standard SID file so it can be incorporated into the High Voltage SID Collection.
Let's assume that your freshly ripped tune is in a file called Ripped.prg. (SIDedit recognizes a file as a C64 data file only if its extension is one of .prg, .p00, .c64 or .dat.) Start up SIDedit, check the List C64 data files checkbox and navigate to the directory where this file can be found. Click on the file. SIDedit will ask you whether you want to load it as SID data. Answer yes. SIDedit also asks you whether you want to reset the SID header data to the defaults. For now answer yes to this question, too. The binary data from Ripped.prg gets loaded into SIDedit.
Now all you have to do is edit the SID header and save the resulting file. Remember that when you change any field in the SID header in SIDedit, you are editing an in-memory copy of the SID file, not the SID file itself! Once you are done with your changes, you'll have to save them to a file to make the changes permanent.
First, decide whether your rip is PlaySID compatible or requires a real C64 environment to play properly. See the next section below for a detailed discussion about this. When you decided, set the Environment field to your choice.
Then, make sure that the Load range displayed in SIDedit is the same as the one you used when you saved the file. If it isn't, enter the load address in the loadAddress field and make sure the Always save as PSID v2NG/RSID option is checked in the Configure settings window under the File navigator tab, otherwise leave the loadAddress field at 0. (NOTE: if you selected Real C64 as the rip's environment, you can't edit the loadAddress field!)
Then, at a minimum, you should edit the initAddress and playAddress hexadecimal fields (leave playAddress as 0 only if the initialization routine of the ripped tune installs an interrupt player itself - this will always be set to 0 for Real C64 rips and you won't be able to change it), the songs and startSong decimal fields (both should be at least 1), and, of course, the textual name, author and released fields that should conform to HVSC standards (read the HVSC FAQ for details on that or hover with the mouse over those fields to see their tooltips for examples).
If certain (or all) subsongs of your rip use different timers, you might also want to edit the speed field. (NOTE: You can't do this if your rip is a Real C64 rip.) The easiest way to do this is to click on the Edit speed bits button, where you can set the speed of the individual subsongs. Due to the SID file format's limitation, subsongs #32 and higher are all represented by 1 bit only, so they'll all have the same speed. This is rarely a problem, though.
Next you should edit the flags field. Again, instead of typing in the actual hexadecimal value for this field it's easier if you simply click on the Edit the flags button. Here you can specify whether your rip uses a built- in player or not (it most likely does), and whether it's fully C64 compatible or it's PlaySID specific (note: this latter setting is not an available choice for Real C64 rips). For example, if your rip plays digi samples and you didn't alter the original player routine, it's definitely a fully C64 compatible rip. If you modified the player routine so that it plays the digi samples via the extended PlaySID registers (not recommended), then you should definitely check the PlaySID specific checkbutton. For Real C64 rips check the C64 BASIC executable checkbox if the ripped tunes uses BASIC instructions.
You should also specify here whether the tune you ripped was intended for PAL or NTSC machines (or maybe it works on both), and also whether it was intended by its author to be played on a 6581 or 8580 chip (or maybe both). Then press Done, and the flags field will be automatically updated for you.
To help SID emulators determine where they should install their interrupt routines, you may want to specify the area of memory that is definitely not used by your ripped tune. Usually this is a problem only when the initialization or player routine reads or writes to memory that is outside the Load range. If this is the case, you should specify the address of the first free 256 byte large memory page in startPage and the number of free pages following that in pageLength. For example, startPage = $30 and pageLength = $10 indicates that the memory area between $3000 and $3FFF is never touched by your ripped tune.
A common example for how to fill out the different SID fields is below:
Now click on the Create HVSC compliant filename button. This will - surprisingly - create an HVSC compliant filename out of the SID's name, in this case it'll create the filename My_Love_is_Infinite.sid. Then make sure the Always save as PSID v2NG/RSID option is checked in the Configure settings window and save the file by clicking on the Save file button on the toolbar. That's it! (You can also save the SID file to a different directory by choosing File - Save as...> from the menu.)
If you ripped more than one tune from the same author, you might want to do the following to save you from typing in his name for every rip: after doing the above procedure, make sure the little checkbuttons by the author and released fields are checked and all the other ones are not. Make sure the Edit - Copy format -> Selected fields only> menu option is also checked, then select Edit - Copy> from the menu or press CTRL-C. This will copy the above two SID fields as text to the clipboard. Now you can go on and add a SID header to your next rip as outlined above, but instead of typing in the author and release info, simply select Edit - Paste> from the menu or press CTRL-V.
You'll notice there is a setting labeled Environment that can be set either to PlaySID or to Real C64. When it is set to PlaySID, SIDedit will save the SID to a valid PSID v1 or v2/v2NG file depending on the other settings. When it is set to Real C64, the data will always be saved to an RSID (RealSID) file, which is basically a PSID v2NG file with its magic ID set to 'RSID' instead of 'PSID'.
The main difference between the two settings is that Real C64 indicates that the rip requires a true Commodore-64 environment to operate properly and won't even play in (or might even crash!) older libsidplay1 and PlaySID compatible SID emulators. The advantage of RSID files is that they can be run on a real C64 unmodified. For this reasons it is highly recommended to save every SID file as an RSID (Real C64 file). See the SID_file_format.txt file included with SIDedit for further details (it is discussed under the 'magicID' field).
Setting the environment to Real C64 also enforces additional restrictions on top of PSID v2NG: it automatically sets the loadAddress, playAddress and speed fields to 0 and modifying these fields is no longer possible, plus changing the bit in the flags field to make the file PlaySID specific will be no longer possible, either. Also, the initAddress and the relocation range indicated by startPage and pageLength cannot be inside or overlap the ROM/IO ($A000-$BFFF and $D000-$FFFF) areas, initAddress cannot be lower than $07E8 and the relocation range cannot overlap the reserved memory area ($0000-$03FF).
When you press the Display SID data button, a new window pops up. Here you can select whether you want to display the data portion of a SID file as a Hex dump, or as disassembled machine code (Assembly checkbutton), or as disassembled machine code showing the illegal instructions, too. Note that when you display the data as Hex dump, for your convenience C64 ASCII characters (both uppercase and lowercase) will be shown as standard ASCII characters on the screen. Also note that when the data is shown as assembly code, you can click on certain jump and branch addresses to jump to that address directly without scrolling to it. Also, when you switch from assembly to hex dump mode or vice versa, the topmost line of the display will be at approximately the same address where it was in the previous display mode.
You can specify the first memory address from which the data will be shown by choosing either the Load address, the initAddress, the playAddress, or an arbitrary memory address (Other) as the starting point for the display.
You can also save the C64 data portion of a SID to a file by clicking the Save data to file button. Choosing the as binary option will save it to a standard C64 binary file with a .prg extension, while choosing the as displayed option will save the actual content of the data display into a plain text file. Choosing the as 64 KB memory image option will create a binary file with an .img extension that is exactly 65536 bytes large and is basically a snapshot of the C64's 64 KB memory with the data portion of the SID file at the appropriate memory address location. Therefore, if you hex edit the resulting .img file, the offsets in your hex editor will match that of the actual offsets when the data is loaded into the C64's memory.
The window also gives you an opportunity to change the size of the C64 data. You can enter a new load range for the data in the Trim/pad data section. If the new range you specify is greater than the current load range at either end, the C64 data gets filled with zeros accordingly. If the new range you specify is smaller than the current load range at either end, the C64 data portion gets trimmed (chopped) as specified. Pressing the Trim/pad data button carries out the change and it also updates the appropriate SID header data. WARNING: if you reduce the data portion there's no other way of getting back the cut data other than reloading the file! Be careful with this button!
Finally, you can also modify a contiguous string of bytes in the data portion by clicking on Modify bytes. This is very useful if you want to add, say, a short sequence of assembly instructions to the SID data.
First specify the C64 address from which you want to modify bytes, then specify the bytes that you want to change it to in the format of ``xx xx xx ...'' where 'xx' are hexadecimal bytes. For example, setting At address to $1000 and the change bytes to to ``AB BA'' will change the C64 data portion at $1000 to hex $AB and at $1001 to hex $BA. Needless to say, don't do byte modifications unless you are absolutely sure about what you are doing as you can really mess up the SID file with incorrect byte modifications here.
The left-hand side of the main SIDedit window is dedicated to the file navigator. You can use the file navigator to browse directories, load SID files into SIDedit, play SID files by double-clicking on them, etc. If the directory listing is long, you can also type the first few letters of the file or directory you'd like to jump to after making the given listbox active by rolling your mouse pointer over it.
The file navigator also has its own toolbar. Besides the usual buttons, like Go to parent directory, Create new directory and Delete selected directory there are also a few so-called directory shortcut buttons. You can use these to jump directly to certain frequently used directories, like to the directory where you usually save your SID files to, or to go to your HVSC directory. You configure where these shortcuts point to on the Configure settings window under the File navigator tab.
SIDedit is also capable of loading SID header data from so-called INFO files which usually have a .sid file extension. These files were part of a now obsolete two-file SID file format.
Check the List INFO files checkbox at the top of the file navigator in SIDedit to see a list of such files in the file navigator. Once you click on an INFO file, SIDedit will ask you whether you want to overload the current SID header data in the memory with the one contained in the INFO file. Answer yes to carry out this operation.
After saving a SID file you probably want to make sure it plays correctly in your favorite SID emulator. SIDedit can launch your favorite SID player with a selected file as outlined below.
First, select the Tools tab in the Configure settings window to tell SIDedit which SID player you would like to use for this feature.
Then you can launch your SID player either by clicking on the Play SID file button on the toolbar, or by double-clicking on the file. If you didn't configure a SID player, yet, SIDedit will automatically pop up the Configure settings window to prompt you for the location of the SID emulator you want to use to play the file.
You might also want to edit the data portion of the SID file after you saved the file. You can do this with your favorite hex editor from within SIDedit by clicking the Edit file with hex editor button on the toolbar.
First, select the Tools tab in the Configure settings window to tell SIDedit which hex editor you would like to use for this feature.
Then you can start your hex editor by clicking on the Edit file with hex editor button.
If you didn't configure a hex editor, yet, SIDedit will automatically pop up the Configure settings window to prompt you for the location of the hex editor you want to use for this purpose.
After saving a SID file you might want to run an external tool like SID2CRC to make sure that your rip is a pristine SID tune. Select the SID file in the file navigator then click the Run command line tool button on the toolbar. Here you can enter a command line that will execute your tool in a shell or choose from a list of previously executed tools (the list remembers the last 10 commands you ran and this list is also saved with other settings to SIDedit.INI).
For example, assuming that sid2crc is in your path, enter sid2crc -v -t80000 -m %f at the command line entry. %f will be replaced with the full pathname of the file you selected in the file navigator. You can also use %d to substitute the full pathname of the current directory shown in the file navigator of SIDedit, or %x to subsitute the full pathname of the selected file without its extension. Now click the Run command line tool button and the command line you entered will be executed.
The output of the command will appear in a new pop-up window. (If you see nothing here, the command you entered most likely failed.) There are two additional buttons on this window that also allow you to save the command's output to a file and to copy the contents of the output to the clipboard. You can also pop up this window any time by clicking the Run tool button in the main SIDedit window and then clicking Show last output or by choosing File - Show last output of tool...> from the menu - as its name suggests it will always show you the output of the most recent command you executed.
When you quit SIDedit, it automatically saves your settings to a SIDedit.INI file that will be located in the same directory from where you started SIDedit itself. If you want to disable this feature, uncheck the Always save settings on exit option on the General tab in the Configure settings window and click Save settings now - from now on, SIDedit will read the settings from the SIDedit.INI file, but it won't save your changes to it when you quit the program. You can also force SIDedit to save the current settings to the SIDedit.INI file any time by clicking on the <Save settings now> in the same window.
Note that besides all the settings available on the Configure settings menu, SIDedit also saves the settings of all the options available via the Edit menu, the list of the last 10 commands that were executed with the Run command line tool feature, plus the last size and position of the main SIDedit window and some other windows.
This script requires the following modules: Audio::SID Cwd File::Basename File::Copy Tk Tk::Balloon Tk::Checkbutton Tk::Dialog Tk::DialogBox Tk::Optionmenu Tk::Radiobutton Tk::ROText Tk::BrowseEntry Tk::LabFrame Tk::Scrollbar Tk::Button Tk::Entry Tk::Photo Tk::ToolBar Tk::NoteBook Tk::WaitBox Tk::DirTree
On Win32 machines it also uses these modules: Win32 Win32::API Win32::Process Win32::Clipboard Win32API::File
If you find any other bugs in this module, please, report them to the author (see COPYRIGHT below).
clipboardPaste() doesn't work,
neither does $window->insert - great...)
Add a button called ``Batch processing''. In there one option would be to
generate a text output of checked fields recursively in current dir, another
option would be to change the checked fields in all files recursively to what
is in current file.
Simon: I still wish something could be done about it like say combining load
address and range (make load address always reflect the range start address).
Then by changing load address you'll see the range change. Also might be nice
if you then click display data the new load address is used... You could even
combine load address and range into a single line.
Keep the ShowSIDData and ShowTextOutput windows on screen, don't grab, so they
can be displayed side-by-side.
Add Dag's code to fill out startPage and pageLength automatically.
Add ability to recurse dirs and autoconvert SID files as per specified
options.
Load MD5s from expanded Songlengths DB to find SIDs already in HVSC.
Allow siddiag duplicate match against HVSC. Or in general incorporate a
duplicate finder?
Add ability to search every field of every SID found in HVSC and/or other
specified directories. Sort of like SidBace. Build a text DB for this. Add
search capability for Songlength DB, STIL, etc.
SIDedit Copyright (C) 1999, 2004 by LaLa <LaLa@C64.org>
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SIDedit v4.01
http://www.geocities.com/SiliconValley/Lakes/5147/
The SIDPLAY2 homepage for documents about the PSID v2NG extensions:http://sidplay2.sourceforge.net
The SID Rippers' Guide: The High Voltage SID Collection, the most comprehensive archive of SID tunes: the Audio::SID manpage
You'll notice that the user interface of SIDedit has undergone some significant upgrades which will hopefully make it easier to use. The basic functionality of SIDedit hasn't changed much, though.
IMPORTANT: If you're installing this version of SIDedit over the old one, I strongly advise you to -DELETE- your existing SIDedit.ini file to remove the chance of some weird bug happening. Upon first starting SIDedit v4.00, select ``Tools'' -> ``Configure settings'', then click ``Save settings now'' to re-create the SIDedit.ini file.
If you are using the UNIX/Perl version (i.e the SIDedit.pl file from the tarball) you'll notice that you'll have to install a few new Perl/Tk modules to get SIDedit running. It's inconvenient, I know, but it was the only way I could add some cool new widgets to the tool.
(added)
SIDedit now uses menus and toolbars for easy access
to most functions.
(added)
Help screens use external files.
(added)
File -> New to reset SID data to defaults.
(added)
File -> Save as... to save file to arbitrary location.
(added)
The main window and the data display make use of colors.
(added)
In the data display window it is now possible to click
on the jump/branch addresses to jump to that location
directly (if that location can be displayed in the window).
(added)
In the data display window switching between hex dump
and assembly listings retains the currently displayed
address range in the window.
(added)
All the settings are now configurable via a separate
"Configure settings" popup window.
(added)
Experimental mousewheel support. (NOTE: on some systems
if you press down on the mousewheel button and move down,
the window contents scroll up, and moving up scrolls them
down instead of the other way around. This seems to be a
bug in Perl/Tk itself.)
(added)
The file navigator window pane also got its own toolbar
with 3 directory "shortcuts" (default dir, default save
dir, HVSC dir) which are configurable via the "Configure
settings" popup window. You can use these shortcuts to
jump to those dirs without navigating to them.
(added)
Toolbar icons that are lifted from Tk::Toolbar -> tkIcons.
(added)
Errors that would be displayed on the command line are now
displayed in an error message box.
(added)
Window positions are retained and also saved to
configuration file.
(added)
"Please wait" popup window when SID data display rendering
takes a long time.
(added)
Jumping between hex and assembly display in the SID data
display retains location from the previous display mode.
(added)
The POD is now in its separate .pod file.
(added)
Added ``%x'' command line substitution pattern to the ``Run Tool'' feature to
allow full pathname without file extension.
(fixed)
Additional verification of playAddress and initAddress fields.
(fixed)
Pressing delete and backspace in the SID fields will also flag the in-memory
file as modified.
(fixed)
Sub-windows now properly take and release focus.
(fixed)
InitAddress and playAddress are grayed out in the SID data display if they
are zero.
(fixed)
Saving a file with the same name but different case now saves the file with
the new cases.
(fixed)
If ``List INFO files'' is checked, loading of data files is no longer messed
up.
(fixed)
Lots and lots of small bugfixes. Hopefully, I managed to fix all the bugs
that were reported since the previous version was released. :)
Some of you might notice that in the Windows version of SIDedit there is no ``Browse'' button next to the directory shortcut entries in the ``Configure settings'' window. Unfortunately, this is due to a shortcoming of the Perl/Tk interface and hopefully it'll be fixed when Tk-804 is released.
First public release. Lots of changes and additions.
First release.