



         BICSF Berkeley/IRCAM/CARL Sound Filesystem


                          _A_B_S_T_R_A_C_T

          BICSF is a collection of programs which
     implement a filesystem for digital audio applica-
     tions running under Berkeley UNIX.  This document
     gives an overview and describes the installation
     procedure.



_C_R_E_D_I_T_S

Contributors to this suite of programs are numerous, but the
main outlines of the system are due to the work of

o+    Marshall Kirk  McKusick,  William  N.  Joy,  Samuel  J.
     Leffler, Robert S. Fabry for the creation of the Berke-
     ley Fast Filesystem,

o+    Gareth Loy at CARL for the prototype CARL _c_s_o_u_n_d(1carl)
     filesystem,

o+    Rob Gross and Dan Timis at IRCAM for  the  IRCAM  sound
     filesystem,

o+    Brad Garton at Columbia  for  the  Digisound-16  device
     driver and associated play and record programs.

The soundfile system code here is largely that of Rob  Gross
and  Dan  Timis  of  the IRCAM group.  Author ascription has
been appended to the manual pages where known.

The device drivers were written by:

o+    DSC-200: Rusty Wright at CARL,

o+    Digisound 16: Brad Garton at Columbia Princeton,

o+    Dyaxis: Susan Fichera at CARL.

The integration of these various sources  into  one  package
was done by Gareth Loy and Abe Singer at CARL and CMIL.

_L_I_S_T _O_F _P_R_O_G_R_A_M_S _A_N_D _A_L_I_A_S_E_S

Following is a list  of  programs  and  aliases,  and  brief
descriptions:








                      November 3, 1988






                           - 2 -



        ALIASES USING STANDARD UNIX COMMANDS
        catsf   - concatenate soundfiles
        chgrpsf - change soundfile group ownership
        chmodsf - change soundfile mode
        chownsf - change soundfile ownership
        cpsf    - copy soundfile
        mkdirsf - make soundfile directory
        mvsf    - move a soundfile
        pwdsf   - print working soundfile directory
        rmdirsf - remove (empty) soundfile directory
        rmsf    - remove soundfile (or directory tree)



        BACKWARD COMPATABILITY
        sndin   - read from soundfile
        sndout  - write to soundfile



        SPECIAL PROGRAMS
        createsf        - prepare soundfile for recording
        fromsf  - read from soundfile
        gainsf  - normalize or adjust gain of soundfile
        lsf     - list sound files
        normsf  - normalize amplitude of soundfile
        pansf   - pan sound file
        peaksf  - compute peak amplitude and record in soundfile header
        querysf - print out contents of header
        restorsf - restore soundfile from csound dumpsf tape
        retrosf - retrograde a soundfile
        scalesf - gain scale a soundfile
        setsf   - set or modify soundfile header parameters
        sndawk  - signal modification language similar to awk for soundfiles
        swabsf  - swap bytes of samples in soundfile
        tarsf   - tape archive of soundfiles
        tosf    - write to soundfile
        transpsf        - transpose pitch of soundfile
        xdr     - convert soundfile to Sun external data representation



        PLAYBACK/RECORD/MONITOR PROGRAMS
        monitor - monitor digital output of ADCs
        play    - play soundfile
        record  - record soundfile


_N_A_M_E_S _O_F _P_R_O_G_R_A_M_S

In the interests of name coherency, some programs have  been
renamed  from  their  original  forms  at  CARL,  IRCAM, and
Columbia-Princeton.


                      November 3, 1988






                           - 3 -



        PROGRAMS:
        ORIGINAL            RENAMED
        sfcreate            createsf
        sndcat              catsf
        sndgain             gainsf
        sndin               fromsf
        sndinfo             querysf
        sndnorm             normsf
        sndout              tosf
        sndpan              pansf
        sndpeak             peaksf
        sndreverse          retrosf
        sndscale            scalesf
        sndset              setsf
        sndtransp           transpsf



        PLAY, RECORD, ETC:
        DigiSound-16:       ai{play,record,monitor,reset}
        Dyaxis:             dy{play,record}
        DSC-200:            ds{play,record}


