1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 /* ==================================================================== 3 * Copyright (c) 1999-2004 Carnegie Mellon University. All rights 4 * reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 13 * 2. Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * 18 * This work was supported in part by funding from the Defense Advanced 19 * Research Projects Agency and the National Science Foundation of the 20 * United States of America, and the CMU Sphinx Speech Consortium. 21 * 22 * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND 23 * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 24 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 25 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY 26 * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 28 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 30 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 32 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33 * 34 * ==================================================================== 35 * 36 */ 37 /* 38 * bio.h -- Sphinx-3 binary file I/O functions. 39 * 40 * ********************************************** 41 * CMU ARPA Speech Project 42 * 43 * Copyright (c) 1996 Carnegie Mellon University. 44 * ALL RIGHTS RESERVED. 45 * ********************************************** 46 * 47 * HISTORY 48 * $Log: bio.h,v $ 49 * Revision 1.8 2005/06/21 20:40:46 arthchan2003 50 * 1, Fixed doxygen documentation, 2, Add the $ keyword. 51 * 52 * Revision 1.5 2005/06/13 04:02:57 archan 53 * Fixed most doxygen-style documentation under libs3decoder. 54 * 55 * Revision 1.4 2005/05/10 21:21:52 archan 56 * Three functionalities added but not tested. Code on 1) addition/deletion of LM in mode 4. 2) reading text-based LM 3) Converting txt-based LM to dmp-based LM. 57 * 58 * Revision 1.3 2005/03/30 01:22:46 archan 59 * Fixed mistakes in last updates. Add 60 * 61 * 62 * 28-Apr-1999 M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University 63 * Created. 64 */ 65 66 67 #ifndef _S3_BIO_H_ 68 #define _S3_BIO_H_ 69 70 #include <stdio.h> 71 #include <stdarg.h> 72 73 /* Win32/WinCE DLL gunk */ 74 #include <sphinxbase/sphinxbase_export.h> 75 #include <sphinxbase/prim_type.h> 76 #include <sphinxbase/byteorder.h> 77 78 /** \file bio.h 79 * \brief Cross platform binary IO to process files in sphinx3 format. 80 * 81 * 82 */ 83 84 #ifdef __cplusplus 85 extern "C" { 86 #endif 87 #if 0 88 /* Fool Emacs. */ 89 } 90 #endif 91 92 #define BYTE_ORDER_MAGIC (0x11223344) 93 94 /** "reversed senses" SWAP, ARCHAN: This is still incorporated in 95 Sphinx 3 because lm3g2dmp used it. Don't think that I am very 96 happy with it. */ 97 98 #if (__BIG_ENDIAN__) 99 #define REVERSE_SENSE_SWAP_INT16(x) x = ( (((x)<<8)&0x0000ff00) | (((x)>>8)&0x00ff) ) 100 #define REVERSE_SENSE_SWAP_INT32(x) x = ( (((x)<<24)&0xff000000) | (((x)<<8)&0x00ff0000) | \ 101 (((x)>>8)&0x0000ff00) | (((x)>>24)&0x000000ff) ) 102 #else 103 #define REVERSE_SENSE_SWAP_INT16(x) 104 #define REVERSE_SENSE_SWAP_INT32(x) 105 106 #endif 107 108 109 110 /** 111 * Read binary file format header: has the following format 112 * <pre> 113 * s3 114 * <argument-name> <argument-value> 115 * <argument-name> <argument-value> 116 * ... 117 * endhdr 118 * 4-byte byte-order word used to find file byte ordering relative to host machine. 119 * </pre> 120 * Lines beginning with # are ignored. 121 * Memory for name and val allocated by this function; use bio_hdrarg_free to free them. 122 * @return 0 if successful, -1 otherwise. 123 */ 124 SPHINXBASE_EXPORT 125 int32 bio_readhdr (FILE *fp, /**< In: File to read */ 126 char ***name, /**< Out: array of argument name strings read */ 127 char ***val, /**< Out: corresponding value strings read */ 128 int32 *swap /**< Out: file needs byteswapping iff (*swap) */ 129 ); 130 /** 131 * Write a simple binary file header, containing only the version string. Also write 132 * the byte order magic word. 133 * @return 0 if successful, -1 otherwise. 134 */ 135 SPHINXBASE_EXPORT 136 int32 bio_writehdr_version (FILE *fp, /**< Output: File to write */ 137 char *version /**< Input: A string of version */ 138 ); 139 140 141 /** 142 * Write a simple binary file header with only byte order magic word. 143 * @return 0 if successful, -1 otherwise. 144 */ 145 SPHINXBASE_EXPORT 146 int32 bio_writehdr(FILE *fp, ...); 147 148 /** 149 * Free name and value strings previously allocated and returned by bio_readhdr. 150 */ 151 SPHINXBASE_EXPORT 152 void bio_hdrarg_free (char **name, /**< In: Array previously returned by bio_readhdr */ 153 char **val /**< In: Array previously returned by bio_readhdr */ 154 ); 155 156 /** 157 * Like fread but perform byteswapping and accumulate checksum (the 2 extra arguments). 158 * 159 * @return unlike fread, returns -1 if required number of elements (n_el) not read; also, 160 * no byteswapping or checksum accumulation is performed in that case. 161 */ 162 SPHINXBASE_EXPORT 163 int32 bio_fread (void *buf, /**< In: buffer to write */ 164 int32 el_sz, /**< In: element size */ 165 int32 n_el, /**< In: number of elements */ 166 FILE *fp, /**< In: An input file pointer */ 167 int32 swap, /**< In: Byteswap iff (swap != 0) */ 168 uint32 *chksum /**< In/Out: Accumulated checksum */ 169 ); 170 171 /** 172 * Like fwrite but perform byteswapping and accumulate checksum (the 2 extra arguments). 173 * 174 * @return the number of elemens written (like fwrite). 175 */ 176 SPHINXBASE_EXPORT 177 int32 bio_fwrite(const void *buf, /**< In: buffer to write */ 178 int32 el_sz, /**< In: element size */ 179 int32 n_el, /**< In: number of elements */ 180 FILE *fp, /**< In: An input file pointer */ 181 int32 swap, /**< In: Byteswap iff (swap != 0) */ 182 uint32 *chksum /**< In/Out: Accumulated checksum */ 183 ); 184 185 /** 186 * Read a 1-d array (fashioned after fread): 187 * 188 * - 4-byte array size (returned in n_el) 189 * - memory allocated for the array and read (returned in buf) 190 * 191 * Byteswapping and checksum accumulation performed as necessary. 192 * Fails fatally if expected data not read. 193 * @return number of array elements allocated and read; -1 if error. 194 */ 195 SPHINXBASE_EXPORT 196 int32 bio_fread_1d (void **buf, /**< Out: contains array data; allocated by this 197 function; can be freed using ckd_free */ 198 size_t el_sz, /**< In: Array element size */ 199 uint32 *n_el, /**< Out: Number of array elements allocated/read */ 200 FILE *fp, /**< In: File to read */ 201 int32 sw, /**< In: Byteswap iff (swap != 0) */ 202 uint32 *ck /**< In/Out: Accumulated checksum */ 203 ); 204 205 /** 206 * Read a 2-d matrix: 207 * 208 * - 4-byte # rows, # columns (returned in d1, d2, d3) 209 * - memory allocated for the array and read (returned in buf) 210 * 211 * Byteswapping and checksum accumulation performed as necessary. 212 * Fails fatally if expected data not read. 213 * @return number of array elements allocated and read; -1 if error. 214 */ 215 SPHINXBASE_EXPORT 216 int32 bio_fread_2d(void ***arr, 217 size_t e_sz, 218 uint32 *d1, 219 uint32 *d2, 220 FILE *fp, 221 uint32 swap, 222 uint32 *chksum); 223 224 /** 225 * Read a 3-d array (set of matrices) 226 * 227 * - 4-byte # matrices, # rows, # columns (returned in d1, d2, d3) 228 * - memory allocated for the array and read (returned in buf) 229 * 230 * Byteswapping and checksum accumulation performed as necessary. 231 * Fails fatally if expected data not read. 232 * @return number of array elements allocated and read; -1 if error. 233 */ 234 SPHINXBASE_EXPORT 235 int32 bio_fread_3d(void ****arr, 236 size_t e_sz, 237 uint32 *d1, 238 uint32 *d2, 239 uint32 *d3, 240 FILE *fp, 241 uint32 swap, 242 uint32 *chksum); 243 244 /** 245 * Read and verify checksum at the end of binary file. Fails fatally if there is 246 * a mismatch. 247 */ 248 SPHINXBASE_EXPORT 249 void bio_verify_chksum (FILE *fp, /**< In: File to read */ 250 int32 byteswap, /**< In: Byteswap iff (swap != 0) */ 251 uint32 chksum /**< In: Value to compare with checksum in file */ 252 ); 253 254 255 256 /** 257 * Write a 1-d array. 258 * Checksum accumulation performed as necessary. 259 * 260 * @return number of array elements successfully written or -1 if error. 261 */ 262 SPHINXBASE_EXPORT 263 int bio_fwrite_1d(void *arr, /**< In: Data to write */ 264 size_t e_sz, /**< In: Size of the elements in bytes */ 265 uint32 d1, /**< In: First dimension */ 266 FILE *fp, /**< In: File to write to */ 267 uint32 *chksum /**< In/Out: Checksum accumulator */ 268 ); 269 270 /** 271 * Write a 3-d array (set of matrices). 272 * Checksum accumulation performed as necessary. 273 * 274 * @return number of array elements successfully written or -1 if error. 275 */ 276 SPHINXBASE_EXPORT 277 int bio_fwrite_3d(void ***arr, /**< In: Data to write */ 278 size_t e_sz, /**< In: Size of the elements in bytes */ 279 uint32 d1, /**< In: First dimension */ 280 uint32 d2, /**< In: Second dimension */ 281 uint32 d3, /**< In: Third dimension */ 282 FILE *fp, /**< In: File to write to */ 283 uint32 *chksum /**< In/Out: Checksum accumulator */ 284 ); 285 286 /** 287 * Read raw data from the wav file. 288 * 289 * @return pointer to the data. 290 */ 291 SPHINXBASE_EXPORT 292 int16* bio_read_wavfile(char const *directory, /**< In: the folder where the file is located */ 293 char const *filename, /**< In: the name of the file */ 294 char const *extension, /**< In: file extension */ 295 int32 header, /**< In: the size of the header to skip usually 44 bytes */ 296 int32 endian, /**< In: endian of the data */ 297 size_t *nsamps /**< Out: number of samples read */ 298 ); 299 300 #ifdef __cplusplus 301 } 302 #endif 303 304 #endif 305