Documentation of IRCAM SDIF utilities

# THE IRCAM SDIF LIBRARY

# Documentation of the Utility Programs

Analysis–Synthesis Team, Diemo Schwarz,

## Introduction

The utilities are part of the SDIF library distribution and are built and installed automatically with the library.

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 SDIF Selection Specification

The SDIF selection specification is a standardized (the d'accord from the community is pending) way to access a part of an SDIF file. The selection can select SDIF frames at certain time intervals and/or certain parts of the data.

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]]

With these mnemonics for the selection elements:

- `#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"

For example,

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

specifies the part of the SDIF file piano.sdif which is contained in stream number 1 in `1HRM` frames and matrices, selects only columns 2 and 3 (frequency and amplitude) of rows (partials) 1 through 50, between the times 1.999 and 2.001. Things to note:

- 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

### querysdif

View summary of data in an SDIF-file. Per default, all ASCII chunks are printed, followed by a count of the frames and the matrices occuring in the file.

    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

### sdifextract

Extract data in the given stream, frame type, matrix type, row and column and write it to a file or to standard output. If one of the five selections is not specified, all data is extracted.

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)

### sdiftotext

Converts an SDIF file into text format, as described in the User Manual.

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

### sdiftoformat and sdiftofmt

Convert an SDIF file with additive analysis data (1TRK or 1HRM frames) into a .format ascii or .fmt binary file.

This is part of the Pm library.

## Writing SDIF files:

### texttosdif

Converts an SDIF file in text format (pseudo--SDIF), as described in the User Manual to true binary SDIF.

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

### formattosdif and fmttosdif

Convert a .format or .fmt file with additive analysis data into an SDIF file with, by default, 1TRK frames.

This is part of the Pm library.

Back to SDIF,

Équipe Analyse/Synthèse, Diemo Schwarz, last update Mai 2006