interpreter/lib/src/libsndfile-1.0.25/doc/new_file_type.HOWTO

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