KeenWave
| Initial Developer | Levellord |
|---|---|
| Developer(s) | Levellass |
| Initial release | 2010-07-31 |
| Latest update | 2011-03-25 |
| Development status | Finished |
| Programming language | FreeBasic |
| Platform | DOS, (DPMI), Windows XP, 7-10, Linux |
| Tool Type | Sound Editor |
| Engine(s) | Keen:Vorticons, Keen:Galaxy, Keen:Dreams, Bio Menace, Catacomb 3D, Wolfenstein 3D |
| Discussion(s) | K:M Discussion Thread |
| Download | KeenWave v.1.1 newest KeenWave v.0.6 KeenWave v.0.5 |
KeenWave is a utility written by Levellass to export and import sounds from several id/Apogee games, especially Commander Keen. It is written using FreeBasic and is thus primarily a Windows-based utility. The official releases are written for Windows with a Linux version also available.
It is based on, and an attempt to improve on KeenFX by Commander Spleen. Though currently a beta, it has the ability to export sounds from the Keen Vorticons and Keen Galaxy series as well as several other games that use the same sound format. It can also be used for basic IMF and sound editing. This page details how to use the program, doubling as online help.
Running KeenWave
There are three basic ways of using KeenWave, that is, telling KeenWave what you want to do. They are:
- Drag-and-drop: This works for individual files, especially exported sound/music files or Keen 1–3 sound archives. Simply drag the file onto the executable.
- Command line: Type in the Commands you want in the command line.
- Text file: This is the easiest option when modding games. The file KEENWAVE.TXT will be read and may contain the same Commands as you would place on the command line. Just run KeenWave and it will automatically read the file. This saves having to retype everything every time you want to do something.
A comprehensive list of commands is included with Keenwave in the file README.TXT They differ depending on what screen of Keenwave you are on. It is reccommended this document be consulted first.
Features
- Extract sounds from games as raw data, bitmaps or playable wave files
- Create and import your own sounds and music
- Alter the number of sounds and songs you can play and use (with limits!)
- Comes with AdLib sound player
Tutorials
These are step-by-step instructions on how do do various things with KeenWave. Before any of these can be done, you must first copy two files to your project directory, KEENWAVE.EXE and, if you want to play sounds, KEENWAVE.DAT. Picture 1 shows a clean Keen 4 directory with the needed files.
Changing sound properties
The example here is for Keen 4, but it is nearly identical for all Keen episodes. The first thing that must be done is to select the sound file to work with. This tutorial uses the drag-and-drop method; AUDIO.CK4 is selected, dragged and dropped onto KeenWave's executable. There is a brief pause while the file is analyzed and then KeenWave opens a window as seen in picture 2.
The window has several sections of interest. Firstly is the sound list, which lists the number, patch number and names of all sounds in the audio file. You start at sound 0, as indicated by the small green dot. Navigation is done with the arrow keys, moving up\down or left and right. At the top of the screen is some basic data about the audio file we're working with, such as file name and number of various sounds.
The first sounds are PC sounds, the same as in Keen Vorticons. By default Keen 4's sounds have no names, which can make them hard to tell apart. It is possible to name a sound by moving right to its name section and entering a name. This can be seen in picture 3, where several of the sounds have been named and a new name is being entered. Other options can be altered in a similar manner, such as the sound's priority.
It is possible to listen to the sound at any time by pressing space. This lets you listen to any changes you make.
Changing a sound
Changing a sound can be done in two ways, the first is to import data from an external file, this is covered in the readme file and involves pressing 'i' for import, typing the file's name and then moving to the sound you want to change, moving to its number (Not priority, name or whatever!) and pressing 'v' to paste the data. This is good for copying sounds.
The second method is to edit the sound data manually, done by pressing enter when the sound's number is selected. (Pressing enter in the second screen of this tutorial would lead to this.) This brings up the sound editing screen. Instructions for what keys can be pressed in this screen are also available in the readme file.
The sound screen shows a plot of the sound pitch over time, a drawing of the soundwave as it were. The light mark indicates where in the sound you are editing, the red and blue marks indicate the start\end of the sound data. Navigation again is with the arrows, up and down (And pgup\pgdn) changing the sound pitch, while left and right move you along the sound. With this screen it is possible to make a sound as long or short as you want and to alter a great deal about how it sounds.
A sound is only saved when you press enter, submitting the data. Pressing Esc will abort any changes. Not that when sound data is 'saved' the sound file has NOT, to save your changes permanently you will need to save the sound files (See below.)
Changing music
In Keen Galaxy it is possible to both add new music and change old music files. In our Keen 4 example this is done by importing data from and IMF file. This is the same as changing a sound via copy\paste above, we press 'i', and type the IMF name. To change an old song we go to the music entries, at the end of the sound list. We can use the arrows, but the 'end' key takes us there quickly. All music entries are marked as such and we can see the difference between sound number and patch number in picture 5.
What happens next depends on what we want to do. If we press 'v' while on a song entry, we'll replace an old song with our new one. If we're on an <empty> entry then we'll add a new song. You will be asked if you want to add a new song, since it changes all the song numbers of old songs.
It is also possible to edit IMF data more directly, by selecting the entry by pressing enter. (Or drag-and-dropping an IMF file on KeenWave.) This will take you to the IMF screen which allows you to do basic things like add song tags, cut bits out of the song and change song speed. This can be useful when tweaking songs.
IMF Types
There are two types of IMF file, type 0 and type 1. KeenWave allows you to switch between types since some games use one and some the other. Extracted IMFs can be in either format. IMFCreator files are always type 1. Keen games also always use type 1 files. If your music causes crashes, the type may be the reason. All Keen games use type 1.
Saving changes
Before any of this can be seen in-game the sound file must be saved. Pressing 's' will ask you for a name, while pressing 'q' quicksaves to the same file you were working with. What happens next depends on what episode of Keen you are working with. In Keen 1, no changes will be apparent, but the sound file may have changed in size. Other Keens will have produced a patch file, since the data will need to be patched. In Keen Galaxy an AUDIOHED and AUDIODCT file will have been produced as well. Patches are in PATCH.TXT, ready for adding to your own patch file. (This may or may not need to be done depending on whether youve done something big, like add a new IMF song.) Picture 7 shows the Keen 4 folder with the data saved. To run the changed sounds, CKPatch will be needed.
Exporting\Importing
This is another method of altering sounds, more akin to Keengraph or ModKeen in methodology. In this case all the sounds are exported as data files or imported to an audio file. This can be easier to do, but it is harder to tell the results of tinkering. Since this is a whole different methodology it is given its own section below.
Exporting\Importing
As noted just above, this is an alternate way of altering sounds, where a sound file is created from exported data files each time, much like how graphics are imported with Keengraph. Following is a tutorial similar to the above using the export\import method.
New music in Keen 4
It is assumed the folder is set up like in the above example, a clean Keen 4 folder with Keenwave as shown in picture 1. To extract the sounds, KeenWave is run with the following switches:
KeenWave.exe -episode=4 -export=raw -snddir="out"
If you check the commands section, you will see this tells KeenWave to look for and export Keen 4 sounds as raw sound data to the subdirectory "out". KeenWave should then run for a few seconds, saying it is "Created directory OUT... Exporting 161 sounds from AUDIO.CK4...".
When it is done and closes, the directory "out" will look like the picture at the top of this page. There will be a text document called LIST.TXT, a number of .CK4 files and six .IMF files. These last two are our sounds and music. The first IMF file, SND1-156.IMF is the map music, as can be seen by playing it in Winamp using Adplug. The third music file, SND1-158.IMF is "Too Hot". We are going to add a copy of Too Hot to the audio file, giving us one 'extra' music file.
In LIST.TXT it is noticeable that there is a "gap" between the last AdLib sound (entry 103) and the first IMF song (entry 156). This is because part of the audio file is full of blank chunks, which we can use for extra songs, even enough for one per level if we want!
The first thing to do is to add a new song entry. Songs must be entered before the other IMF songs, since there is only a limited amount of entries available. This means that adding a new song will "move" all the other songs "up a space" as far as the game is concerned, messing up the music for all levels. Thus, when putting new music in, it is wise to decide beforehand how many songs you want then fill them in with "placeholder" songs until you have the music sorted. In this example, we are going to use the map song as a placeholder for any new song we might want to put in.
We add the following entry below the line mentioning "IMF music:", but above all the other IMF entries:
155: SND1-158.IMF
Notice that here, we are using an existing extracted song as our "new" song. This new entry means that an unused "blank" chunk will now be a new song, giving us 7 songs (entries 155–162). We now import the sounds again by running KeenWave with these commands:
KeenWave.exe -episode=4 -import -snddir="out"
Once the sounds are imported the folder looks a lot like in picture 7, though with the 'out' folder. We'll need to add CKPatch before we can use our new music. In PATCH.TXT we can find the following patches, patching not just the new sounds, but expanding the music as well:
#Keenwave patch file; Patch sounds: %patchfile $20DF0 AUDIOHED.CK4 #Audio header %patchfile $354F6 AUDIODCT.CK4 #Audio dictionary #Change number of songs: %patch $8CEF $9B $00 %patch $8C75 $C893W %patch $8C83 $C893W %patch $8D83 $C893W
When we run the game now, we will find that the map uses our "new" song, since it is the only level that uses "song 1". We will also notice that the songs playing in all the other levels are mixed up. This is because when we added the new song, "song 1" became "song 2" and "song 2" "song 3" and so on. This means each level is now playing a song 1 "less" than it was before.
To change this, simply go here for song list patches and increase each level's value by one. Notice that this tutorial is only useful for Keen 4–6, other games are not yet supported (such as Biomenace).
Commands
Also known as switches, these tell KeenWave what to do. They are used exclusively when extracting or importing sounds to/from games, due to the complexity involved in doing this. As mentioned above, these cane be given via the command line or by writing them in KeenWave's configuration text file. It does not matter how many commands are entered, in what case, in what order or in how many lines. In this regard, it is very similar to ModKeen.
KeenWave will look for commands from the command line first. If it finds none, it will then look in its config file. If this cannot be found, it will create one and inform you that you need to tell it what to do. An example config file is included with the download at the bottom of this page. The following are valid commands:
-export=???. This tells Keenwave you want to export sounds and also what format you want them in. By default, KeenWave will export sounds as raw data. The three options are-export=raw,-export=bmpand-export=wav. If no type is given, sounds will be exported as raw data.-import. This tells KeenWave to import sounds. The format does not matter, KeenWave can import multiple filetypes. Be aware though that at present, some imports are buggy, especially wave import. Whether KeenWave imports or exports depends on what command it encounters last. If neither is given, KeenWave will export by default.-episode=N. This tells KeenWave what "episode" to work with. Episodes 1–3 are Keen Vorticons, 4–6 is Galaxy and 7 for Dreams. Other values are used for different games. If no episode is specified, KeenWave will search the files directory for the first game executable it can find to determine the episode.-filedir="DIR". This is the directory that the game files are located/created in. If the full path is not specified, KeenWave will look for a subdirectory in its current directory. If no directory is specified, it will use its current directory. If the directory is not found, it will be created if KeenWave is exporting. (Creating an empty directory does not let you get sounds from it.)-snddir="DIR". This is the directory extracted (sound) files are located/created in. The same rules apply as with the filedir. Notice both commands are separate, so it is possible to read game files off a USB and write them to a hard drive. To avoid clutter, it is recommended that the sounds directory be a subdirectory of the mod directory.-list. When importing raw data for Keen 4–6 type games, this command tells KeenWave to rely on its LIST.TXT file for sound parameters instead of the files themselves. This lets a modder quickly tweak the AdLib parameters/priority of various sounds to experiment. On the downside, a sound copied from another game will sound warped, since its own, optimized AdLib/priority data will be overwritten.-patch="FILE". The name of the patch file to work with. If this is used, KeenWave will create a patchfile with the required patches to patch modified sounds. If this is not used, or no patches are needed, the patch file will not be created.-backup. Backs up files when importing. Currently not implemented.-mod. This will write changed sounds directly to the game executable, meaning no patching is required. It is technically illegal modification and is currently not implemented.
LIST.TXT
LIST.TXT, and others like it, is the list file produced when sounds are exported. It contains information about the sound archive exported and all the sounds/music in it. This is used by KeenWave when importing sounds to correctly find and arrange all the sound data.
If there is more than one sound archive for a game (e.g. Cosmo's Cosmic Adventure, which has two), several LIST files will be produced, one for each archive. LIST files need to "work" in Windows Notepad, that is, they need carriage returns AND line feeds to end each line. Other limits include the fact that file names cannot be longer than 13 characters, including extension, and that sound names cannot be longer than 15 characters and are enclosed in ' marks. Furthermore, you cannot use parentheses or square brackets for either.
The start of the file has some basic information that limits you when importing. This is because games themselves often have limits as to what you can do and how you can do it. The main limits you may encounter are:
- Size of sound file: For internally stored files, this is how much space you have to work with. Deleting this line or ignoring it means you may make a file too large, and overwrite other, vital, game data. Keen 1–3 type files have a maximum size of 64Kb, even if not stored in an executable.
- Number of sounds: Many games limit how many sounds you can have. For Keen 1–3 type games, this is usually 64 sounds, though you can push yourself up to 255 in some cases. More sounds take up more space, even if they are small, the sound header data takes up room. You cannot change the number of sounds at all in Keen 4–6 type games, though you can add more songs (see tutorial below).
- Extracted from...: This is used when patching executables, that is, reinserting extracted sound data from them or writing patch files. It has no effect on the sounds themselves.
The rest of the LIST file consists of several sections of data. For Keen 1–3 type LISTs, there is only one section, PC Speaker sounds. Keen 4–6 type LISTs will have two other sections, AdLib sounds and IMF music. These will be labeled as such, and it is unwise to put a PC entry under the AdLib section or somesuch.
Each section will have a number of entries, each a single line. Each line begins with the sound number it is for, followed by a colon. It is best practice to keep these entries in order (0, 1, 2, 3, 4..) since some sound files do not like having them out of order. Notice that the first sound is sound 0, not sound 1. There are several types of entry:
PC Speaker entries
9: SND1-009.CK2 'Wheeee!' [ 85]
These entries are for PC Speaker sounds and are found in all LIST files, appearing first, just after the header. They have four "fields", the sound number, the name of the file to use for sound data, the sound's name, and its priority. In the above entry, sound 9 is stored in the file SND1-009.CK2 and is called "Wheeee!". While sounds can be named, names are not needed and are there only to help the modder.
Priority, the last entry, in square brackets, is a measure of how "important" a sound is. When two sounds try to play at the same time (or one interrupts another), the sound that is more or equally important will play over the less important one. This is why things like the extra life bonus sound are not interrupted by dull things like Keen walking. It is suggested that modders adopt a "scale" of importance, such as low–med–hi or 1–10 to organize their sounds.
AdLib entries
63: SND1-063.CK4 'Blink' [ 50] ( 6, 196, 0, 0, 255, 248, 240, 181, 0, 0, 15, 0, 0, 0, 0, 0, 4)
These appear much more complex, and they are. They consist of five fields instead of four, the first four being identical to their PC Speaker counterparts, number, filename, name and priority. The last field, enclosed in parentheses, consists of seventeen numbers separated by commas.
These numbers are AdLib parameters. Basically, each AdLib sound is a single IMF instrument which needs to be defined. There are eight sets of two numbers and a seventeenth giving the octave to play the sound in. (Sort of like the pitch.) Unless you know about the AdLib sound format and OPLH registers, these are going to look like gibberish and can be treated as such. It is often interesting to randomly tweak the parameters to see how the sound changes. (More information can be found here.) Otherwise these values can be left alone.
IMF entries
157: SND1-157.IMF
These are refreshingly simple; they consist of only two fields, sound number and filename. All other data is usually stored in the IMF file. They need little explanation.
Blank entries
43: '__UnNamed__ ' [ 1]
Keen 1–3 type LISTs can have "blank" entries, or unused sounds. These are basically placeholders since many games had a predefined limit of 63 sounds which were gradually filled in. Sometimes, they can be deleted with no ill effect (Keen 1–3), at other times they are needed. You can see they have no file name specified, and that they have low priority and most games give them an "unamed" name. Note that if these entries are included, they will be compiled as "sounds" of a sort and the game will be able to use them.
File formats
There are a number of file formats for both sounds and game files. Keeping tack of them can be important, it is not yet possible to mix and match all the various formats.
Game formats
These are the formats used by the games themselves, as well as the raw data exported by KeenWave. There are three broad categories, Keen Vorticons, Keen Galaxy and Crystal Caves.
- Keen Vorticons: This consists of a single sound file containing numerous sound chunks. They are basic PC Speaker sounds and there is no music. They are often stored in the executable or a group file. The earliest games will use this format. An example is Keen 1's SOUNDS.CK1.
- Crystal Caves: Based on Keen Vorticons, this is almost identical and only used by Crystal Caves. There is currently no support for it. Again, it is basic PC speaker sounds.
- AudioT: This is used by later games and can be told apart from Keen Vorticons by its use of an AUDIO or AUDIOT file. Sounds may or may not be compressed and may or may not need data from the executable. (See the linked page for details.) There are three types of sound chunk in this type of file:
- PC Speaker sound: Similar but even more simple than Keen Vorticons speaker sounds.
- Adlib sound: More complex and using the sound card, these are the hardest sounds to edit correctly.
- IMF music: Songs, playable with Winamp and Adplug. These also use the sound card. Games that do not use the AudioT format may also use IMF music (Cosmo's Cosmic Adventure) where these will be separate from the PC sounds.
KeenWave formats
These are files that KeenWave produces and uses when working with sounds.
- Raw data: This is just raw data copied from the game files. It will have the exact same format as the game sounds and can only really be edited using a hex editor. IMF music is always exported in this manner. The advantage of these is that they can be swapped around, so if you hear a sound you like in a game you can just copy it wholesale into yours.
- Bitmaps: These are monochrome bitmaps 256 pixels tall. This is a visual representation of the sound's pitch; that is, it is what the sound looks like. This allows a modder to easily make sounds they have in their head, a rising tone is a / a beep is a - and so on. This is rather intuitive to use since you can often see the whole sound and how its pitch changes. Notice that it is ONLY the pitch data, for AdLib sounds there is also instrument data which controls a lot of what the sound actually sounds like.
- The sound is represented by a thin black "line" showing the pitch. The higher the line goes, the higher the frequency of the sound. Quiet segments either have no line, or have a pitch of 0 (Bottom of the bitmap). This can easily be seen in exported sounds.
- KeenWave wave files: these are playable wave files that also contain the sound data. Imported sounds will sound exactly like the wave file does. These are created by KeenWave. They are very much simpler than normal wave files. These files cannot be edited without changing format and are included only so a modder has a format of sound data that can be played in many players and converted to many other formats.
- Other wave files: These are any other wave files. KeenWave will have to convert them, which is difficult and buggy, since so much information must be discarded. At present this is not supported at all.
Supported games
This is a list of the various "episode" values given to games KeenWave works with, as well as the current level of support for them. (X=full support, x=partial support, E=full export support only, otherwise not yet supported or tested.)
(X) 1 Commander Keen 1 ( ) 26 Rescue Rover (X) 2 Commander Keen 2 ( ) 27 Slordax (X) 3 Commander Keen 3 ( ) 28 Street Ball (X) 4 Commander Keen 4 ( ) 29 Paragon (X) 5 Commander Keen 5 ( ) 30 RESERVED (X) 6 Commander Keen 6 ( ) 31 RESERVED (X) 7 Commander Keen Dreams (E) 32 Catacomb 3D ( ) 8 Dave 1 ( ) 33 The Catacomb ( ) 9 Copyright Infringement (E) 34 Biomenace 1 ( ) 10 Dave 2 (E) 35 Biomenace 2 ( ) 11 Shadow Knights (E) 36 Biomenace 3 (X) 12 Cosmo 1 ( ) 37 Dangerous Dave 3 (X) 13 Cosmo 2 ( ) 38 Dangerous Dave 4 (X) 14 Cosmo 3 ( ) 39 The Catacomb Abyss 3D (Keen Dreams based) ( ) 15 Crystal Caves 1 ( ) 40 Major Stryker ( ) 16 Crystal Caves 2 (E) 41 Wolfenstein 3D ( ) 17 Crystal Caves 3 (E) 42 Wolfenstein 3D 2 ( ) 18 Duke Nukum 1.1 (E) 43 Wolfenstein 3D 3 ( ) 19 Duke Nukum 1.2 ( ) RESERVED ( ) 20 Duke Nukum 1.3 ( ) RESERVED ( ) 21 Duke Nukum 2 ( ) RESERVED ( ) 22 Word Rescue ( ) RESERVED ( ) 23 Math Rescue ( ) RESERVED ( ) 24 Hovertank 3D ( ) RESERVED ( ) 25 Pickle Wars ( ) RESERVED