Pm
A Library for Additive Analysis/Transformation/Synthesis

Guillermo García*

Version 1.2





Library Version History



Version Date Author Changes

0.9 2 . July 1994 Guillermo García Original version
1.0 21 . May 1997 Rolf Woehrmann Reworked for Mac/Unix
1.1 14 . May 1998 Diemo Schwarz Added PmGetAllPartial(Freq|Ampl|Phase)
1.2.1 22 . July 1999 Diemo Schwarz Added SDIF I/O, initialisation, file handling
1.2.2 23 . September 1999 Diemo Schwarz Added bpf I/O, changed PmAddSynt prototype






Source control revision of this document: $Header: /usr/local/cvsroot/Pm/doc/Pm.tex,v 1.6 1999/09/27 14:07:55 schwarz Exp $

If you prefer to read on paper, you can download the compressed PostScript version of the user documentation.




1   Alphabetical Index

additive analysis/synthesis
Additive Synthesis Function
Breakpoints
Building the Library
Compilation
Converting
Data Types
Documentation
File Formats
File Handling
fmttoformat
fmttosdif
formattofmt
formattosdif
Frame Data Access
Frame Sets
FrameSet Data Access
FrameSet Data Transfer
FrameSet Editing
Functions: Synopsis and Description
Header
Include
Initialisation
Installation of the Library
Introduction
libm.a
libPm.a
libraries
PartialSet Data Access Functions
PartialSet Processing at FrameSet Level
Partialsets
pm Parser
PmAddBreakPoint
PmAddFrameData
PmAddPartial
PmAddSynt
PmBreakPoint
PmCloseFile
pmconvert
PmCopyFrameSet
PmCopyPartialSet
PmCopySubPartialSet
PmCreateBreakPoint
PmCreateFrameSet
PmCreateParamSet
PmCreatePartialSet
PmCutFrameSet
PmDecrNbOfFrames
PmDeInit
PmDeletePartial
PmDeleteSubPartialSet
PmDetectSpectralPeaks
PmEvalBreakPoint
PmExtractBreakPoint
PmFadeHarmEnds
PmFrameSet
PmFreeBreakPoint
PmFreeFrameSet
PmFreeParamSet
PmFreePartialSet
PmFreqTransp
PmFvarFreqTransp
PmGetActiveParamSetId
PmGetBeginTime
PmGetBreakPoint
PmGetBreakPointNb
PmGetEndTime
PmGetExtension
PmGetFileFormat
PmGetFrameData
PmGetFrameTime
PmGetNbOfFrames
PmGetNbOfParamSets
PmGetParamSet
PmGetParamSetAllocSize
PmGetParamSetElemSize
PmGetParamSetName
PmGetParamSetNb
PmGetParamSetPtr
PmGetParamSetType
PmGetPartialAmpl
PmGetPartialFreq
PmGetPartialIndex
PmGetPartialPhase
PmGetPartialSetAllocSize
PmGetPartialSetNb
PmGetPartialSetTime
Pm.h
PmInit
PmInsertFrameSet
PmInterpPartialSet
PmIvarFreqTransp
PmLoadBreakPoint
PmLoadBreakPointOrConst
PmMoveSubPartialSet
PmMultSpectralEnv
PmNameToFormat
PmOpenFile
PmParamSetId
PmPartialSet
PmPresentPartial
PmPutBeginTime
PmPutEndTime
PmPutFrameTime
PmPutParamSet
PmPutPartialAmpl
PmPutPartialFreq
PmPutPartialIndex
PmPutPartialPhase
PmPutPartialSetNb
PmPutPartialSetTime
PmReadBreakPoint
PmReadPartialSet
PmReallocBreakPoint
PmReallocFrameSet
PmReallocPartialSet
PmReverseFrameSet
PmSaveBreakPoint
PmScaleFrameSetTime
PmSeeve
PmSetSpectralEnv
PmShiftFrameSet
PmTimeScaling
PmUnwrapPhase
PmWrapPhase
PmWriteBreakPoint
PmWritePartialSet
Programs
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
SDIF
sdiftofmt
sdiftoformat
Synopsis and Description of Functions
Synthesis
Testing
The pm Parser
Tools
Using the Library



2   Introduction

Pm is a C library for additive analysis, transformation, and synthesis of sound. Other signal models will be incorporated in the future.

This document describes the Pm library from the user's point of view. For the programmer, an automatically generated HTML documentation of all data types and functions (even the internal ones) is available.


3   Data Types

Pm defines some specific data structures. Access to fields of these structures should always be made using the data interface functions provided by Pm.

The following data types are specific to Pm:


3.1   PmPartialSet

A set of partials defined at one given time.

Accessible parameters of a PartialSet are:




3.2   PmFrameSet

A set of data frames.

A frame is defined as a collection of parameter sets defined at one given time.

A frame can hold parameter sets of different types, including PartialSet and C basic data types.

When a FrameSet is first created, it has a given number of allocated, empty frames. Frames can be filled with data strictly in sequential order, so as to avoid gaps of data in the middle of a FrameSet.

Filled frames will be called "active" frames from now on.

Times in a FrameSet must always be in increasing order. Otherwise, Pm functions are not warranted to work.

A FrameSet is defined in a time interval [beginTime ; endTime]. This continuous-time limits may be different from the respective times of the first and last frame of the FrameSet. They are used in some editing functions (PmCutFrameSet, PmInsertFrameSet) to keep the exact time distance between frames.

