Used file formats

Before we'll continue with writing scripts, please let me tell you some words about the file formats the CapiSuite core uses.

CapiSuite always reads and saves files in the native format as they are be expected and given by the CAPI ISDN drivers. This preserves it from having to convert everything from and to other formats thus reducing unnecessary overhead.

As these formats aren't that well-known and you will need special tools to convert or view/play them, I'll give you a short overview of how you can do this.

Most likely, your scripts will convert the special ISDN file formats to well-known ones for sending them to you via e-mail for example. Nevertheless, I'd advice you to store the received and sent files in the native CapiSuite formats somewhere. This will protect you from losing data in the case the conversion fails and will help you in debugging problems which may arise with your scripts.

All tools which I refer to here are described in the section called “Software”. See there for informations how to get them.

Format of voice files (inversed A-Law, 8kHz, mono)

ISDN transmits voice data as waves with a sample-rate of 8kHz in mono. To save bandwith, a compression called A-Law is used (at least in Europe, other countries like the USA use u-Law which is quite similar to A-Law). For any reason beyond my understanding, they use a bit-reversed form of A-Law called "inversed A-Law".

Creating A-Law files

There are two possible ways to create A-Law files.

The first one is to call your computer with your phone (either use the default answering machine script and configure it as described in answering_machine.conf(5) or write a simple script yourself). Now, record whatever you want and take the created output file (when you use the default scripts please take the file from the user_dir, not the attachment of the mail as this is already converted) and use it.

You eventually want to trim the recorded file and remove unwanted noise and silence at the beginning and the end. This can easily be done by sox and play (both come together with the sox package).

sox is used to convert a file while play is used to just play it. Both support the same effects including the trim option. Both also detect what type of file you are using by looking at the suffix of your file name. So all your inversed A-Law files should be named like something.la (.la is the inversed form of .al which stands for A-Law).

So let's first try to find the optimal values for the trim effect by calling play:

play myfile.la trim <start-offset> <duration>

Now play around with start-offset and duration (both given in seconds) until you know the right values. If you found them, you can use sox to actually produce the needed file:

sox myfile.la outfile.la trim <start-offset> <duration>

You'll now get a file named outfile.la which should contain what you want.

The second way to create an inversed A-Law file is to record a normal WAV-file with your favourite sound-tools and convert it to the destination format using sox. You'll get the best results when your WAV file already is in 8kHz, mono, 8 bit format. sox is able to convert other waves if necessary but this usually will result in worse quality. You should also normalize your sound file to about 50% of the maximum amplitude.

You can convert WAV to inversed A-Law by calling (thx to Carsten Heesch for the tip):

sox myfile.wav -r 8000 -c 1 -b outfile.la resample -ql

Playing A-Law files

Again, there are two possibilities. The play command of sox is able to just play the inversed A-Law format without any conversion. Just call play with the filename as parameter:

play myfile.la

But you can also use sox to convert the A-Law files to the more common WAV format by just invoking:

sox myfile.la outfile.wav

The created outfile.wav can be played by nearly any audio player without problems.

Format of fax files (Structured Fax Files)

CAPI-compliant drivers will expect and provide fax files in a so called Structured Fax File (SFF). As this seems to be a CAPI-specific format, there are not much tools out there for GNU/Linux which are capable of handling it. Finally I found some small tools written by Peter Schäfer, which we can use here.

CapiSuite is also able to receive color fax files which will be stored in a special file format I called CFF.

Creating a SFF

In current Ghostscript releases, a patch from Peter has been included to produce SF files. To see if your Ghostscript already supports it, enter gs --help and look for the so-called cfax-device in the long device list presented to you. If it's not listed, you have to take a newer Ghostscript or recompile it, sorry. I don't know any other way to produce SFF currently.

You need a PostScript file (as produced by nearly every Linux program when you choose "print to file") first. Now you can call GhostScript to convert it to a SFF:

gs -dNOPAUSE -dBATCH -sDEVICE=cfax -sOutputFile=outfile.sff file.ps

If you're not sure if it worked you can use sffview as described below.

Viewing / converting from SFF

To simply view a received SFF, you can use the sffview program. It's a simple but useful tool for viewing SF files without the need to convert them. Just start it and you will get a GUI where you can open the desired file.

If you want to convert a fax file to a more common format, I recommend using sfftobmp. It supports quite some output formats like JPEG, TIFF, PBM or BMP. I prefer multipage TIFF files as this is the only format being able to store several pages in one file. To convert SFF to multipage TIFF, call:

sfftobmp -tif myfile.sff outfile.tiff

This will give you a TIFF file which you can convert now to nearly any other useful format with the TIFF tools, for example tiff2ps.

Color faxes - the CFF format

There exists an enhancement to the fax standard which allows to transfer documents in color. It's not very widely used, but as some people wanted it for CapiSuite, I added support for receiving this faxes with CapiSuite.

The CFF format (I don't know if this is an official name for the format) seems to be some sort of JPEG file with a special encoding. Most programs who can handle JPEG files should be able to open it. Perhaps you must rename it from .cff to .jpg first, before it will be recognized.

Currently, I don't know a nice way to create this format manually. Therefore, CapiSuite currently only supports the reception of these files. If someone knows more about it or knows the JPEG standards well, please contace me!