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