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


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