interpreter/lib/src/libsndfile-ocaml/sndfile.mli

   1 (*
   2 ** File: sndfile.ml
   3 **
   4 **      Copyright (c) 2006, 2007 Erik de Castro Lopo <erikd at mega-nerd dot com>
   5 **      WWW: http://www.mega-nerd.com/libsndfile/Ocaml/
   6 **
   7 **      This library is free software; you can redistribute it and/or
   8 **      modify it under the terms of the GNU Lesser General Public
   9 **      License as published by the Free Software Foundation; either
  10 **      version 2 of the License, or (at your option) any later version.
  11 **
  12 **      This library is distributed in the hope that it will be useful,
  13 **      but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 **      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 **      Lesser General Public License for more details.
  16 **
  17 **      You should have received a copy of the GNU Lesser General Public
  18 **      License along with this library; if not, write to the Free Software
  19 **      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  20 *)
  21
  22 (** libsndfile interface for OCaml.
  23
  24         libsndfile (http://www.mega-nerd.com/libsndfile) is a library for reading
  25         and writing a huge number of different audio file formats.
  26
  27         Typical (simple) usage for small files:
  28
  29 {[
  30         let file = Sndfile.openfile filename in
  31         let frames = Int64.to_int (Sndfile.frames file) in
  32         let data = Array.create frames 0.0 in
  33         let readcount = Sndfile.read file data in
  34         .....
  35 ]}
  36
  37 *)
  38
  39 type open_mode_t =
  40         |       READ                    (** Open file for read. *)
  41         |       WRITE                   (** Open file for write. *)
  42         |       RDWR                    (** Open file for read/write. *)
  43
  44 type seek_mode_t =
  45         |       SEEK_SET                        (** Seek relative to start of file. *)
  46         |       SEEK_CUR                        (** Seek relative to current position. *)
  47         |       SEEL_END                        (** Seek relative to end of file. *)
  48
  49 type major_format_t =
  50         |       MAJOR_NONE
  51         |       MAJOR_WAV               (** Microsoft WAV format (little endian default). *)
  52         |       MAJOR_AIFF              (** Apple/SGI AIFF format (big endian). *)
  53         |       MAJOR_AU                        (** Sun/NeXT AU format (big endian). *)
  54         |       MAJOR_RAW               (** RAW PCM data. *)
  55         |       MAJOR_PAF               (** Ensoniq PARIS file format. *)
  56         |       MAJOR_SVX               (** Amiga IFF / SVX8 / SV16 format. *)
  57         |       MAJOR_NIST              (** Sphere NIST format. *)
  58         |       MAJOR_VOC               (** VOC files. *)
  59         |       MAJOR_IRCAM             (** Berkeley/IRCAM/CARL *)
  60         |       MAJOR_W64               (** Sonic Foundry's 64 bit RIFF/WAV *)
  61         |       MAJOR_MAT4              (** Matlab (tm) V4.2 / GNU Octave 2.0 *)
  62         |       MAJOR_MAT5              (** Matlab (tm) V5.0 / GNU Octave 2.1 *)
  63         |       MAJOR_PVF               (** Portable Voice Format *)
  64         |       MAJOR_XI                        (** Fasttracker 2 Extended Instrument *)
  65         |       MAJOR_HTK               (** HMM Tool Kit format *)
  66         |       MAJOR_SDS               (** Midi Sample Dump Standard *)
  67         |       MAJOR_AVR               (** Audio Visual Research *)
  68         |       MAJOR_WAVEX             (** MS WAVE with WAVEFORMATEX *)
  69         |       MAJOR_SD2               (** Sound Designer 2 *)
  70         |       MAJOR_FLAC              (** FLAC lossless file format *)
  71         |       MAJOR_CAF               (** Core Audio File format *)
  72
  73 type minor_format_t =
  74         |       MINOR_NONE
  75         |       MINOR_PCM_S8                    (** Signed 8 bit data *)
  76         |       MINOR_PCM_16                    (** Signed 16 bit data *)
  77         |       MINOR_PCM_24                    (** Signed 24 bit data *)
  78         |       MINOR_PCM_32                    (** Signed 32 bit data *)
  79         |       MINOR_PCM_U8                    (** Unsigned 8 bit data (WAV and RAW only) *)
  80         |       MINOR_FLOAT                     (** 32 bit float data *)
  81         |       MINOR_DOUBLE                    (** 64 bit float data *)
  82         |       MINOR_ULAW                      (** U-Law encoded. *)
  83         |       MINOR_ALAW                      (** A-Law encoded. *)
  84         |       MINOR_IMA_ADPCM         (** IMA ADPCM. *)
  85         |       MINOR_MS_ADPCM          (** Microsoft ADPCM. *)
  86         |       MINOR_GSM610                    (** GSM 6.10 encoding. *)
  87         |       MINOR_VOX_ADPCM         (** OKI / Dialogix ADPCM *)
  88         |       MINOR_G721_32           (** 32kbs G721 ADPCM encoding. *)
  89         |       MINOR_G723_24           (** 24kbs G723 ADPCM encoding. *)
  90         |       MINOR_G723_40           (** 40kbs G723 ADPCM encoding. *)
  91         |       MINOR_DWVW_12           (** 12 bit Delta Width Variable Word encoding. *)
  92         |       MINOR_DWVW_16           (** 16 bit Delta Width Variable Word encoding. *)
  93         |       MINOR_DWVW_24           (** 24 bit Delta Width Variable Word encoding. *)
  94         |       MINOR_DWVW_N                    (** N bit Delta Width Variable Word encoding. *)
  95         |       MINOR_DPCM_8                    (** 8 bit differential PCM (XI only) *)
  96         |       MINOR_DPCM_16           (** 16 bit differential PCM (XI only) *)
  97
  98
  99 type endianness_t =
 100         |       ENDIAN_FILE                     (** Default endianness for file format. *)
 101         |       ENDIAN_LITTLE           (** Force little endian format. *)
 102         |       ENDIAN_BIG                      (** Force Big endian format. *)
 103         |       ENDIAN_CPU                      (** Use same endianness as host CPU. *)
 104
 105
 106 type file_format_t
 107 (**
 108         An opaque type representing a sound file file format.
 109
 110         It is constructed using either format or format_e.
 111 *)
 112
 113 type error =
 114         |       No_error
 115         |       Unrecognised_format
 116         |       System
 117         |       Malformed_file
 118         |       Unsupported_encoding
 119         |       Internal
 120
 121 exception Error of (error * string)
 122
 123 type t
 124 (**
 125         [Sndfile.t] An opaque type representing a open sound file.
 126 *)
 127
 128 val format : major_format_t -> minor_format_t -> file_format_t
 129 (**
 130         [Sndfile.format ma mi] constructs a file_format_t for use with
 131         sf_open for the supplied major format [ma], minor format [mi].
 132 *)
 133
 134 val format_e : major_format_t -> minor_format_t -> endianness_t -> file_format_t
 135 (**
 136         [Sndfile.format ma mi] constructs a file_format_t for use with
 137         sf_open for the supplied major format [ma], minor format [mi] and
 138         endianness [e].
 139 *)
 140
 141 val openfile :
 142         ?info : (open_mode_t * file_format_t * int * int) ->
 143         string ->
 144         t
 145 (**
 146         [Sndfile.openfile fn] opens the file specified by the filename [fn] for
 147         read.
 148
 149         [Sndfile.openfile (SFM_WRITE, fmt, ch, sr) fn] opens the file specified
 150         by the filename [fn] for write with the specified file_format_t, channel
 151         count and samplerate.
 152
 153         [Sndfile.openfile (SFM_RDWR, fmt, ch, sr) fn] opens the file specified
 154         by the filename [fn] for read/write with the sepcified file_format_t,
 155         channel count and samplerate.
 156 *)
 157
 158 val close : t -> unit
 159 (**
 160         [Sndfile.close f] closes the file [f].
 161
 162         Attempting to read from or write to a file after it has been closed will
 163         fail.
 164 *)
 165
 166 val read : t -> float array -> int
 167 (**
 168         [Sndfile.read f a] read data from the file [f] into the supplied array
 169         [a] and return the number of float values read.
 170
 171         For multi-channel files, the array length must be an integer multiple of
 172         the number of channels.
 173 *)
 174
 175 val write : t -> float array -> int
 176 (**
 177         [Sndfile.write f a] write data from the supplied array [a] to the file
 178         [f] and return the number of float values written.
 179
 180         For multi-channel files, the array length must be an integer multiple of
 181         the number of channels.
 182 *)
 183
 184 val frames : t -> Int64.t
 185 (**
 186         [Sndfile.frames f] returns the number of frames in the file [f].
 187 *)
 188
 189 val samplerate : t -> int
 190 (**
 191         [Sndfile.samplerate f] returns the sample rate of the file [f].
 192 *)
 193
 194 val channels : t -> int
 195 (**
 196         [Sndfile.channels f] returns the channel count for the file [f].
 197 *)
 198
 199 val seek : t -> Int64.t -> seek_mode_t -> Int64.t
 200 (**
 201         [Sndfile.seek f pos m] seeks to posiont [pos] of file [f] using
 202         the specified seek mode [m]. Returns offset from start of file.
 203 *)
 204
 205 val compare : t -> t -> int
 206 (**
 207         The comparison function for Sndfile.t, with the same specification as
 208     [Pervasives.compare].
 209 *)