Aliases have been created for all the  original  names,  and
are   listed   along   with  the  rest  of  the  aliases  in
./_b_i_c_s_f/_s_t_d._s_f_a_l_i_a_s_e_s._m_4.

_O_R_G_A_N_I_Z_A_T_I_O_N _O_F _S_O_F_T_W_A_R_E

Software is divided into three groups:

o+    device drivers, found in subdirectory ../_s_y_s,

o+    applications programs which depend upon  type  of  con-
     verters,  found  in subdirectories ./{_d_s,_a_i,_d_y}_p_l_a_y and
     ./{_d_s,_a_i,_d_y}_r_e_c_o_r_d,

o+    soundfile manipulation and signal  processing  programs
     (found in the rest of the directories).

_B_R_I_E_F _T_H_E_O_R_Y _O_F _O_P_E_R_A_T_I_O_N

Using BICSF, one  is  presented  with  two  current  working
directories:  one's  regular  UNIX current working directory
(cwd), plus the BICSF cwd, which is initialized to point  to
one's  home  soundfile directory.  Soundfiles are ordinarily
partitioned on a separate disk from other  files.   However,
the  BICSF  soundfile  directory  is  really a standard UNIX
filesystem at bottom.  Having soundfiles on  separate  disks
from regular UNIX disks avoids competition for head movement
with regular UNIX processes.  It  is  also  advisable  where
possible  to  have  a separate disk controller for soundfile


                      November 3, 1988






                           - 4 -


disks to improve throughput for high sampling rates.

There are several reasons to segregate soundfiles from regu-
lar UNIX files.

o+    Conventional wisdom is that the block/fragment size  of
     the soundfile partitions should be set to their maximum
     (currently 8K blocks and 8K fragments).  This is desir-
     able  for  maximum  disk  throughput.   The  bigger the
     blocks, the more efficient the disk I/O  can  be.   But
     UNIX files tend to favor smaller granularization, since
     there tend to be more of them,  and  they  tend  to  be
     small.   It  is more common to have UNIX partitions set
     to 4k/512 to allow more effective filling of the  disk.
     Thus, the two types of files demand different treatment
     to optimize space (for UNIX files) and speed (for BICSF
     files).

o+    System  administration:  soundfiles  are  BIG.   It  is
     better to have them separate from regular UNIX files so
     you don't have to do huge system dumps of  user's  home
     directory  trees.   In  fact,  at  CARL, we do not dump
     soundfile systems, but leave this to the users to do as
     they see fit.

o+    Speed of throughput: you do not want realtime sound I/O
     to  be  in competition with timesharing I/O.  Expect an
     increase of up to 50% for having a  separate  disk  and
     controller for sound.

The idea of simultaneous working directories  for  UNIX  and
BICSF  filesystems  overcomes  the problem of having to name
long absolute pathnames to get to  one's  soundfiles.   This
implementation (developed by Robert Gross) consists of a set
of aliases listed in ./_b_i_c_s_f/_s_t_d._s_f_a_l_i_a_s_e_s._m_4.  An  environ-
ment  variable  _S_F_D_I_R contains the current working soundfile
directory.  The UNIX command has a  BICSF  counterpart  with
the following definition:

        alias     pwdsf     '(cd $SFDIR; /bin/pwd \!*)'

Likewise, the UNIX command has this counterpart:

        alias     catsf     '(cd $SFDIR; /cmil/bin/catsf \!*)'

_c_d_s_f, the BICSF equivalent of sets the _S_F_D_I_R variable  (it's
definition  repays  careful  study). All BICSF programs must
have such an alias as shown above.

_A_D_J_U_S_T_I_N_G _F_O_R _L_O_C_A_L _C_O_N_D_I_T_I_O_N_S

