Using cktool

The cktool utility is located in bin/macosx and bin/win

Its usage is:

Usage:

cktool buildbank [common_options] <infile> [<outfile>]
builds a bank file (.ckb) from an xml bank description file (.ckbx)

cktool buildbank [common_options] -single [sound_attributes] <infile> [<outfile>]
builds a bank file (.ckb) containing one sound

cktool buildstream [common_options] [sound_attributes] <infile> [<outfile>]
builds a stream file (.cks)

cktool info [common_options] <file>
prints info about a bank (.ckb) or stream (.cks) file


Available common options are:
-verbose

Available sound attribute options are:
-format <format>
-volume <volume>
-pan <pan>
-loopStart <frame>
-loopEnd <frame>
-loopCount <count>

Building bank files

Creating a bank file from a bank description file

To create a bank file, first create an XML bank description file.  A sample bank description file used by the hellocricket sample projects can be found at src/samples/hellocricket/common/hellocricket.ckbx:

<?xml version="1.0" encoding="utf-8" ?>
<bank name="test">
    <sound name="hello" source="hellocricket.wav" />
</bank>

The first line (which is optional) just indicates that this is an XML file.

The second line starts the "bank" block.  Each bank description file must contain one bank block.  Each bank should have a name, which should be 31 characters or less.

The third line is a "sound" block, which defines one sound.  There should be at least one sound in a bank, though typically there will be more.  Each sound has a name (which, like the bank name, should be 31 characters or less) and a source file (which must be a WAV or AIFF file).  The source file can be an absolute path (such as /Users/steve/sound.wav or C:/sounds/sound.wav) or a relative path (such as sounds/sound.wav).  If it's a relative path, it is assumed to be relative to the bank description file.

To create the binary bank file (.ckb) from this XML bank description file (.ckbx), run
cktool buildbank infile.ckbx outfile.ckb
where infile.ckbx is the input bank description file and outfile.ckb is the output binary bank file.  If the output file is omitted, the output will be written to a file with the same name as the input file but with the .ckb file extension, in the same directory as the input file.

Creating a bank file from a single audio file

If you are building a bank file containing only one sound, you can do so without creating an XML file; simply specify the -single option, and pass in the source audio file as the input file.  For example:
cktool buildbank -single explosion.wav explosion.ckb
will create a bank called explosion.ckb from the file explosion.wav.

Sound attributes

You can also specify some optional attributes for each sound:

attribute
description
default value
format
The format of the audio data; can be one of pcm8, pcm16, or adpcm.
pcm16
volume
Default volume of the sound, in the range from 0.0 to 1.0. 
1.0
pan
Default pan of the sound, in the range from -1.0 (pan left) to 1.0 (pan right).
0.0 (center)
loopStart
Default starting sample frame for looping, in the range from 0 (loop from the first sample) to one less than the number of sample frames in the sound.
0
loopEnd
Default ending sample frame for looping in the range from 1 to the number of sample frames in the sound, or -1 to indicate the end of the sound. (The sample frame specified here is the sample after the end of the loop.)
number of sample frames
loopCount
Number of times the sound loops.  0 means no looping; -1 means loop indefinitely; 1 means it will play twice, 2 means it will play three times, etc.
0 (no looping), or -1 (infinite looping) if either loopStart or loopEnd were set


If you are using a bank description file, those attributes are specified as XML attributes on the sound elements.  For example, here is a more complex bank description file:

<?xml version="1.0" encoding="utf-8" ?>
<bank name="sound effects">
    <sound name="explosion" source="explosion.wav"                  format="adpcm"  volume="0.72" />
    <sound name="hooray"    source="/Users/steve/sounds/hooray.aif" format="pcm8"   loopStart="1200" loopEnd="-1"/>
    <sound name="buzz"      source="moresounds/buzzsound.wav"       volume="0.3" pan="-1" />
</bank>

If you are building a single-sound bank using the -single option, the attributes are specified as command-line options.  For example, here is how you would create the "explosion" sound from the bank description file above:
cktool buildbank -format adpcm -volume 0.72 explosion.wav explosion.ckb

Building stream files

To create a .cks stream file, run
cktool buildstream infile.wav outfile.cks
where infile.wav is the input audio file, and outfile.cks is the output stream file.  If the output file is omitted, the output will be written to a file with the same name as the input file but with the .cks file extension, in the same directory as the input file.

When creating a stream, you can specify sound attributes on the command line:
cktool buildstream -format adpcm -pan -1 infile.wav outfile.cks