| 1 |
--- |
| 2 |
layout: page |
| 3 |
--- |
| 4 |
|
| 5 |
# How to add new file format |
| 6 |
|
| 7 |
Original : Wed May 23 19:05:07 EST 2001 |
| 8 |
Update 1 : Fri Jul 11 22:12:38 EST 2003 |
| 9 |
|
| 10 |
This document will attempt to explain as fully as possible how to add code to |
| 11 |
libsndfile to allow the reading and writing of new file types. By new file |
| 12 |
type I particularly mean a new header type rather than a new encoding method |
| 13 |
for an existing file type. |
| 14 |
|
| 15 |
This HOWTO will take the form of a step by step guide. It will assume that you |
| 16 |
have all required tools including : |
| 17 |
|
| 18 |
- gcc |
| 19 |
- make (should really be the GNU version) |
| 20 |
- autoconf |
| 21 |
- automake |
| 22 |
- libtool |
| 23 |
|
| 24 |
These should all be available on the GNU ftp site: <ftp://ftp.gnu.org/pub/gnu/>. |
| 25 |
|
| 26 |
To help make these steps clearer let's suppose we are adding support for the |
| 27 |
Whacky file format whose files contain 'W','A','C' and 'K' as the first four |
| 28 |
bytes of the file format. Lets also assume that Whacky files contain PCM encoded |
| 29 |
data. |
| 30 |
|
| 31 |
## Step 1 |
| 32 |
|
| 33 |
Create a new .c file in the src/ directory of the libsndfile source tree. The |
| 34 |
file name should be reasonable descriptive so that is is obvious that files of |
| 35 |
the new type are handled by this file. In this particular case the file might |
| 36 |
be named 'whacky.c'. |
| 37 |
|
| 38 |
## Step 2 |
| 39 |
|
| 40 |
Add your new source code file to the build process. |
| 41 |
|
| 42 |
Edit the file src/Makefile.am and add the name of your file handler to the |
| 43 |
FILESPECIFIC list of handlers. This list looks something like this: |
| 44 |
|
| 45 |
FILESPECIFIC = aiff.c au.c au_g72x.c nist.c paf.c raw.c samplitude.c \ |
| 46 |
svx.c wav.c wav_float.c wav_gsm610.c wav_ima_adpcm.c \ |
| 47 |
wav_ms_adpcm.c |
| 48 |
|
| 49 |
Then, run the script named 'reconf' in the libsndfile top level directory, |
| 50 |
which will run autoconf and other associated tools. Finally run "./configure" |
| 51 |
in the top level directory. You may want to use the "--disable-gcc-opt" option |
| 52 |
to disable gcc optimisations and make debugging with gdb/ddd easier. |
| 53 |
|
| 54 |
## Step 3 |
| 55 |
|
| 56 |
Add a unique identifier for the new file type. |
| 57 |
|
| 58 |
Edit src/sndfile.h and find the enum containing the SF_FORMAT_XXX identifiers. |
| 59 |
Since you will be adding a major file type you should add your identifier to the |
| 60 |
top part of the list where the values are above 0x10000 in value. The easiest |
| 61 |
way to do this is to find the largest value in the list, add 0x10000 to it and |
| 62 |
make that your new identifier value. The identifier should be something like |
| 63 |
SF_FORMAT_WACK. |
| 64 |
|
| 65 |
## Step 4 |
| 66 |
|
| 67 |
Add code to the file type recogniser function. |
| 68 |
|
| 69 |
Edit src/sndfile.c and find the function guess_file_type (). This function |
| 70 |
reads the first 3 ints of the file and from that makes a guess at the file |
| 71 |
type. In our case we would add: |
| 72 |
|
| 73 |
if (buffer [0] == MAKE_MARKER ('W','A','C','K')) |
| 74 |
return SF_FORMAT_WACK ; |
| 75 |
|
| 76 |
The use of the MAKE_MARKER macro should be pretty obvious and it is defined at |
| 77 |
the top of file should you need to have a look at it. |
| 78 |
|
| 79 |
## Step 5 |
| 80 |
|
| 81 |
Add a call to your open function from psf_open_file (). |
| 82 |
|
| 83 |
Edit src/sndfile.c and find the switch statement in psf_open_file (). It starts |
| 84 |
like this: |
| 85 |
|
| 86 |
switch (filetype) |
| 87 |
{ case SF_FORMAT_WAV : |
| 88 |
error = wav_open (psf) ; |
| 89 |
break ; |
| 90 |
|
| 91 |
case SF_FORMAT_AIFF : |
| 92 |
error = aiff_open (psf) ; |
| 93 |
break ; |
| 94 |
|
| 95 |
Towards the bottom of this switch statement your should add one for the new file |
| 96 |
type. Something like: |
| 97 |
|
| 98 |
case SF_FORMAT_WACK : |
| 99 |
sf_errno = whacky_open (psf) ; |
| 100 |
break ; |
| 101 |
|
| 102 |
## Step 6 |
| 103 |
|
| 104 |
Add prototypes for new open read and open write functions. |
| 105 |
|
| 106 |
Edit src/common.h, go to the bottom of the file and add something like |
| 107 |
|
| 108 |
int whacky_open (SF_PRIVATE *psf) ; |
| 109 |
|
| 110 |
## Step 7 |
| 111 |
|
| 112 |
Implement your open read function. The best way to do this is by coding |
| 113 |
something much like one of the other file formats. The file src/au.c might be a |
| 114 |
good place to start. |
| 115 |
|
| 116 |
In src/whacky.c you should now implement the function whacky_open() which |
| 117 |
was prototyped in src/common.h. This function should return 0 on success and |
| 118 |
a non-zero number on error. |
| 119 |
|
| 120 |
Error values are defined in src/common.h in a enum which starts at SFE_NO_ERROR. |
| 121 |
When adding a new error value, you also need to add an error string to the |
| 122 |
SndfileErrors array in src/sndfile.c. |
| 123 |
|
| 124 |
To parse the header of your new file type you should avoid using standard read/ |
| 125 |
write/seek functions (and the fread/fwrite/fseek etc) and instead use |
| 126 |
psf_binheader_readf () which is implemented and documented in src/common.h. |
| 127 |
|
| 128 |
During the parsing process, you should also print logging information to |
| 129 |
libsndfile's internal log buffer using the psf_log_printf() function. |
| 130 |
|
| 131 |
At the end of the open read process, you should have set a number of fields in |
| 132 |
the SF_PRIVATE structure pointed to by psf. |
| 133 |
|
| 134 |
**THIS FILE IS INCOMPLETE** |