You should  inspect  the  aliases  in  _s_t_d._s_f_a_l_i_a_s_e_s._m_4  and
_s_t_d._c_s_h_r_c._m_4  to  make  sure  they agree with local require-
ments.  In particular, check the play, record,  and  monitor


                      November 3, 1988






                           - 5 -


aliases  in  _s_t_d._s_f_a_l_i_a_s_e_s._m_4,  and  set them to execute the
play/record programs for the converters you are using.  Also
check values of _B_I_N_S_F, _R_O_O_T__S_F_D_I_R, _H_O_M_E__S_F_D_I_R, and _S_F_D_I_R for
local conditions.

When the system  is  installed,  these  two  files  are  run
through  the UNIX macro preprocessor to resolve the location
of the programs the aliases refer to.   _m_4  macros  defining
standard pathnames for executables, manual pages, libraries,
alias files, sources,  etc.  must  be  listed  in  the  file
_c_o_n_f_i_g._m_4,  usually  located in /_u_s_r/_i_n_c_l_u_d_e/_c_a_r_l/_c_o_n_f_i_g._m_4.
See _c_o_n_f_i_g._m_4(1carl) for details.

_S_O_U_R_C_E_S

Sources may be placed in one  of  several  places  depending
upon   local   conventions.    At   CARL,   this   path   is
/_c_a_r_l/_s_r_c/_c_a_r_l/_s_r_c/_b_i_c_s_f.  Elsewhere, a good place to put it
(or find it) is /`_h_o_s_t_n_a_m_e`/_s_r_c/_i_m_p_o_r_t/_c_a_r_l/_s_r_c/_b_i_c_s_f, where
`_h_o_s_t_n_a_m_e` is the name of your machine.

     The  applications  programs  depend  upon  a   library:
_l_i_b_b_i_c_s_f._a.   After  creation, this library may be in one of
several places, depending upon local conventions.  At  CARL,
this  path is /_c_a_r_l/_l_i_b/_l_i_b_b_i_c_s_f._a.  Elsewhere, a good place
to put it (or find it) is /`_h_o_s_t_n_a_m_e`/_l_i_b/_l_i_b_b_i_c_s_f._a.

     It can also be put in /_u_s_r/_l_o_c_a_l/_l_i_b/_l_i_b_b_i_c_s_f._a, but as
this  area  is usually wiped out across upgrades of UNIX, it
is preferable to make a  symbolic  link,  /_u_s_r/_l_o_c_a_l/_l_i_b  ->
/`_h_o_s_t_n_a_m_e`/_l_i_b.   In  this  way, the loader, can still find
local libraries, allowing the loader's -l flag convention:
     % cc file.c -lbicsf
to succeed.  Otherwise, a full path to  the  file  could  be
given:
     % cc file.c /`hostname`/lib/libbicsf.a

Include files in the source code all make generic references
to  include files.  The Makefiles in each directory are made
from their _M_a_k_e_f_i_l_e._m_4 prototypes in each source  directory,
and  compile  the  programs to look in the correct locations
for include files.  These are  almost  universally  relative
paths   to   the  directory  ./_i_n_c_l_u_d_e  (except  for  device
drivers).

_H_A_R_D_W_A_R_E _I_N_S_T_A_L_L_A_T_I_O_N

Besides the installation of your converters, it is important
to block out appropriate partitions for BICSF soundfile par-
titions, and give  them  the  proper  block/fragment  sizes.
Conventional  wisdom  is  that you want to set them to 8K/8K
block/fragment size.   The larger the  block/fragment  size,
the  more efficient the disk can be in reading/writing data.
If possible, you do want sound on a separate physical  disk,


                      November 3, 1988






                           - 6 -


not  sharing  any  other  UNIX function, including swapping,
etc.  It's also useful if sound disks are on  separate  con-
trollers.   CARL  benchmarks are that a Digisound-16 can run
48,000Hz stereo from a Fujitsu Eagle with a single  Xylogics
450  controller on a Sun-3 with a little spare bandwidth.  A
second controller helps a lot.  There are some files in  the
device  driver  directories  for  the  _a_i  driver  (for  the
Digisound-16) which  suggest  further  performance  enhance-
ments.

