SFS Manual for Programmers

1. Example Program

1.1

'C' Program Source

Here follows the full 'C' source for an example data analysis program. This program prints out the value of fundamental frequency at the time in the file indicated by an annotation of 'NUC'. Such a facility is, of course, more easily provided by sml, see User Manual Section 5.

/* nucfx -- print fx value at annotation 'NUC' */

/* program name and version */
#define PROGNAME "nucfx"
#define PROGVERS "1.0"
char *progname=PROGNAME;   /* for error() */

/* include files */
#include <stdio.h>   /* file i/o */
#include "sfs.h"           /* SFS structures */

/* manifest constants */
#define TARGET "NUC"       /* target annotation */

/* global variables */
double anlocate();         /* forward declaration */
struct item_header anitem; /* AN item header */
struct an_rec*an;          /* AN buffer */
struct item_header fxitem; /* FX item header */
short *fx;                 /* FX buffer */

/* main program */
main(argc,argv)
int argc;
char *argv[];
{
  /* option decoding */
  extern int optind;   /* option index */
  extern char *optarg; /* option argument */
  int c;               /* switch letter */
  int errflg=0;        /* decoding error */
  /* item location */
  int it;              /* item number */
  char *ty;            /* item type */
  char *antype="0";    /* default=last */
  char *fxtype="0";    /* default=last */
  /* file processing */
  char filename[SFSMAXFILENAME];
  /* SFS input file */
  double tim;          /* time of annotation */
  int idx;             /* fx index */

  /* decode options */
  while ((c=getopt(argc,argv,"Ii:"))!=EOF) switch (c) {
  case 'I':/* Identify */
    fprintf(stderr,"%s: Print FX at annotation '%s' V%s\n",
      PROGNAME,TARGET,PROGVERS);
      exit(0);
  case 'i':/* input item selection */
    if (itspec(optarg,&it,&ty) == 0) {
      if (it==AN_TYPE)
        antype=ty;
      else if (it==FX_TYPE)
        fxtype=ty;  
      else
        error("unsuitable item: '%s'",optarg);
    }
    else
      error("illegal item: '%s'",optarg);
    break;
  default:/* bad switch */
    errflg++;
  }

  /* check decoding error & print usage */
  if (errflg || (argc < 2))
    error("usage: %s (-I) (-i item) file",PROGNAME);

  /* get filename */
  if (optind < argc)
    strcpy(filename,sfsfile(argv[optind]));
  else
    error("no data file specified",NULL);

  /* load data sets into memory */
  getitem(filename,AN_TYPE,antype,&anitem,&an);
  getitem(filename,FX_TYPE,fxtype,&fxitem,&fx);

  /* get location of annotation */
  tim = anlocate(&anitem,an,TARGET);

  /* calculate index into fx data */
  idx = (tim - fxitem.offset)/fxitem.frameduration;
  if ((idx < 0) || (idx >= fxitem.numframes))
    printf("no value\n");
  else
    printf("%dHz\n",fx[idx]);

  /* free data buffers */
  free(an);
  free(fx);

  /* and exit */
  exit(0);
}

/* function to locate time of annotation */
double anlocate(item,an,str)
struct item_header *item; /* annotation header */
struct an_rec *an;        /* annotation buffer */
char *str;                /* annotation label */
{
  int i;

  /* scan annotations for match */
  for (i=0;i<item->numframes;i++) {
    if (strcmp(an[i].label,str)==0)
      /* found it - return absolute time */
      return(item->offset+an[i].posn*item->frameduration);
  }
  error("'%s' string not found",str); 
}

This is a full SFS program apart from the text of its manual page, which by convention should be included at the top of the source file.

1.2

Compilation and Execution

If the above source was stored in the file 'nucfx.c' it could be compiled on a Unix system with the command:

% gcc nucfx.c $SFSBASE/lib/libsfs.a -o nucfx

where libsfs.a is the standard SFS library, and the '-o' switch identifies the name of the resulting program. For other operating systems, study the compilation instructions in the makefiles.

To test nucfx:

% nucfx
nucfx: usage: nucfx (-I) (-i item) file
% nucfx -I
nucfx: Print FX at annotation 'NUC' V1.0
%

To run nucfx against a data file:

% nucfx testfil
121Hz
%

To select particular input items:

% nucfx -ian. -ifx^fxac testfil
132Hz
%

To run on a number of data files:

% apply nucfx test1 test2 test3
test1:
121Hz
test2:
105Hz
test3:
117Hz