File encoder

The file encoder, which the Klipspringer hub uses for converting the audio format when downloading a file via the recordings source, can be run directly with the command klipcook1.

The klipcook command is installed as part of the full Klipspringer platform. Its primary purpose is to convert raw audio files, of the type created when recording with kliptune, into other formats, but it can be used for other conversions as well. The command takes two file name arguments, which can be preceded with some options (run klipcook -help to list available options). For example, the following might be a command to convert a recorded audio file to FLAC format: 

klipcook 'kliprec@20250220T151144.277 -r 44100 -b 24+8 -c 2 -e signed-integer -L.raw' 'my_recorded_audio.flac'

Available input formats, determined by file suffix, are:

  • .raw, with the data format encoded in the file name (see below),
  • .wav,
  • .aiff or .aif (handled by the Java sound system),
  • .flac, if Klipspringer was built with FLAC support,
  • .ogg, if Klipspringer was built with Vorbis support, and
  • .opus, if Klipspringer was built with Opus support.

Output formats, also determined by file suffix, are:

  • .raw, with the data format encoded in the file name (see below), which must match the sample frequency, bit depth, and number of channels of the input file,
  • .wav,
  • .flac, if Klipspringer was built with FLAC support,
  • .ogg, if Klipspringer was built with Ogg Vorbis support, and
  • .mp3 ,if Klipspringer was built with LAME support.

Raw input format options

Since raw PCM data doesn’t include any header specifying the format (sample frequency, bit depth, etc.), the format is instead included in the file name as format options of a kind used by of SoX commands, just before the .raw suffix. For instance, the file 

mymusic -r 44100 -b 24 -c 2 -e signed-integer -L.raw

is in 24-bit 44100 Hz stereo signed little-endian format. The default, if no format is specified, is 24-bit 44100 Hz stereo signed little-endian, so in this case, the file could have been called just mymusic -b 24.raw (but it’s nice to have the full format specified, e.g. to copy it to the command line if you want to process the file with sox).

The -b option extends the SoX format to allow specification of padding, by adding a plus sign and the number of padding bits to the bit depth. For instance, -b 24+8 means that each sample value is padded with 8 zero-bits up to 32 bits, with the actual data bits in the least significant positions. (SoX doesn’t support such padding, and has therefore no need for specifying it.)

Notes

  1. The command is a shell script that launches the Java class EncodeFile. Hence, Java needs to be installed, but Node.js doesn’t if klipcook is run as a standalone program.