_D_E_V_I_C_E _D_R_I_V_E_R _I_N_S_T_A_L_L_A_T_I_O_N

Refer to the appropriate subdirectory in ../_s_y_s for the type
of  converter  you  have  and follow the directions you find
there.


_S_O_F_T_W_A_R_E _I_N_S_T_A_L_L_A_T_I_O_N

The code is installed using standard CARL  Software  conven-
tions.   If this code is being installed as part of the CARL
Software  Distribution,  the  process   should   be   mostly
automatic,  save for the installation of the device drivers.
Refer to the instructions for the Distribution, but all that
need be done is to first say

                  make

then

                  make install

and finally

                  make clean


To install standalone, proceede as follows:

First, you need a copy of libcarl.a, from the CARL  software
distribution  to  compile  some  routines,  so  don't bother
unless you have one elsewhere, or are  willing  to  do  wri-
tearounds  (which wouldn't be too difficult) for the missing
routines.

Edit the file ./_i_n_c_l_u_d_e/_c_o_n_f_i_g._m_4,  which  contains  default
and built-in pathnames for programs.  For standalone instal-
lation, the most important are  m4SNDFILESYSTEM,  m4INCLUDE,
m4DESTDIR, and m4MANDIR.

Then execute the file ./Makefirst as follows:

                  % make -f Makefirst



                      November 3, 1988






                           - 7 -


This creates the subdirectory  /_u_s_r/_i_n_c_l_u_d_e/_c_a_r_l,  and  puts
the  file ./_i_n_c_l_u_d_e/_c_o_n_f_i_g._m_4 in it.  It is strongly advised
that this subdirectory be used.  If you want to put it some-
where  else,  you  must  edit  all _M_a_k_e_f_i_l_e._m_4 files in this
directory tree to point to the new  directory,  plus  change
any    C    program    files    that   make   reference   to
/_u_s_r/_i_n_c_l_u_d_e/_c_a_r_l.   There  is  a  script  to   change   the
makefiles  called  ./misc/fixmakefiles  that  you can use to
expedite this process, if necessary.

Next, say

                  % make

which does the following steps:

o+    remakes all Makefiles with correct paths,

o+    installs    the    remaining    include    files     in
     /_u_s_r/_i_n_c_l_u_d_e/_c_a_r_l,

o+    builds the library

o+    compiles application programs.

Next say

                  % make install

which  will  install  binaries,  manual  pages,  and  system
aliases.

Lastly, say

                  % make clean

to remove executables and .o files.

To run off documentation, say

                  $ make roffall


_S_Y_S_T_E_M _A_L_I_A_S_E_S

The  contents  of  ./_b_i_c_s_f/_s_t_d._s_f_a_l_i_a_s_e_s  must  somehow   be
sourced  by  all users when they log in.  Furthermore, it is
useful to have users refer to a  master  copy,  so  that  as
BICSF  programs  come  and  go,  a single file only needs be
changed.  At CMIL, for instance, this is done as follows.

All users have a standard ._c_s_h_r_c file in their  home  direc-
tories which contains the following line:



                      November 3, 1988






                           - 8 -



        source /`hostname`/lib/std.cshrc

where `_h_o_s_t_n_a_m_e` is either the name of the machine, or  some
other  well-known  local  path.   The file _s_t_d._c_s_h_r_c in turn
sources  /`_h_o_s_t_n_a_m_e`/_l_i_b/_s_t_d._s_f_a_l_i_a_s_e_s,  which   initializes
shell variables and establishes the system aliases for BICSF
commands.

There is a prototype .cshrc file, ./_b_i_c_s_f/_d_o_t_c_s_h_r_c, which is
provided  for convenience.  These should be the basis of the
.cshrc files all users have.  At CARL, we  have  an  _a_d_d_u_s_e_r
shell script which installs new users.  Part of it's task is
to copy dotcshrc to ~newuser/.cshrc.










































                      November 3, 1988



