THE IRCAM SDIF LIBRARY

Documentation of the Utility Programs

All utilities have the following two common options:

-h

display the usage of the command

-T types-file

load a file with additional SDIF types, or type completions, as explained in the SDIF Specification

The selection specification can be appended to a filename. For various problems with filename and shell metacharacters, the start of the select spec is marked by the last '::' occuring. This way, there is no ambiguity with filenames containing the selection element markers below. To specify a filename containing '::' itself, you just have to append '::' (which means an empty selection which matches all data).

The full syntax for a filename (which can include the directory path, of course) with an SDIF selection is:

    [filename][::[#stream][:frame][/matrix][.column][_row][@time]]

• #stream as with "number"
• frame/matrix as in a file hierarchy
• .column as in a C-struct
• _row as in a LaTeX index
• @time as in English "at time t"

    piano.sdif::#1:1HRM/1HRM.2,3_1-50@2+0.001

• There can be white space between the elements. You have to quote the whole selection if you want to use spaces on a Unix shell command line, however.

• The order of the 6 possible elements is not significant. (Especially, as .column_row may seem unnatural for people with a maths background these can be given in inverse order as _row.column.)

• All specifications can be comma-separated lists of values. Numerical specifications can also be ranges lower-upper (LATER: a missing value lower or upper is replaced by the respective min/max).

• Shortcut: if the first selection element is the frame, you can drop the frame element marker ':'. So instead of filename:::frame@cetera it's filename::frame@cetera

• (LATER: Streams and columns can be given either as a number or as a name.)

• Watch out for possible ambiguities between floating point time spec and column spec: @1.2 will be time 1.2, not time 1, column 2. It is advisable always to put the time spec last to avoid this (.2@1 is ok) or use spaces (@1 .2 is also ok).

• Beware that column selections can produce invalid SDIF output in terms of the description types. It is useful to do this for external analysis of the data in an SDIF file, however. SDIF tools should check if it is allowed to select columns.

• All IRCAM SDIF Tools accept an SDIF selection for the input filename. This works also with standard input using as filename ::select-spec or -::select-spec

Inspecting and reading SDIF files

Usage: querysdif [options] [sdif-file]

Options:
        -a      view ASCII chunks
        -d      view data
        -t  <sdif types file>  specify file with additional sdif types
        -h      this help

The selection can be made using an SDIF Select Specification appended to the input file, or by various flags on the command line.

Using the verbose flag, the selection is echoed and a summary is printed.

The output can be in SDIF (the default) or in two ASCII output formats:

SDIF

In SDIF output, the structure of the input file is kept if no columns or rows are selected. Otherwise, the output may not conform to the SDIF description types.

SDIF output to a terminal is prohibited.

BPF

In the default multi-bpf format, there will be one line per matrix row in the format:

                frame-time  matrix-row...
	

If a column is selected, or the matrix contains only one column, the output file can be used as a break-point-function.

Format

In .format file format (as used with additive), for each matrix there will be one frame in the format:

                number-of-rows  frame-time
                matrix-row-1
                ...
                matrix-row-n
	

Usage: sdifextract [options] [input] [output]

The input filename can have an appended SDIF selection of the form
        ::[#stream][:frame][/matrix][.column][_row][@time]

Options:
        -T <sdif types file>  specify file with additional sdif types
        -v                    be verbose
        -q                    be quiet
        -h                    short help
        -help                 long help (prints sdif types if -T given before)

Format options (see long help for formats):
        -sdif                 output data in SDIF (default)
        -bpf                  output data as ASCII multi-bpf
        -format               output data as ASCII .format file
        -time                 output only frame-times as ASCII
        -data                 output data only (without frame-times) as ASCII
	
Selection options:
        -t <begin>[-<end>|+<delta>]  select time range <begin> to <end> or 
                             <begin>-<delta> to <begin>+<delta>
        -s <stream id>        select stream to extract
        -f <frame signature>  select frame  to extract
        -m <matrix signature> select matrix to extract
        -r <row>              select row    to extract
        -c <column>           select column to extract

Extract data in the given time range, stream, frame type, matrix type, row
and column and write it to an ascii file.  If one of the six selections is
not specified, all data is extracted.

Formats:

-sdif   In SDIF output, the structure of the input file is kept if no
        columns or rows are selected.  Otherwise, the output may not
        conform to the SDIF description types.

-bpf    In multi-bpf format, every matrix row is printed as one line
        of text in the format:

                frame-time  matrix-row...

        If one column is selected, or all selected matrices contain only
        one column, the output file can be used as a break-point-function.

-format In the ASCII .format file format (as used with additive),
        each matrix is printed in the format:

                number-of-rows  frame-time
                matrix-row-1
                ...
                matrix-row-n

-time   In time format, only the frame-times of the selected frames are
        printed, where every time is printed on a new line

-data   In data-only format, output is like bpf but without time (the first column)

Usage: sdiftotext [-t <types file>] [-i <input>] [-o <output>]

This is part of the Pm library.

Usage: tosdif [-<type input>] [-i <input>] [-o <output>]

This is part of the Pm library.