Accessible parameters of a FrameSet are:

GLOBAL LEVEL:

FRAME LEVEL:




3.3   PmParamSetId

An identifier of a parameter set in a frame set.


3.4   PmBreakPoint

A simple breakpoint function using float data type.


4   Compilation




4.1   Using the Library

C files calling Pm functions must include the header file Pm.h:
#include "Pm.h"
You must link to the libraries libPm.a and the math library libm.a with:
-lPm -lm
To find them, the search paths for the compiler and the linker must include the Pm installation directories, at the moment, that's
-I/u/formes/include -L/u/formes/lib/$(ARCH)



4.2   Building the Library

In the sub-directory src of the Pm project directory, say make to build the library, the tools, and the parser. These can be built individually in their respective sub-directories LibSrc, Tools, and Parser.


4.3   Testing

The library, the tools, and the parser can be tested in directory src/test. Say make to run various test cases.


4.4   Installation of the Library

By saying make install the header file, the SDIF type definitions, the library, and the programs are installed in /u/formes/include, /u/formes/lib, /u/formes/lib/$(ARCH), and /u/formes/bin/$(ARCH), respectively.

The installs can be initiated seperately with the targets install-incl, install-lib (includes the types file), and install-prog.

The installation root can be changed from /u/formes by setting the make-variable PREFIX:

make install PREFIX=/where/do/you/want/to/install/today 



4.5   Documentation

The documentation is generated in the doc sub-directory. The make targets are: tex, html, and cocoon, for the printable user documentation, its HTML version, and the internal programmer documentation, respectively.




5   Functions: Synopsis and Description




5.1   Initialisation






5.1.1   PmInit

Synopsis
int PmInit (void)
Initialises the Pm library (especially the SDIF part).

Returns 1 on success.






5.1.2   PmDeInit

Synopsis
int PmInit (void)
Deinitialises the Pm library (free static memory and deinit the SDIF part).

Returns 1 on success.


5.2   File Handling




5.2.1   File Formats

Pm recognises the following file formats for I/O:

PM_ASCII
Ascii format, as described in additive, usually with file extension .format
PM_BIN
Binary format, as described in additive, usually with file extension .fmt
PM_SDIF
SDIF format, usually with file extension .sdif. With SDIF, there are several sub-formats to choose from, described at CNMAT's SDIF site.

PM_SDIF_TRACKS
partial tracks (the default, when only PM_SDIF is used)
PM_SDIF_HARMONICS
harmonic partials
PM_SDIF_PEAKS
picked peaks





5.2.2   PmGetExtension

Synopsis
char *PmGetExtension (char *name)
Find the extension of a filename (the part after the last '.' of the filename part of the full path).

Returns Pointer to extension (after the '.'), or NULL if no extension found






5.2.3   PmNameToFormat

Synopsis
int PmNameToFormat (char *name)
Determine Pm format from string name.

Returns format.






5.2.4   PmGetFileFormat

