#ifndef INCLUDE_LORIS_H
#define INCLUDE_LORIS_H
/*
* This is the Loris C++ Class Library, implementing analysis,
* manipulation, and synthesis of digitized sounds using the Reassigned
* Bandwidth-Enhanced Additive Sound Model.
*
* Loris is Copyright (c) 1999-2010 by Kelly Fitz and Lippold Haken
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY, without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*
* loris.h
*
* Header specifying C-linkable procedural interface for Loris.
*
* Main components of this interface:
* - version identification symbols
* - type declarations
* - Analyzer configuration
* - LinearEnvelope (formerly BreakpointEnvelope) operations
* - PartialList operations
* - Partial operations
* - Breakpoint operations
* - sound modeling functions for preparing PartialLists
* - utility functions for manipulating PartialLists
* - notification and exception handlers (all exceptions must be caught and
* handled internally, clients can specify an exception handler and
* a notification function. The default one in Loris uses printf()).
*
* loris.h is generated automatically from loris.h.in. Do not modify loris.h
*
* Kelly Fitz, 4 Feb 2002
* loris@cerlsoundgroup.org
*
* http://www.cerlsoundgroup.org/Loris/
*
*/
/* ---------------------------------------------------------------- */
/* Version
/*
/* Define symbols that facilitate version/release identification.
*/
#define LORIS_MAJOR_VERSION 1
#define LORIS_MINOR_VERSION 8
#define LORIS_SUBMINOR_VERSION
#define LORIS_VERSION_STR "Loris 1.8"
/* ---------------------------------------------------------------- */
/* Types
/*
/* The (class) types Breakpoint, LinearEnvelope, Partial,
and PartialList are imported from the Loris namespace.
The first three are classes, the latter is a typedef
for std::list< Loris::Partial >.
*/
#if defined(__cplusplus)
// include std library list header, declaring templates
// is too painful and fragile:
#include <list>
// declare Loris classes in Loris namespace:
namespace Loris
{
class Breakpoint;
class LinearEnvelope;
class Partial;
// this typedef has to be copied from PartialList.h
typedef std::list< Loris::Partial > PartialList;
}
// import those names into the global namespace
using Loris::Breakpoint;
using Loris::LinearEnvelope;
using Loris::Partial;
using Loris::PartialList;
#else
/* no classes, just declare types and use
opaque C pointers
*/
typedef struct Breakpoint Breakpoint;
typedef struct LinearEnvelope LinearEnvelope;
typedef struct PartialList PartialList;
typedef struct Partial Partial;
#endif
/*
TODO
Maybe should also have loris_label_t and loris_size_t
defined, depending on configure.
*/
#if defined(__cplusplus)
extern "C" {
#endif
/* ---------------------------------------------------------------- */
/* Analyzer configuration
/*
/* An Analyzer represents a configuration of parameters for
performing Reassigned Bandwidth-Enhanced Additive Analysis
of sampled waveforms. This analysis process yields a collection
of Partials, each having a trio of synchronous, non-uniformly-
sampled breakpoint envelopes representing the time-varying
frequency, amplitude, and noisiness of a single bandwidth-
enhanced sinusoid.
For more information about Reassigned Bandwidth-Enhanced
Analysis and the Reassigned Bandwidth-Enhanced Additive Sound
Model, refer to the Loris website: www.cerlsoundgroup.org/Loris/.
In the procedural interface, there is only one Analyzer.
It must be configured by calling analyzer_configure before
any of the other analyzer operations can be performed.
*/
void analyze( const double * buffer, unsigned int bufferSize,
double srate, PartialList * partials );
/* Analyze an array of bufferSize (mono) samples at the given sample rate
(in Hz) and append the extracted Partials to the given
PartialList.
*/
void analyzer_configure( double resolution, double windowWidth );
/* Configure the sole Analyzer instance with the specified
frequency resolution (minimum instantaneous frequency
difference between Partials). All other Analyzer parameters
are computed from the specified frequency resolution.
Construct the Analyzer instance if necessary.
In the procedural interface, there is only one Analyzer.
It must be configured by calling analyzer_configure before
any of the other analyzer operations can be performed.
*/
double analyzer_getAmpFloor( void );
/* Return the amplitude floor (lowest detected spectral amplitude),
in (negative) dB, for the Loris Analyzer.
*/
double analyzer_getCropTime( void );
/* Return the crop time (maximum temporal displacement of a time-
frequency data point from the time-domain center of the analysis
window, beyond which data points are considered "unreliable")
for the Loris Analyzer.
*/
double analyzer_getFreqDrift( void );
/* Return the maximum allowable frequency difference between
consecutive Breakpoints in a Partial envelope for the Loris Analyzer.
*/
double analyzer_getFreqFloor( void );
/* Return the frequency floor (minimum instantaneous Partial
frequency), in Hz, for the Loris Analyzer.
*/
double analyzer_getFreqResolution( void );
/* Return the frequency resolution (minimum instantaneous frequency
difference between Partials) for the Loris Analyzer.
*/
double analyzer_getHopTime( void );
/* Return the hop time (which corresponds approximately to the
average density of Partial envelope Breakpoint data) for this
Analyzer.
*/
double analyzer_getSidelobeLevel( void );
/* Return the sidelobe attenutation level for the Kaiser analysis window in
positive dB. Higher numbers (e.g. 90) give very good sidelobe
rejection but cause the window to be longer in time. Smaller
numbers raise the level of the sidelobes, increasing the likelihood
of frequency-domain interference, but allow the window to be shorter
in time.
*/
double analyzer_getWindowWidth( void );
/* Return the frequency-domain main lobe width (measured between
zero-crossings) of the analysis window used by the Loris Analyzer.
*/
void analyzer_setAmpFloor( double x );
/* Set the amplitude floor (lowest detected spectral amplitude), in
(negative) dB, for the Loris Analyzer.
*/
void analyzer_setBwRegionWidth( double x );
/* Deprecated, use analyzer_storeResidueBandwidth instead.
*/
void analyzer_setCropTime( double x );
/* Set the crop time (maximum temporal displacement of a time-
frequency data point from the time-domain center of the analysis
window, beyond which data points are considered "unreliable")
for the Loris Analyzer.
*/
void analyzer_setFreqDrift( double x );
/* Set the maximum allowable frequency difference between
consecutive Breakpoints in a Partial envelope for the Loris Analyzer.
*/
void analyzer_setFreqFloor( double x );
/* Set the amplitude floor (minimum instantaneous Partial
frequency), in Hz, for the Loris Analyzer.
*/
void analyzer_setFreqResolution( double x );
/* Set the frequency resolution (minimum instantaneous frequency
difference between Partials) for the Loris Analyzer. (Does not cause
other parameters to be recomputed.)
*/
void analyzer_setHopTime( double x );
/* Set the hop time (which corresponds approximately to the average
density of Partial envelope Breakpoint data) for the Loris Analyzer.
*/
void analyzer_setSidelobeLevel( double x );
/* Set the sidelobe attenutation level for the Kaiser analysis window in
positive dB. Larger numbers (e.g. 90) give very good sidelobe
rejection but cause the window to be longer in time. Smaller
numbers raise the level of the sidelobes, increasing the likelihood
of frequency-domain interference, but allow the window to be shorter
in time.
*/
void analyzer_setWindowWidth( double x );
/* Set the frequency-domain main lobe width (measured between
zero-crossings) of the analysis window used by the Loris Analyzer.
*/
void analyzer_storeResidueBandwidth( double regionWidth );
/* Construct Partial bandwidth envelopes during analysis
by associating residual energy in the spectrum (after
peak extraction) with the selected spectral peaks that
are used to construct Partials.
regionWidth is the width (in Hz) of the bandwidth
association regions used by this process, must be positive.
*/
void analyzer_storeConvergenceBandwidth( double tolerancePct );
/* Construct Partial bandwidth envelopes during analysis
by storing the mixed derivative of short-time phase,
scaled and shifted so that a value of 0 corresponds
to a pure sinusoid, and a value of 1 corresponds to a
bandwidth-enhanced sinusoid with maximal energy spread
(minimum sinusoidal convergence).
tolerance is the amount of range over which the
mixed derivative indicator should be allowed to drift away
from a pure sinusoid before saturating. This range is mapped
to bandwidth values on the range [0,1]. Must be positive and
not greater than 1.
*/
void analyzer_storeNoBandwidth( void );
/* Disable bandwidth envelope construction. Bandwidth
will be zero for all Breakpoints in all Partials.
*/
double analyzer_getBwRegionWidth( void );
/* Return the width (in Hz) of the Bandwidth Association regions
used by this Analyzer, only if the spectral residue method is
used to compute bandwidth envelopes. Return zero if the mixed
derivative method is used, or if no bandwidth is computed.
*/
double analyzer_getBwConvergenceTolerance( void );
/* Return the mixed derivative convergence tolerance
only if the convergence indicator is used to compute
bandwidth envelopes. Return zero if the spectral residue
method is used or if no bandwidth is computed.
*/
/* ---------------------------------------------------------------- */
/* LinearEnvelope object interface
/*
/* A LinearEnvelope represents a linear segment breakpoint
function with infinite extension at each end (that is, the
values past either end of the breakpoint function have the
values at the nearest end).
In C++, a LinearEnvelope is a Loris::LinearEnvelope.
*/
LinearEnvelope * createLinearEnvelope( void );
/* Construct and return a new LinearEnvelope having no
breakpoints and an implicit value of 0. everywhere,
until the first breakpoint is inserted.
*/
LinearEnvelope * copyLinearEnvelope( const LinearEnvelope * ptr_this );
/* Construct and return a new LinearEnvelope that is an
exact copy of the specified LinearEnvelopes, having
an identical set of breakpoints.
*/
void destroyLinearEnvelope( LinearEnvelope * ptr_this );
/* Destroy this LinearEnvelope.
*/
void linearEnvelope_insertBreakpoint( LinearEnvelope * ptr_this,
double time, double val );
/* Insert a breakpoint representing the specified (time, value)
pair into this LinearEnvelope. If there is already a
breakpoint at the specified time, it will be replaced with
the new breakpoint.
*/
double linearEnvelope_valueAt( const LinearEnvelope * ptr_this,
double time );
/* Return the interpolated value of this LinearEnvelope at the
specified time.
*/
/* ---------------------------------------------------------------- */
/* PartialList object interface
/*
/* A PartialList represents a collection of Bandwidth-Enhanced
Partials, each having a trio of synchronous, non-uniformly-
sampled breakpoint envelopes representing the time-varying
frequency, amplitude, and noisiness of a single bandwidth-
enhanced sinusoid.
For more information about Bandwidth-Enhanced Partials and the
Reassigned Bandwidth-Enhanced Additive Sound Model, refer to
the Loris website: www.cerlsoundgroup.org/Loris/.
In C++, a PartialList is a Loris::PartialList.
*/
PartialList * createPartialList( void );
/* Return a new empty PartialList.
*/
void destroyPartialList( PartialList * ptr_this );
/* Destroy this PartialList.
*/
void partialList_clear( PartialList * ptr_this );
/* Remove (and destroy) all the Partials from this PartialList,
leaving it empty.
*/
void partialList_copy( PartialList * ptr_this,
const PartialList * src );
/* Make this PartialList a copy of the source PartialList by making
copies of all of the Partials in the source and adding them to
this PartialList.
*/
unsigned long partialList_size( const PartialList * ptr_this );
/* Return the number of Partials in this PartialList.
*/
void partialList_splice( PartialList * ptr_this,
PartialList * src );
/* Splice all the Partials in the source PartialList onto the end of
this PartialList, leaving the source empty.
*/
/* ---------------------------------------------------------------- */
/* Partial object interface
/*
/* A Partial represents a single component in the
reassigned bandwidth-enhanced additive model. A Partial consists of a
chain of Breakpoints describing the time-varying frequency, amplitude,
and bandwidth (or noisiness) envelopes of the component, and a 4-byte
label. The Breakpoints are non-uniformly distributed in time. For more
information about Reassigned Bandwidth-Enhanced Analysis and the
Reassigned Bandwidth-Enhanced Additive Sound Model, refer to the Loris
website: www.cerlsoundgroup.org/Loris/.
*/
double partial_startTime( const Partial * p );
/* Return the start time (seconds) for the specified Partial.
*/
double partial_endTime( const Partial * p );
/* Return the end time (seconds) for the specified Partial.
*/
double partial_duration( const Partial * p );
/* Return the duration (seconds) for the specified Partial.
*/
double partial_initialPhase( const Partial * p );
/* Return the initial phase (radians) for the specified Partial.
*/
int partial_label( const Partial * p );
/* Return the integer label for the specified Partial.
*/
unsigned long partial_numBreakpoints( const Partial * p );
/* Return the number of Breakpoints in the specified Partial.
*/
double partial_frequencyAt( const Partial * p, double t );
/* Return the frequency (Hz) of the specified Partial interpolated
at a particular time. It is an error to apply this function to
a Partial having no Breakpoints.
*/
double partial_bandwidthAt( const Partial * p, double t );
/* Return the bandwidth of the specified Partial interpolated
at a particular time. It is an error to apply this function to
a Partial having no Breakpoints.
*/
double partial_phaseAt( const Partial * p, double t );
/* Return the phase (radians) of the specified Partial interpolated
at a particular time. It is an error to apply this function to
a Partial having no Breakpoints.
*/
double partial_amplitudeAt( const Partial * p, double t );
/* Return the (absolute) amplitude of the specified Partial interpolated
at a particular time. Partials are assumed to fade out
over 1 millisecond at the ends (rather than instantaneously).
It is an error to apply this function to a Partial having no Breakpoints.
*/
void partial_setLabel( Partial * p, int label );
/* Assign a new integer label to the specified Partial.
*/
/* ---------------------------------------------------------------- */
/* Breakpoint object interface
/*
/* A Breakpoint represents a single breakpoint in the
Partial parameter (frequency, amplitude, bandwidth) envelope.
Instantaneous phase is also stored, but is only used at the onset of
a partial, or when it makes a transition from zero to nonzero amplitude.
Loris Partials represent reassigned bandwidth-enhanced model components.
A Partial consists of a chain of Breakpoints describing the time-varying
frequency, amplitude, and bandwidth (noisiness) of the component.
For more information about Reassigned Bandwidth-Enhanced
Analysis and the Reassigned Bandwidth-Enhanced Additive Sound
Model, refer to the Loris website:
www.cerlsoundgroup.org/Loris/.
*/
double breakpoint_getAmplitude( const Breakpoint * bp );
/* Return the (absolute) amplitude of the specified Breakpoint.
*/
double breakpoint_getBandwidth( const Breakpoint * bp );
/* Return the bandwidth coefficient of the specified Breakpoint.
*/
double breakpoint_getFrequency( const Breakpoint * bp );
/* Return the frequency (Hz) of the specified Breakpoint.
*/
double breakpoint_getPhase( const Breakpoint * bp );
/* Return the phase (radians) of the specified Breakpoint.
*/
void breakpoint_setAmplitude( Breakpoint * bp, double a );
/* Assign a new (absolute) amplitude to the specified Breakpoint.
*/
void breakpoint_setBandwidth( Breakpoint * bp, double bw );
/* Assign a new bandwidth coefficient to the specified Breakpoint.
*/
void breakpoint_setFrequency( Breakpoint * bp, double f );
/* Assign a new frequency (Hz) to the specified Breakpoint.
*/
void breakpoint_setPhase( Breakpoint * bp, double phi );
/* Assign a new phase (radians) to the specified Breakpoint.
*/
/* ---------------------------------------------------------------- */
/* non-object-based procedures
/*
/* Operations in Loris that need not be accessed though object
interfaces are represented as simple functions.
*/
void channelize( PartialList * partials,
LinearEnvelope * refFreqEnvelope, int refLabel );
/* Label Partials in a PartialList with the integer nearest to
the amplitude-weighted average ratio of their frequency envelope
to a reference frequency envelope. The frequency spectrum is
partitioned into non-overlapping channels whose time-varying
center frequencies track the reference frequency envelope.
The reference label indicates which channel's center frequency
is exactly equal to the reference envelope frequency, and other
channels' center frequencies are multiples of the reference
envelope frequency divided by the reference label. Each Partial
in the PartialList is labeled with the number of the channel
that best fits its frequency envelope. The quality of the fit
is evaluated at the breakpoints in the Partial envelope and
weighted by the amplitude at each breakpoint, so that high-
amplitude breakpoints contribute more to the channel decision.
Partials are labeled, but otherwise unmodified. In particular,
their frequencies are not modified in any way.
*/
void collate( PartialList * partials );
/* Collate unlabeled (zero-labeled) Partials into the smallest-possible
number of Partials that does not combine any overlapping Partials.
Collated Partials appear at the end of the sequence, after all
labeled Partials.
*/
LinearEnvelope *
createFreqReference( PartialList * partials,
double minFreq, double maxFreq, long numSamps );
/* Return a newly-constructed LinearEnvelope using the legacy
FrequencyReference class. The envelope will have approximately
the specified number of samples. The specified number of samples
must be greater than 1. Uses the FundamentalEstimator
(FundamentalFromPartials) class to construct an estimator of
fundamental frequency, configured to emulate the behavior of
the FrequencyReference class in Loris 1.4-1.5.2. If numSamps
is zero, construct the reference envelope from fundamental
estimates taken every five milliseconds.
For simple sounds, this frequency reference may be a
good first approximation to a reference envelope for
channelization (see channelize()).
Clients are responsible for disposing of the newly-constructed
LinearEnvelope.
*/
LinearEnvelope *
createF0Estimate( PartialList * partials, double minFreq, double maxFreq,
double interval );
/* Return a newly-constructed LinearEnvelope that estimates
the time-varying fundamental frequency of the sound
represented by the Partials in a PartialList. This uses
the FundamentalEstimator (FundamentalFromPartials)
class to construct an estimator of fundamental frequency,
and returns a LinearEnvelope that samples the estimator at the
specified time interval (in seconds). Default values are used
to configure the estimator. Only estimates in the specified
frequency range will be considered valid, estimates outside this
range will be ignored.
Clients are responsible for disposing of the newly-constructed
LinearEnvelope.
*/
void dilate( PartialList * partials,
const double * initial, const double * target, int npts );
/* Dilate Partials in a PartialList according to the given
initial and target time points. Partial envelopes are
stretched and compressed so that temporal features at
the initial time points are aligned with the final time
points. Time points are sorted, so Partial envelopes are
are only stretched and compressed, but breakpoints are not
reordered. Duplicate time points are allowed. There must be
the same number of initial and target time points.
*/
void distill( PartialList * partials );
/* Distill labeled (channelized) Partials in a PartialList into a
PartialList containing at most one Partial per label. Unlabeled
(zero-labeled) Partials are left unmodified at the end of the
distilled Partials.
*/
void exportAiff( const char * path, const double * buffer,
unsigned int bufferSize, double samplerate, int bitsPerSamp );
/* Export mono audio samples stored in an array of size bufferSize to
an AIFF file having the specified sample rate at the given file path
(or name). The floating point samples in the buffer are clamped to the
range (-1.,1.) and converted to integers having bitsPerSamp bits.
*/
void exportSdif( const char * path, PartialList * partials );
/* Export Partials in a PartialList to a SDIF file at the specified
file path (or name). SDIF data is described by RBEM and RBEL
matrices.
For more information about SDIF, see the SDIF web site at:
www.ircam.fr/equipes/analyse-synthese/sdif/
*/
void exportSpc( const char * path, PartialList * partials, double midiPitch,
int enhanced, double endApproachTime );
/* Export Partials in a PartialList to a Spc file at the specified file
path (or name). The fractional MIDI pitch must be specified. The
enhanced parameter defaults to true (for bandwidth-enhanced spc files),
but an be specified false for pure-sines spc files. The endApproachTime
parameter is in seconds. A nonzero endApproachTime indicates that the plist does
not include a release, but rather ends in a static spectrum corresponding
to the final breakpoint values of the partials. The endApproachTime
specifies how long before the end of the sound the amplitude, frequency,
and bandwidth values are to be modified to make a gradual transition to
the static spectrum.
*/
/* Apply a reference Partial to fix the frequencies of Breakpoints
whose amplitude is below threshold_dB. 0 harmonifies full-amplitude
Partials, to apply only to quiet Partials, specify a lower
threshold like -90). The reference Partial is the first Partial
in the PartialList labeled refLabel (usually 1). The LinearEnvelope
is a time-varying weighting on the harmonifing process. When 1,
harmonic frequencies are used, when 0, breakpoint frequencies are
unmodified.
*/
void harmonify( PartialList * partials, long refLabel,
const LinearEnvelope * env, double threshold_dB );
unsigned int importAiff( const char * path, double * buffer, unsigned int bufferSize,
double * samplerate );
/* Import audio samples stored in an AIFF file at the given file
path (or name). The samples are converted to floating point
values on the range (-1.,1.) and stored in an array of doubles.
The value returned is the number of samples in buffer, and it is at
most bufferSize. If samplerate is not a NULL pointer,
then, on return, it points to the value of the sample rate (in
Hz) of the AIFF samples. The AIFF file must contain only a single
channel of audio data. The prior contents of buffer, if any, are
overwritten.
*/
void importSdif( const char * path, PartialList * partials );
/* Import Partials from an SDIF file at the given file path (or
name), and append them to a PartialList.
*/
void importSpc( const char * path, PartialList * partials );
/* Import Partials from an Spc file at the given file path (or
name), and return them in a PartialList.
*/
void morph( const PartialList * src0, const PartialList * src1,
const LinearEnvelope * ffreq,
const LinearEnvelope * famp,
const LinearEnvelope * fbw,
PartialList * dst );
/* Morph labeled Partials in two PartialLists according to the
given frequency, amplitude, and bandwidth (noisiness) morphing
envelopes, and append the morphed Partials to the destination
PartialList. Loris morphs Partials by interpolating frequency,
amplitude, and bandwidth envelopes of corresponding Partials in
the source PartialLists. For more information about the Loris
morphing algorithm, see the Loris website:
www.cerlsoundgroup.org/Loris/
*/
void morphWithReference( const PartialList * src0,
const PartialList * src1,
long src0RefLabel,
long src1RefLabel,
const LinearEnvelope * ffreq,
const LinearEnvelope * famp,
const LinearEnvelope * fbw,
PartialList * dst );
/* Morph labeled Partials in two PartialLists according to the
given frequency, amplitude, and bandwidth (noisiness) morphing
envelopes, and append the morphed Partials to the destination
PartialList. Specify the labels of the Partials to be used as
reference Partial for the two morph sources. The reference
partial is used to compute frequencies for very low-amplitude
Partials whose frequency estimates are not considered reliable.
The reference Partial is considered to have good frequency
estimates throughout. A reference label of 0 indicates that
no reference Partial should be used for the corresponding
morph source.
Loris morphs Partials by interpolating frequency,
amplitude, and bandwidth envelopes of corresponding Partials in
the source PartialLists. For more information about the Loris
morphing algorithm, see the Loris website:
www.cerlsoundgroup.org/Loris/
*/
void morpher_setAmplitudeShape( double shape );
/* Set the shaping parameter for the amplitude morphing
function. This shaping parameter controls the slope of
the amplitude morphing function, for values greater than
1, this function gets nearly linear (like the old
amplitude morphing function), for values much less than
1 (e.g. 1E-5) the slope is gently curved and sounds
pretty "linear", for very small values (e.g. 1E-12) the
curve is very steep and sounds un-natural because of the
huge jump from zero amplitude to very small amplitude.
Use LORIS_DEFAULT_AMPMORPHSHAPE to obtain the default
amplitude morphing shape for Loris, (equal to 1E-5,
which works well for many musical instrument morphs,
unless Loris was compiled with the symbol
LINEAR_AMP_MORPHS defined, in which case
LORIS_DEFAULT_AMPMORPHSHAPE is equal to
LORIS_LINEAR_AMPMORPHSHAPE).
Use LORIS_LINEAR_AMPMORPHSHAPE to approximate the linear
amplitude morphs performed by older versions of Loris.
The amplitude shape must be positive.
*/
extern const double LORIS_DEFAULT_AMPMORPHSHAPE;
extern const double LORIS_LINEAR_AMPMORPHSHAPE;
void resample( PartialList * partials, double interval );
/* Resample all Partials in a PartialList using the specified
sampling interval, so that the Breakpoints in the Partial
envelopes will all lie on a common temporal grid.
The Breakpoint times in resampled Partials will comprise a
contiguous sequence of integer multiples of the sampling interval,
beginning with the multiple nearest to the Partial's start time and
ending with the multiple nearest to the Partial's end time. Resampling
is performed in-place.
*/
void shapeSpectrum( PartialList * partials, PartialList * surface,
double stretchFreq, double stretchTime );
/* Scale the amplitudes of a set of Partials by applying
a spectral suface constructed from another set.
Stretch the spectral surface in time and frequency
using the specified stretch factors. Set the stretch
factors to one for no stretching.
*/
void sift( PartialList * partials );
/* Identify overlapping Partials having the same (nonzero)
label. If any two partials with same label
overlap in time, set the label of the weaker
(having less total energy) partial to zero.
*/
unsigned int
synthesize( const PartialList * partials,
double * buffer, unsigned int bufferSize,
double srate );
/* Synthesize Partials in a PartialList at the given sample
rate, and store the (floating point) samples in a buffer of
size bufferSize. The buffer is neither resized nor
cleared before synthesis, so newly synthesized samples are
added to any previously computed samples in the buffer, and
samples beyond the end of the buffer are lost. Return the
number of samples synthesized, that is, the index of the
latest sample in the buffer that was modified.
*/
/* ---------------------------------------------------------------- */
/* utility functions
/*
/* Operations for transforming and manipulating collections
of Partials.
*/
double avgAmplitude( const Partial * p );
/* Return the average amplitude over all Breakpoints in this Partial.
Return zero if the Partial has no Breakpoints.
*/
double avgFrequency( const Partial * p );
/* Return the average frequency over all Breakpoints in this Partial.
Return zero if the Partial has no Breakpoints.
*/
void copyIf( const PartialList * src, PartialList * dst,
int ( * predicate )( const Partial * p, void * data ),
void * data );
/* Append copies of Partials in the source PartialList satisfying the
specified predicate to the destination PartialList. The source list
is unmodified. The data parameter can be used to
supply extra user-defined data to the function. Pass 0 if no
additional data is needed.
*/
void copyLabeled( const PartialList * src, long label, PartialList * dst );
/* Append copies of Partials in the source PartialList having the
specified label to the destination PartialList. The source list
is unmodified.
*/
void crop( PartialList * partials, double t1, double t2 );
/* Trim Partials by removing Breakpoints outside a specified time span.
Insert a Breakpoint at the boundary when cropping occurs. Remove
any Partials that are left empty after cropping (Partials having no
Breakpoints between t1 and t2).
*/
void extractIf( PartialList * src, PartialList * dst,
int ( * predicate )( const Partial * p, void * data ),
void * data );
/* Remove Partials in the source PartialList satisfying the
specified predicate from the source list and append them to
the destination PartialList. The data parameter can be used to
supply extra user-defined data to the function. Pass 0 if no
additional data is needed.
*/
void extractLabeled( PartialList * src, long label, PartialList * dst );
/* Remove Partials in the source PartialList having the specified
label from the source list and append them to the destination
PartialList.
*/
void fixPhaseAfter( PartialList * partials, double time );
/* Recompute phases of all Breakpoints later than the specified
time so that the synthesized phases of those later Breakpoints
matches the stored phase, as long as the synthesized phase at
the specified time matches the stored (not recomputed) phase.
Phase fixing is only applied to non-null (nonzero-amplitude)
Breakpoints, because null Breakpoints are interpreted as phase
reset points in Loris. If a null is encountered, its phase is
corrected from its non-Null successor, if it has one, otherwise
it is unmodified.
*/
void fixPhaseAt( PartialList * partials, double time );
/* Recompute phases of all Breakpoints in a Partial
so that the synthesized phases match the stored phases,
and the synthesized phase at (nearest) the specified
time matches the stored (not recomputed) phase.
Backward phase-fixing stops if a null (zero-amplitude)
Breakpoint is encountered, because nulls are interpreted as
phase reset points in Loris. If a null is encountered, the
remainder of the Partial (the front part) is fixed in the
forward direction, beginning at the start of the Partial.
Forward phase fixing is only applied to non-null
(nonzero-amplitude) Breakpoints. If a null is encountered,
its phase is corrected from its non-Null successor, if
it has one, otherwise it is unmodified.
*/
void fixPhaseBefore( PartialList * partials, double time );
/* Recompute phases of all Breakpoints earlier than the specified
time so that the synthesized phases of those earlier Breakpoints
matches the stored phase, and the synthesized phase at the
specified time matches the stored (not recomputed) phase.
Backward phase-fixing stops if a null (zero-amplitude) Breakpoint
is encountered, because nulls are interpreted as phase reset
points in Loris. If a null is encountered, the remainder of the
Partial (the front part) is fixed in the forward direction,
beginning at the start of the Partial.
*/
void fixPhaseBetween( PartialList * partials, double tbeg, double tend );
/*
Fix the phase travel between two times by adjusting the
frequency and phase of Breakpoints between those two times.
This algorithm assumes that there is nothing interesting
about the phases of the intervening Breakpoints, and modifies
their frequencies as little as possible to achieve the correct
amount of phase travel such that the frequencies and phases at
the specified times match the stored values. The phases of all
the Breakpoints between the specified times are recomputed.
*/
void fixPhaseForward( PartialList * partials, double tbeg, double tend );
/* Recompute phases of all Breakpoints later than the specified
time so that the synthesized phases of those later Breakpoints
matches the stored phase, as long as the synthesized phase at
the specified time matches the stored (not recomputed) phase.
Breakpoints later than tend are unmodified.
Phase fixing is only applied to non-null (nonzero-amplitude)
Breakpoints, because null Breakpoints are interpreted as phase
reset points in Loris. If a null is encountered, its phase is
corrected from its non-Null successor, if it has one, otherwise
it is unmodified.
*/
int forEachBreakpoint( Partial * p,
int ( * func )( Breakpoint * p, double time, void * data ),
void * data );
/* Apply a function to each Breakpoint in a Partial. The function
is called once for each Breakpoint in the source Partial. The
function may modify the Breakpoint (but should not otherwise attempt
to modify the Partial). The data parameter can be used to supply extra
user-defined data to the function. Pass 0 if no additional data is needed.
The function should return 0 if successful. If the function returns
a non-zero value, then forEachBreakpoint immediately returns that value
without applying the function to any other Breakpoints in the Partial.
forEachBreakpoint returns zero if all calls to func return zero.
*/
int forEachPartial( PartialList * src,
int ( * func )( Partial * p, void * data ),
void * data );
/* Apply a function to each Partial in a PartialList. The function
is called once for each Partial in the source PartialList. The
function may modify the Partial (but should not attempt to modify
the PartialList). The data parameter can be used to supply extra
user-defined data to the function. Pass 0 if no additional data
is needed. The function should return 0 if successful. If the
function returns a non-zero value, then forEachPartial immediately
returns that value without applying the function to any other
Partials in the PartialList. forEachPartial returns zero if all
calls to func return zero.
*/
double peakAmplitude( const Partial * p );
/* Return the maximum amplitude achieved by a Partial.
*/
void removeIf( PartialList * src,
int ( * predicate )( const Partial * p, void * data ),
void * data );
/* Remove from a PartialList all Partials satisfying the
specified predicate. The data parameter can be used to
supply extra user-defined data to the function. Pass 0 if no
additional data is needed.
*/
void removeLabeled( PartialList * src, long label );
/* Remove from a PartialList all Partials having the specified label.
*/
void scaleAmplitude( PartialList * partials, LinearEnvelope * ampEnv );
/* Scale the amplitude of the Partials in a PartialList according
to an envelope representing a time-varying amplitude scale value.
*/
void scaleAmp( PartialList * partials, LinearEnvelope * ampEnv );
/* Bad old name for scaleAmplitude.
*/
void scaleBandwidth( PartialList * partials, LinearEnvelope * bwEnv );
/* Scale the bandwidth of the Partials in a PartialList according
to an envelope representing a time-varying bandwidth scale value.
*/
void scaleFrequency( PartialList * partials, LinearEnvelope * freqEnv );
/* Scale the frequency of the Partials in a PartialList according
to an envelope representing a time-varying frequency scale value.
*/
void scaleNoiseRatio( PartialList * partials, LinearEnvelope * noiseEnv );
/* Scale the relative noise content of the Partials in a PartialList
according to an envelope representing a (time-varying) noise energy
scale value.
*/
void setBandwidth( PartialList * partials, LinearEnvelope * bwEnv );
/* Set the bandwidth of the Partials in a PartialList according
to an envelope representing a time-varying bandwidth value.
*/
void shiftPitch( PartialList * partials, LinearEnvelope * pitchEnv );
/* Shift the pitch of all Partials in a PartialList according to
the given pitch envelope. The pitch envelope is assumed to have
units of cents (1/100 of a halfstep).
*/
void shiftTime( PartialList * partials, double offset );
/* Shift the time of all the Breakpoints in a Partial by a
constant amount.
*/
void sortByLabel( PartialList * partials );
/* Sort the Partials in a PartialList in order of increasing label.
The sort is stable; Partials having the same label are not
reordered.
*/
void timeSpan( PartialList * partials, double * tmin, double * tmax );
/* Return the minimum start time and maximum end time
in seconds of all Partials in this PartialList. The v
times are returned in the (non-null) pointers tmin
and tmax.
*/
double weightedAvgFrequency( const Partial * p );
/* Return the average frequency over all Breakpoints in this Partial,
weighted by the Breakpoint amplitudes. Return zero if the Partial
has no Breakpoints.
*/
/* ---------------------------------------------------------------- */
/* Notification and exception handlers
/*
/* An exception handler and a notifier may be specified. Both
are functions taking a const char * argument and returning
void.
*/
void setExceptionHandler( void(*f)(const char *) );
/* Specify a function to call when reporting exceptions. The
function takes a const char * argument, and returns void.
*/
void setNotifier( void(*f)(const char *) );
/* Specify a notification function. The function takes a
const char * argument, and returns void.
*/
#if defined(__cplusplus)
} /* extern "C" */
#endif
#endif /* ndef INCLUDE_LORIS_H */