Cleaning the examples' Makefiles and octaves scripts.
[Faustine.git] / interpretor / 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 *)