SPHERE(3)

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 endorsement 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 associated 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 describing 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 argument 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 deallocate 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, double, 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 written 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 john@jaguar.ncsl.nist.gov. 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 (stan@jaguar.ncsl.nist.gov)