sphere.doc

来自「speech signal process tools」· DOC 代码 · 共 171 行

NAME
     sphere - NIST SPeech HEader REsources functions

SYNOPSIS
     #include <header.h>
     #include <sp.h>

     struct header_t *sp_create_header()
     struct header_t *sp_open_header(fp,parse_flag,error)
     FILE *fp;
     char **error;
     int parse_flag;

     int sp_close_header(h)
     struct header_t *h;

     int sp_clear_fields(h)
     struct header_t *h;

     int sp_get_nfields(h)
     struct header_t *h;

     int sp_get_field(h,name,type,size)
     struct header_t *h;
     char *name;
     int *type, *size;

     int sp_get_data(h,name,buf,len)
     struct header_t *h;
     char *name, *buf;
     int *len;

     int sp_add_field(h,name,type,p)
     struct header_t *h;
     int type;
     char *name, *p;

     int sp_delete_field(h,name)
     struct header_t *h;
     char *name;

     int sp_change_field(h,name,type,p)
     struct header_t *h;
     char *name, *p;
     int type;

     int sp_write_header(fp,h,hbytes,databytes)
     FILE *fp;
     struct header_t *h;
     long *hbytes, *databytes;

     int sp_format_lines(h,fp)
     struct header_t *h;
     FILE *fp;

     int sp_print_lines(h,fp)
     FILE *fp;
     struct header_t *h;

DESCRIPTION
     The SPHERE function library supports disk I/O and  in-memory
     creation and modification of NIST speech file headers.  This
     software has been developed at  The  National  Institute  of
     Standards  and  Technology  for  use within the DARPA speech
     research community.  Although care has been taken to  ensure
     that  all  software  is  complete  and  bug-free, it is made
     available to the speech research community without  endorse-
     ment or express or implied warranties.

     The abstract data type that programs use is a pointer  to  a
     header_t  structure.  This  pointer  is a handle used by the
     functions that operate on  the  header,  much  like  a  FILE
     pointer  is  used  as  a  handle by functions in the C stdio
     library that operate on files.   All  arguments  h  in  this
     document  refer  to a header structure that has been associ-
     ated with a header pointer.

     There are two ways to return a program may obtain  a  header
     pointer.  The first method is to call sp_create_header which
     returns a pointer to an empty header.  The other is to  call
     sp_open_header  which  reads  the fields from a NIST SPHERE-
     format speech file into a header data  structure.   Argument
     fp  must  be  a  file pointer associated with a NIST SPHERE-
     format speech file that has been  opened  for  reading.   On
     success,  the  file  pointer is positioned at the end of the
     header, which is  the  start  of  the  speech  samples.   On
     failure,  the argument error will point to a string describ-
     ing the cause of the failure.  If the parse_flag argument is
     non-zero,  the header is parsed and all fields in the header
     file are associated with the header structure. If the  argu-
     ment  is  zero,  the  header is not parsed and no fields are
     associated with the structure.

     The memory for header structures is obtained dynamically via
     malloc(3).   Therefore,  the function sp_close_header should
     be used to deallocate the memory header structure associated
     with a header pointer. This function uses free(3) to deallo-
     cate all memory associated with the  fields  in  the  header
     structure, then the space for the header structure itself.
     The function sp_get_nfields returns  the  number  of  fields
     stored  in  the  header  structure  associated with a header
     pointer.  The function sp_clear_fields  deletes  all  fields
     from the header structure associated with a header pointer.
     Programs may determine the type  and  size  in  bytes  of  a
     header  field  via  sp_get_field. Valid types are T_INTEGER,
     T_REAL, and T_STRING, which are defined  in  header.h.   The
     sizes  of  integer  and  double  fields are sizeof(long) and
     sizeof(double), respectively.  The sizes of strings vary and
     do  not include null-terminator bytes, since all byte values
     including zero are allowed in a string by  the  NIST  header
     grammar.   The  function sp_get_data copies the value of the
     field specified by name into buffer buf.  No more  than  len
     bytes are copied; len must be positive.

     A  field  name  may  be  added  to  a  header   by   calling
     sp_add_field  with a type field of either T_INTEGER, T_REAL,
     or T_STRING.  Argument p should be a pointer to a long, dou-
     ble,  or character, respectively, and cast, if necessary, to
     a character pointer.  The specified field must  not  already
     exist  in  the  header.   A field name may be deleted from a
     header via  sp_delete_field.   The  function  fails  if  the
     specified  field  does not exist in the header.  An existing
     field's  type  and/or   value   may   changed   by   calling
     sp_change_field   with   arguments   type   and   p   as  in
     sp_add_field.

     A header structure can be written to  disk  in  NIST  SPHERE
     format  via  sp_write_header.   Argument  fp  must be a file
     pointer associated with a file  that  has  been  opened  for
     writing.  The format is:

          fieldname -typespec fieldvalue

     where typespec is  i,  r,  or  sstringlength.   On  success,
     hbytes and databytes contain the total number of bytes writ-
     ten to disk including padding  and  not  including  padding,
     respectively.  On failure, the variables are undefined.  The
     function sp_format_lines writes  the  fields  to  stream  fp
     one-per-line.  The function sp_print_lines writes a header h
     to stream fp in a more-readable format:

          fieldnumber: fieldtype fieldname "fieldvalue"

     where fieldtype is either  s,  i,  or  r.   Field  numbering
     begins at zero.

RETURN VALUES
     All functions in the library  that  return  pointers  return
     NULL  pointers  on  failure/error.   All  numeric  functions
     return negative values on failure/error.

FILES
     libsp.a             Sphere library
     header.h            basic type definitions and constants
     sp.h                Sphere function type definitions

NOTES
     Comments in speech headers are ignored when  encountered  on
     input.  No  mechanism is supported for writing comments into
     headers.

BUGS
     Please report any bugs to John Garofolo by sending email  to
     [e-mail].
     Please include a description  of  the  bug/problem  and  the
     hardware  and  software under which the problem occurred, as
     well as any data needed to reproduce the problem.

AUTHOR
     Stan Janet ([e-mail])