Synopsis
int PmGetFileFormat (char *name, int defnonsdif, int defsdif)
Determine Pm format from extension of file given by name, unless it is an SDIF file (determined by the first 4 characters in the file.

Returns formatdefsdif, if file is an SDIF file, otherwise, the format determined by the extension in name, if none found defnonsdif.






5.2.5   PmOpenFile

Synopsis
FILE *PmOpenFile (char *name, int mode, int format)
Open file name with given mode (PM_READ, PM_WRITE, or PM_APPEND) and format.

Note that, on systems which have a popen() function, if the extension is (.gz), the file is automatically decompressed or compressed with gzip, using a pipe.

Returns opened file pointer or NULL on failure. Note that in case of an SDIF format the return value points to an Sdif file structure and must not be used except for Pm i/o.






5.2.6   PmCloseFile

Synopsis
void PmCloseFile (FILE *f, int format)
Close a file which was opened with format format.


5.3   Breakpoints






5.3.1   PmCreateBreakPoint

Synopsis
PmBreakPoint PmCreateBreakPoint (int size)
Creates and returns a BreakPoint of size points.

Returns NULL if there is no available memory.






5.3.2   PmReallocBreakPoint

Synopsis
PmBreakPoint PmReallocBreakPoint (PmBreakPoint aBP, int size)
Reallocates input BreakPoint aBP up to size points.

Returns

If reallocation is successful, returns the same input BreakPoint aBP with reallocated number of points.

If reallocation fails, returns NULL and the size of aBP remains unchanged.

If aBP is NULL, returns a new BreakPoint of size points, or NULL if reallocation failed.






5.3.3   PmFreeBreakPoint

Synopsis
void PmFreeBreakPoint (PmBreakPoint aBP)
Frees aBP.






5.3.4   PmReadBreakPoint

Synopsis
int PmReadBreakPoint (FILE *Stream, PmBreakPoint aBP, int format_flag)
Reads aBP from the input Stream.

format_flag indicates the format of the input file:

PM_BIN or PM_BIN_BPF
binary [x y] points
PM_ASCII or PM_ASCII_BPF
ascii [x y] points on the same line . Comments can be placed after each point [x y] in a line.
PM_SDIF_BPF
SDIF format, by default reads 1FQ0 frames and matrices. If an SDIF selection specification is appended to the file name, the stream, frame and matrix type therein will be read.
Returns [number of points] if a BreakPoint was read, -1 if there is no available memory to perform the operation.






5.3.5   PmWriteBreakPoint

Synopsis
void PmWriteBreakPoint (FILE *Stream, PmBreakPoint aBP, int format_flag)
Writes aBP to the output Stream.

format_flag indicates the format of the input stream (see above).






5.3.6   PmLoadBreakPoint

Synopsis
PmBreakPointPmLoadBreakPoint (char *name)
Creates and loads an entire bpf from a file given by name. The format is determined by checking if it is an SDIF file, if not, PM_ASCII_BPF is assumed.

Returns the bpf read, which must be PmFreeBreakPoint'ed by the caller.






5.3.7   PmLoadBreakPointOrConst

Synopsis
PmBreakPointPmLoadBreakPointOrConst (char *nameorconst)
If nameorconst looks like a number, returns a constant PmBreakPoint with that value, else, uses it as filename and loads a bpf from it. This is especially useful for parsing command line arguments, which can then be transparently either a constant (e.g. maximum fundamental frequency to be considered) or a bpf from a file.

On load, the function tries to auto-detect the file format, if it is not SDIF, for now we assume PM_ASCII_BPF.

Returns: A freshly created PmBreakPoint (which must be PmFreeBreakPoint'ed by the calling program).






5.3.8   PmSaveBreakPoint

Synopsis
int PmSaveBreakPoint (char *name, PmBreakPointbp, int format)
Saves an entire bpf to file name, in format format. If the format is PM_SDIF_BPF, the SDIF selection specification determines the SDIF stream, frame and matrix type (1FQ0 by default). E.g. if name = "foo.sdif::#4:1WRP/1BPF" writes on stream 4 as 1BPF matrices in 1WRP frames.

Returns 1 on success.






5.3.9   PmEvalBreakPoint

Synopsis
float PmEvalBreakPoint (PmBreakPoint aBP, float x)
Evaluates the function aBP at X = x by linear interpolation and returns the corresponding Y value.






5.3.10   PmAddBreakPoint

Synopsis
int PmAddBreakPoint (PmBreakPoint aBP, float x, float y)
Adds a point [x ; y] to the function aBP.

Returns 1 if addition was successful, -1 if there is no available memory to add the point.






5.3.11   PmExtractBreakPoint

Synopsis
void PmExtractBreakPoint (PmBreakPoint aBP, float x)
Extracts (=deletes) from the function aBP the point whose x-coordinate is closest to x.






5.3.12   PmGetBreakPoint

Synopsis
int PmGetBreakPoint (PmBreakPoint aBP, int pos, float *px, float *py)
Writes to the addresses px and py the coordinates of the point in position=pos in the function aBP.

Returns -1 if pos is greater than the [nb_of_points - 1] of aBP, 1 otherwise.






5.3.13   PmGetBreakPointNb

Synopsis
int PmGetBreakPointNb (PmBreakPoint aBP)
Returns the number of points of the function aBP.


5.4   Partialsets






5.4.1   PmCreatePartialSet

Synopsis
PmPartialSet PmCreatePartialSet (int max_index)
Creates and returns a new PartialSet.

max_index is the greatest partial index the new PartialSet can initially hold. Reallocation of an existing PartialSet can be done later.

Returns NULL if there is no available memory.






5.4.2   PmReallocPartialSet

Synopsis
PmPartialSetPmReallocPartialSet (PmPartialSet aPS, int new_max_index)
Reallocates the input PartialSet aPS up to new_max_index.

Returns

If reallocation is successful, returns the same input PartialSet aPS with reallocated size.

If reallocation fails, returns NULL and the size of aPS remains unchanged.

If aPS is NULL, returns a new PartialSet of size new_max_index, or NULL if reallocation failed.

Most functions that operate on PartialSets provide for automatic reallocation. Only the PartialSet's data access functions require the application programmer to test allocation sizes before putting/getting data to/from a PartialSet.






5.4.3   PmFreePartialSet

Synopsis
void PmFreePartialSet (PmPartialSet aPS)
Frees PartialSet aPS.






5.4.4   PmReadPartialSet

Synopsis
int PmReadPartialSet (FILE *Stream, PmPartialSet aPS, int format_flag)
Reads one PartialSet aPS from the input Stream.

format_flag indicates the formatof the input stream.

Returns

1 if a PartialSet was read.

0 if EOF

-1 if there is no available memory to perform the operation.






5.4.5   PmWritePartialSet

Synopsis
int PmWritePartialSet (FILE *Stream, PmPartialSet aPS, int format_flag)
Writes one PartialSet aPS to the output Stream.

format_flag indicates the formatof the output stream.

Returns

1 if a PartialSet was written.

-1 if there is no available memory to perform the operation.






5.4.6   PmCopyPartialSet

Synopsis
void PmCopyPartialSet (PmPartialSet source, PmPartialSet destination)
Copies data from PartialSet source to PartialSet destination.

Returns 1 if data were successfully copied, -1 if there is no available memory to copy all source data.






5.4.7   PmDetectSpectralPeaks

Synopsis
int PmDetectSpectralPeaks (float *complex_fft, PmPartialSet peaks, float srate, int fft_size, int window_size)
Fills peaks with peaks detected in the spectrum complex_fft.

Index values of PartialSet peaks do not correspond to partial indexes. They identify a peak in the spectrum.

Vector complex_fft contains FFT real part at even locations, and FFT imaginary part at odd locations.

srate : sampling rate

fft_size : number of complex fft points

window_size : number of points of the signal window

Returns

[number of peaks] if detection is successful.

-1 if there is no available memory to perform the operation.






5.4.8   PmSeeve

Synopsis
int PmSeeve (PmPartialSet peaks, PmPartialSet harms, float f0, float band, float srate, int nbHarm)
Logical filtering of spectral peaks: selects the peak of greatest amplitude in each harmonic band.

peaks : input spectral peaks. Could be the output of PmDetectSpectralPeaks.

harms : output selected spectral peaks

f0 : fundamental frequency value

band : width of harmonic bands in pct (i.e. 100 means bandwidth = f0)

srate : sampling rate

nbHarm : max number of harmonics

Returns ?






5.4.9   PmPresentPartial

Synopsis
int PmPresentPartial (PmPartialSet aPS, int index)
Returns 1 if partial index is present in PartialSet aPS, 0 otherwise.






5.4.10   PmUnwrapPhase

Synopsis
float PmUnwrapPhase (float prev_freq, float next_freq, float prev_phase, float next_phase, float dtime)
Returns the unwrapped phase variation of a variable-frequency sinusoid between two times prev_time and next_time.

prev_freq : frequency at prev_time

next_freq : frequency at next_time

prev_phase : phase at prev_time

next_phase : phase at next_time

dtime : [next_time - prev_time]






5.4.11   PmWrapPhase

Synopsis
float PmWrapPhase (float phase)
Wraps phase to the inverval [-PI;PI].






5.4.12   PmFreqTransp

Synopsis
int PmFreqTransp (PmPartialSet nextOrig, PmPartialSet nextTransf, PmPartialSet prevOrig, PmPartialSet prevTransf, float nextFactor, float prevFactor)
Transposes frequencies of PartialSet nextOrig by factor nextFactor and puts the result in nextTransf.

As phase evolution is taken into account, this algorithm needs past and current data, defined at times prev_time and next_time respectively:

nextOrig : input non-transformed PartialSet at next_time.

nextTransf : output transformed PartialSet at next_time.

prevOrig : input non-transformed PartialSet at prev_time.

prevTransf : input transformed PartialSet at prev_time.

nextFactor : transposition factor at next_time.

prevFactor : transposition factor at prev_time.

If prevOrig or prevTransf are set to NULL, phase is not considered (and prevFactor is not used). In this case, phase values after frequency transposition are nonsense.

The algorithm still works if nextOrig is equal to nextTransf. In this case, nextOrig non-transformed data is overwritten.

Returns

1 if transposition was successful.

-1 if there is no available memory to perform the operation.






5.4.13   PmIvarFreqTransp

Synopsis
int PmIvarFreqTransp (PmPartialSet nextOrig, PmPartialSet nextTransf, PmPartialSet prevOrig, PmPartialSet prevTransf, PmBreakPoint nextIvar, float prevIvar)
Index-variable frequency transposition: transposes frequencies of PartialSet nextOrig by a factor which depends on the partial index.

Transposition factor is defined in a breakpoint function nextIvar which contains points [index ; factor].

prevIvar is the breakpoint function which has been used at prev_time.

Other features are the same as for PmFreqTransp.

Returns

1 if transposition was successful.

-1 if there is no available memory to perform the operation.






5.4.14   PmFvarFreqTransp

Synopsis
int PmFvarFreqTransp (PmPartialSet nextOrig, PmPartialSet nextTransf, PmPartialSet prevOrig, PmPartialSet prevTransf, PmBreakPoint nextIvar, float prevIvar)
Frequency-variable frequency transposition: transposes frequencies of PartialSet nextOrig by a factor which depends on the partial frequency.

Transposition factor is defined in a breakpoint function nextIvar which contains points [frequency ; factor].

prevIvar is the breakpoint function which has been used at prev_time.

Other features are the same as for PmFreqTransp.

Returns

1 if transposition was successful.

-1 if there is no available memory to perform the operation.






5.4.15   PmTimeScaling

Synopsis
int PmTimeScaling (PmPartialSet nextOrig, PmPartialSet nextTransf, PmPartialSet prevOrig, PmPartialSet prevTransf, float scaleFactor)
Scales time of PartialSet nextOrig according to factor scaleFactor and puts the result in nextTransf.

The interval between nextTransf and prevTransf is calculated as [next_time-prev_time] multiplied by factor scaleFactor.

Input and output PartialSets are the same as for PmFreqTransp.

If prevOrig or prevTransf are set to NULL:

Returns

1 if scaling was successful.

-1 if there is no available memory to perform the operation.






5.4.16   PmInterpPartialSet

Synopsis
void PmInterpPartialSet (PmPartialSet left, PmPartialSet right, PmPartialSet interp, int phase_flag)
Calculates an interpolated PartialSet interp between PartialSets left and right.

The interpolation factor is calculated as

(interp_time - left_time) / (right_time - left_time)

so time of PartialSet interp must be set before calling the function.

Amplitudes are linearly interpolated.

If phase_flag is set to 0, phases are not considered and frequencies are linearly interpolated.

If phase_flag is different from 0, phases are assumed to be valid; in this case phases and frequencies are interpolated using 3rd-degree and 2nd-degree polynoms respectively.

Returns

1 if interpolation was successful.

-1 if there is no available memory to perform the operation.






5.4.17   PmSetSpectralEnv

Synopsis
int PmSetSpectralEnv (PmPartialSet inPS, PmPartialSet outPS, float *env, float scale_factor, float srate, int env_size, int energy_flag)
Imposes the spectral envelope defined by env to inPS.

Amplitudes of partials in inPS are recalculated by interpolating env at the corresponding partial frequencies.

The spectral envelope defined by env can be previously rescaled by a scale_factor.

scale_factor > 1 stretches the envelope.

scale_factor < 1 compresses the envelope.

The result is placed in outPS, which can be eventually equal to inPS.

env is a spectral envelope defined at env_size regularly spaced points, corresponding to the frequency interval [0 - srate/2].

If energy_flag is different from 0, output and input energies are equalized.

srate : sampling rate

Returns

1 if the operation was successful.

-1 if there is no available memory to perform the operation.






5.4.18   PmMultSpectralEnv

Synopsis
int PmMultSpectralEnv (PmPartialSet inPS, PmPartialSet outPS, float *env, float scale_factor, float srate, int env_size, int energy_flag)
Same as PmSetSpectralEnv but multiplies amplitudes of partials by the envelope instead of imposing it.






5.4.19   PmCopySubPartialSet

Synopsis
int PmCopySubPartialSet (PmPartialSet inPS, PmPartialSet outPS, int *subset_indexes, int nb_indexes)
Partials defined in inPS, and whose indexes are present in subset_indexes, are copied to outPS.

outPS is reset to an empty PartialSet before copy is performed.

nb_indexes : number of elements of subset_indexes.

Returns

1 if the operation was successful.

-1 if there is no available memory to perform the operation.






5.4.20   PmMoveSubPartialSet

Synopsis
int PmMoveSubPartialSet (PmPartialSet inPS, PmPartialSet outPS, int *subset_indexes, int nb_indexes)
Partials defined in inPS, and whose indexes are present in subset_indexes, are copied to outPS and removed from inPS.

outPS is reset to an empty PartialSet before move is performed.

nb_indexes : number of elements of subset_indexes.

Returns
1 if the operation was successful,
-1 if there is no available memory to perform the operation.






5.4.21   PmAddSynt

Synopsis
int PmAddSynt(PmPartialSetleft, PmPartialSetright, float *outSig, int maxsize, int done, float srate, int phase_flag)
Performs additive synthesis in the interval between PartialSets left and right, and puts the resulting signal in outSig. At most maxsize samples are computed. Because the interval can be larger than maxsize (the output buffer size), PmAddSynt must be called in a loop:

    sig_done = 0;
    do {
        sig_size = PmAddSynt(leftPartialSet, rightPartialSet, 
                             outSig, maxsize, sig_done, srate, phaseFlag);
        sig_done += sig_size;

        /* do something useful with the synthesized signal */
        ...
    } while (sig_size == maxsize);
If phase_flag is set to 0, phases are not considered and frequencies are linearly interpolated.

If phase_flag is different from 0, phases are assumed to be valid; in this case phases and frequencies are interpolated using 3rd-degree and 2nd-degree polynoms respectively.

srate : output sampling rate

Returns
the number of output samples actually computed if the operation was successful.
-1 if there is no available memory to perform the operation.


5.5   PartialSet Data Access Functions






5.5.1   PmPutPartialSetTime

Synopsis
void PmPutPartialSetTime (PmPartialSet aPS, float time)





5.5.2   PmGetPartialSetTime

Synopsis
float PmGetPartialSetTime (PmPartialSet aPS)





5.5.3   PmPutPartialSetNb

Synopsis
void PmPutPartialSetNb (PmPartialSet aPS, int nb)





5.5.4   PmGetPartialSetNb

Synopsis
int PmGetPartialSetNb (PmPartialSet aPS)





5.5.5   PmGetPartialSetAllocSize

Synopsis
int PmGetPartialSetAllocSize (PmPartialSet aPS)





5.5.6   PmPutPartialIndex

Synopsis
void PmPutPartialIndex (PmPartialSet aPS, int position, int index)





5.5.7   PmGetPartialIndex

Synopsis
int PmGetPartialIndex (PmPartialSet aPS, int position)





5.5.8   PmPutPartialFreq

Synopsis
void PmPutPartialFreq (PmPartialSet aPS, int index, float freq)





5.5.9   PmGetPartialFreq

Synopsis
float PmGetPartialFreq (PmPartialSet aPS, int index)





5.5.10   PmPutPartialAmpl

Synopsis
void PmPutPartialAmpl (PmPartialSet aPS, int index, float ampl)





5.5.11   PmGetPartialAmpl

Synopsis
float PmGetPartialAmpl (PmPartialSet aPS, int index)





5.5.12   PmPutPartialPhase

Synopsis
void PmPutPartialPhase (PmPartialSet aPS, int index, float phase)





5.5.13   PmGetPartialPhase

Synopsis
float PmGetPartialPhase (PmPartialSet aPS, int index)





5.5.14   PmAddPartial

Synopsis
int PmAddPartial (PmPartialSet aPS, int index, float freq, float ampl, float phase)
Adds a new partial with index index to PartialSet aPS.

freq, ampl and phase are the parameters of the new partial.

Returns

1 if the new partial was added.

0 if a partial with index index was already present in PartialSet aPS. In this case, new parameters do not overwrite old ones.






5.5.15   PmDeletePartial

Synopsis
int PmDeletePartial (PmPartialSet aPS, int index)
Deletes partial with index index from PartialSet aPS.

Returns

1 if the partial was deleted.

0 if a partial with index index did not exist in PartialSet aPS.






5.5.16   PmDeleteSubPartialSet

Synopsis
int PmDeleteSubPartialSet (PmPartialSet aPS, int *subset_indexes, int nb_indexes)
Partials defined in aPS, and whose indexes are present in subset_indexes, are removed from aPS.

Returns the number of deleted partials.


5.6   Frame Sets






5.6.1   PmCreateFrameSet

Synopsis
PmFrameSet PmCreateFrameSet (int nb_of_frames, int nb_of_paramsets)
Creates a new FrameSet.

nb_of_frames : max number of frames of the FrameSet.

nb_of_paramsets : max number of ParamSets the FrameSet can support.

Returns a new FrameSet, or NULL if there is no available memory.






5.6.2   PmReallocFrameSet

Synopsis
PmFrameSet PmReallocFrameSet (PmFrameSet aFS, int nb_of_frames, int nb_of_paramsets)
Reallocates FrameSet aFS in the two dimensions: frames and sets of parameters.

nb_of_frames : new max number of frames of the FrameSet.

nb_of_paramsets : new max number of ParamSets the FrameSet can support. If a new dimension size (i.e. nb_of_frames or nb_of_paramsets) is smaller than the current dimension size, reallocation of this dimension is ignored.

Returns

If reallocation is successful, returns the same input FrameSet aFS with reallocated number of frames and ParamSets.

If reallocation fails, returns NULL and the size of aFS remains unchanged.

If aFS is NULL, returns a new FrameSet or NULL if reallocation failed.

Reallocation is performed in two stages: first for ParamSets, secondly for Frames. It can eventually fail at the second stage; in this case reallocation of ParamSets remains valid even if the function returns NULL.

Most functions that operate on FrameSets provide for automatic reallocation.






5.6.3   PmFreeFrameSet

Synopsis
void PmFreeFrameSet (PmFrameSet aFS)
Frees FrameSet aFS.






5.6.4   PmCreateParamSet

Synopsis
PmParamSetId PmCreateParamSet (PmFrameSet aFS, int paramset_length, int paramset_type, char *paramset_name)
Allocates memory for a set of paramset_length elements of paramset_type type in each frame of FrameSet aFS.

paramset_type possible values are:

C basic data types:

PM_CHAR, PM_SHORT, PM_INT, PM_LONG, PM_FLOAT, PM_DOUBLE
Pm specific data types:

PM_PARTIAL
Returns an identifier of the new ParamSet, or -1 if there is no available memory to create the new paramset, or if paramset_type is unknown for the library.






5.6.5   PmFreeParamSet

Synopsis
void PmFreeParamSet (PmFrameSet aFS, PmParamSetId aParamSetId)
Frees ParamSet identified by aParamSetId in FrameSet aFS.


5.7   FrameSet Data Access






5.7.1   PmGetNbOfFrames

Synopsis
int PmGetNbOfFrames (PmFrameSet aFS)
Returns the number of active frames in FrameSet aFS.






5.7.2   PmDecrNbOfFrames

Synopsis
void PmDecrNbOfFrames (PmFrameSet aFS, int N)
Decrease in N the number of active frames of FrameSet aFS, by throwing away the last N frames.

N is automatically limited to the number of active frames of FrameSet aFS.






5.7.3   PmGetBeginTime

Synopsis
float PmGetBeginTime (PmFrameSet aFS)
Returns the begin time of FrameSet aFS.






5.7.4   PmPutBeginTime

Synopsis
void PmPutBeginTime (PmFrameSet aFS, float time)
Sets to time the begin time of FrameSet aFS.






5.7.5   PmGetEndTime

Synopsis
float PmGetEndTime (PmFrameSet aFS)
Returns the end time of FrameSet aFS.






5.7.6   PmPutEndTime

Synopsis
void PmPutEndTime (PmFrameSet aFS, float time)
Sets to time the end time of FrameSet aFS.






5.7.7   PmGetNbOfParamSets

Synopsis
int PmGetNbOfParamSets (PmFrameSet aFS)
Returns the number of active ParamSets in FrameSet aFS.






5.7.8   PmGetActiveParamSetId

Synopsis
PmParamSetId PmGetActiveParamSetId (PmFrameSet aFS, int pos)
Returns the identifier of the ParamSet in position pos in FrameSet aFS.






5.7.9   PmGetParamSetType

Synopsis
int PmGetParamSetType (PmFrameSet aFS, PmParamSetId aParamSetId)
Returns the type of ParamSet identified by aParamSetId in FrameSet aFS.

ParamSet type is one of the following:

C basic data types:

PM_CHAR, PM_SHORT, PM_INT, PM_LONG, PM_FLOAT, PM_DOUBLE
Pm specific data types:

PM_PARTIAL





5.7.10   PmGetParamSetName

Synopsis
char * PmGetParamSetName (PmFrameSet aFS, PmParamSetId aParamSetId)
Returns the name of ParamSet identified by aParamSetId in FrameSet aFS.






5.7.11   PmGetParamSetElemSize

Synopsis
int PmGetParamSetElemSize (PmFrameSet aFS, PmParamSetId aParamSetId)
Returns the size of the variable type of ParamSet identified by aParamSetId in FrameSet aFS.


5.8   Frame Data Access






5.8.1   PmGetFrameTime

Synopsis
float PmGetFrameTime (PmFrameSet aFS, int frame_index)
Returns the time of frame in position frame_index in FrameSet aFS.

Returns PM_MAXFLOAT if frame_index is equal to or greater than the number of active frames in FrameSet aFS.






5.8.2   PmPutFrameTime

Synopsis
void PmPutFrameTime (PmFrameSet aFS, int frame_index, float time)
Sets to time the time of frame in position frame_index in FrameSet aFS.






5.8.3   PmGetParamSetAllocSize

Synopsis
int PmGetParamSetAllocSize (PmFrameSet aFS, int frame_index, PmParamSetId aParamSetId)
Returns the allocated number of elements, in frame number frame_index, for a ParamSet identified by aParamSetId in FrameSet aFS,

-1 if frame_index is equal to or greater than the number of allocated frames in FrameSet aFS.






5.8.4   PmGetParamSetNb

Synopsis
int PmGetParamSetNb (PmFrameSet aFS, int frame_index, PmParamSetId aParamSetId)
Returns the current number of elements, in frame number frame_index, of a ParamSet identified by aParamSetId in FrameSet aFS.

-1 if frame_index is equal to or greater than the number of active frames in FrameSet aFS.






5.8.5   PmGetParamSetPtr

Synopsis
void * PmGetParamSetPtr (PmFrameSet aFS, int frame_index, PmParamSetId aParamSetId)
Returns the data pointer of ParamSet identified by aParamSetId in FrameSet aFS, in frame number frame_index.

NULL if frame_index is equal to or greater than the number of allocated frames in FrameSet aFS.


5.9   FrameSet Data Transfer






5.9.1   PmGetParamSet

Synopsis
int PmGetParamSet (PmFrameSet aFS, int frame_index, PmParamSetId aParamSetId, void data_ptr, int data_nb)
Copies a ParamSet from frame frame_index to the space pointed by data_ptr.

The ParamSet is identified by aParamSetId in FrameSet aFS.

If the ParamSet lenght in frame frame_index is greater than argument data_nb, data_nb elements are copied.

Otherwise, the entire ParamSet is copied.

Returns

0 if frame_index is equal to or greater than the number of active frames.

1 if operation is successful.






5.9.2   PmPutParamSet

Synopsis
int PmPutParamSet (PmFrameSet aFS, int frame_index, PmParamSetId aParamSetId, void data_ptr, int data_nb)
Copies data_nb elements from the space pointed by data_ptr to a ParamSet in frame frame_index.

The ParamSet is identified by aParamSetId in FrameSet aFS.

data_ptr is assumed to point at data of the same type as the ParamSet.

Returns

0 if frame_index is equal to or greater than the number of active frames.

1 if operation is successful.






5.9.3   PmAddFrameData

Synopsis
int PmAddFrameData (PmFrameSet aFS, float time, PmParamSetId *theParamSetIds, void **theDataPtrs, int *theNbOfElems, int nbOfParamSets)
Fills a new frame of data and increments by one the number of active frames of FrameSet aFS.

time is the time to be assigned to the new frame.

Each line of vectors theParamSetIds, theDataPtrs and theNbOfElems correspond to a source data set and its corresponding destination ParamSet in FrameSet aFS.

theParamSetIds is a vector of destination ParamSet identifiers.

ParamSets identified by theParamSetIds should have been created previously. If an identifier in theParamSetIds is not listed among existing ParamSets, the corresponding data set is not transferred.

theDataPtrs is a vector of pointers to the source data sets.

It is assumed that each source data set and its corresponding destination ParamSet have the same variable type.

theNbOfElems is a vector specifying the number of elements of each source data set.

nbOfParamSets is the number of transferred data sets.

Returns

[number of transferred data sets] if operation is successful.

-1 if there is no available memory to perform the operation.






5.9.4   PmGetFrameData

Synopsis
int PmGetFrameData (PmFrameSet aFS, int frame_index, float *ptime, PmParamSetId *theParamSetIds, void **theDataPtrs, int *theNbOfElems, int nbOfParamSets)
Retrieves data from ParamSets in frame number frame_index of FrameSet aFS.

Does not remove frame number frame_index from FrameSet aFS.

The contents of pointer ptime will be filled with the time value of frame number frame_index.

If ptime is NULL, no time value is transferred.

Each line of vectors theParamSetIds, theDataPtrs and theNbOfElems correspond to a destination data set and its corresponding source ParamSet in FrameSet aFS.

theParamSetIds is a vector of source ParamSet identifiers.

If an identifier in theParamSetIds is not listed among existing ParamSets, the corresponding transfer is skipped.

theDataPtrs is a vector of pointers to the destination data sets.

It is assumed that each destination data set and its corresponding source ParamSet have the same variable type.

theNbOfElems is a vector specifying the length of each destination data set.

The number of transferred data is limited to the destination data set length if this one is shorter than the corresponding ParamSet.

Otherwise, the entire ParamSet is copied.

nbOfParamSets is the number of transferred ParamSets.

Returns

[number of transferred ParamSets] if operation is successful.

0 if frame_index is equal to or greater than the number of active frames in FrameSet aFS.


5.10   FrameSet Editing






5.10.1   PmCutFrameSet

Synopsis
PmFrameSet PmCutFrameSet (PmFrameSet aFS, float tInf, float tSup)
Removes the set of frames in the interval [tInf;tSup], and connects the extremities of the remaining portions of FrameSet aFS.

Returns a new FrameSet which contains the removed set of frames.

NULL if there is no frame in the interval [tInf;tSup], or if there is no available memory to perform the operation.






5.10.2   PmInsertFrameSet

Synopsis
void PmInsertFrameSet (PmFrameSet aFS, PmFrameSet insFS, float tIns)
Inserts FrameSet insFS at time tIns of FrameSet aFS.

Returns

1 if insertion is successful.

0 if insertion time tIns is outside the definition interval of FrameSet aFS.

-1 if there is no available memory to perform the operation.






5.10.3   PmCopyFrameSet

Synopsis
PmFrameSet PmCopyFrameSet (PmFrameSet aFS, float tInf, float tSup)
Copies the set of frames in the interval [tInf;tSup] of FrameSet aFS.

Returns a new FrameSet which contains the copied set of frames.

NULL if there is no frame in the interval [tInf;tSup], or if there is no available memory to perform the operation.






5.10.4   PmShiftFrameSet

Synopsis
int PmShiftFrameSet (PmFrameSet aFS, int nb_of_frames)
Shifts to the left nb_of_frames frames of FrameSet aFS.

nb_of_frames is automatically limited to the number of active frames of FrameSet aFS.






5.10.5   PmReverseFrameSet

Synopsis
void PmReverseFrameSet (PmFrameSet aFS, float tInf, float tSup)
Reverses the set of frames in the interval [tInf;tSup] of FrameSet aFS.


5.11   PartialSet Processing at FrameSet Level






5.11.1   PmFadeHarmEnds

Synopsis
int PmFadeHarmEnds (PmFrameSet aFS, PmParamSetId aParamSetId, float tAttack, float tRelease, int input_flag)
Smooth trajectories of partials in ParamSet aParamSetId of FrameSet aFS.

Amplitude fading is made at trajectory birth and death ends.

Frequency in the fading portion is kept constant at the corresponding end value.

tAttack: fade in duration.

tRelease: fade out duration.

For amplitude fading to be performed, a partial must remain dead for a time of at least (tRelease + tAttack). Otherwise amplitude and frequency linear interpolation is done in between death and birth ends.

It is assumed that a given index identifies always the same partial trajectory all along FrameSet aFS.

This is always the case when partials are harmonic.

Instead, for inharmonic partials, a partial with index i which dies at time t may have no relation at all with another partial with same index i which is born at a future time t+dt. If dt < (tAttack + tRelease), PmFadeHarmEnds will join the two independent partials by interpolation in between death and birth ends.

Returns

A minimum duration of (tRelease + tAttack + tRelease) is required for FrameSet aFS. As time step between frames may be variable, the number of frames required to satisfy this condition may be variable too.

While FrameSet aFS is too short, PmFadeHarmEnds does nothing and returns 0, waiting for a longer FrameSet.

If FrameSet aFS is long enough, PmFadeHarmEnds performs smoothing and returns a positive integer, equal to the number of processed frames that can be shifted out of FrameSet aFS using PmShiftFrameSet.

If input_flag is set to 0, PmFadeHarmEnds does not expect for new frames to be added to FrameSet aFS and finishes smoothing regardless of the FrameSet duration.

PmFadeHarmEnds returns -1 if aParamSetId does not correspond to a ParamSet of type PM_PARTIAL or if there is no available memory to perform the operation.






5.11.2   PmScaleFrameSetTime

Synopsis
PmFrameSet PmScaleFrameSetTime (PmFrameSet aFS, PmBreakPoint aBP)
Scales time of FrameSet aFS according to a breakpoint function aBP specifying output time versus input time.

Returns a new scaled FrameSet.

NULL if there is no available memory to perform the operation.




6   Programs




6.1   pmconvert, formattosdif, fmttosdif, sdiftoformat, sdiftofmt, formattofmt, fmttoformat, picstosdif, picsbintosdif

The pmconvert program converts partial data between the formats ascii (.format), binary (.fmt), and SDIF (.sdif).

Synopsis
usage: pmconvert [options] [infile [outfile]]

pmconvert converts between files with partials (.format, .fmt, .sdif),
peaks (.pics), and break-point functions (.f0).
Files can be '-' for standard input/output.

options:
        -q      work quietly
        -R <sr> sampling rate for peaks conversion
        -h      this help
When called as pmconvert, the input and output files must be given, and their types are inferred from the extensions. I.e. you cannot use standard input/output.

The programs formattosdif, fmttosdif, sdiftoformat, sdiftofmt, formattofmt, fmttoformat, picstosdif, picsbintosdif are copies of pmconvert, which take the input and output file types from their name. Here, you can use standard input/output.

Note that you can use gzip-compressed files (.gz) as input/output, which are automatically decompressed/compressed.




6.2   The pm Parser

...performs additive analysis/synthesis

Synopsis
pm [options...] [output file]

Options:
-v <Verbose>
-S <Input FileName>          (.fft or .format)
-P <Fundamuntal FileName>    (.F0)
-A <Action>                  (par:PartialFollow, syn:Synthesis)
-O <Partial Type>            (a:ASCII, b:Binary, s:SDIF)
-q <Number Of Partials>      (all by default)
-M <Window Analysis Size>    (nbSamples)
-N <Window FFT Size>         (nbSamples)
-I <Window Analysis Step>    (nbSamples)
-W <Analysis Type>
-p <Synthesis With Phase>
-R <Sampling Rate>           (nbSamples/s)
-B <Begin>                   (time)
-E <End>                     (time)
-c <Bandwidth Partial Seeve> (coeff 0<k<1)
-a <Envelopp Attack>         (time)
-r <Envelopp Release>        (time)


*
Documentation formatted and converted to HTML by Diemo Schwarz (schwarz@ircam.fr)

Formatted and maintained by Diemo Schwarz --- last change
This document was translated from LATEX by HEVEA.