path: root/src/loris/Synthesizer.C

/*
 * 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
 *
 *
 * Synthesizer.C
 *
 * Implementation of class Loris::SynthesizerSynthesizer, a synthesizer of 
 * bandwidth-enhanced Partials.
 *
 * Kelly Fitz, 16 Aug 1999
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */

#if HAVE_CONFIG_H
    #include "config.h"
#endif

#include "Synthesizer.h"
#include "Oscillator.h"
#include "Breakpoint.h"
#include "BreakpointUtils.h"
#include "Envelope.h"
#include "LorisExceptions.h"
#include "Notifier.h"
#include "Partial.h"
#include "Resampler.h"
#include "phasefix.h"

#include <algorithm>
#include <cmath>

#if defined(HAVE_M_PI) && (HAVE_M_PI)
    const double Pi = M_PI;
#else
    const double Pi = 3.14159265358979324;
#endif

//  begin namespace
namespace Loris {


// ---------------------------------------------------------------------------
//  Synthesizer constructor
// ---------------------------------------------------------------------------
//!	Construct a Synthesizer using the default parameters and sample
//!	buffer (a standard library vector). Since Partials generated by the 
//! Loris Analyzer generally begin and end at non-zero amplitude, zero-amplitude
//!	Breakpoints are inserted at either end of the Partial, at a temporal
//!	distance equal to the fade time, to reduce turn-on and turn-off
//!	artifacts.
//!
//! \sa Synthesizer::Parameters
//!
//!	\param	buffer The vector (of doubles) into which rendered samples
//!			   should be accumulated.
//!	\throw	InvalidArgument if any of the parameters is invalid.
Synthesizer::Synthesizer( std::vector<double> & buffer ) :
    m_sampleBuffer( & buffer ),
    m_fadeTimeSec( DefaultParameters().fadeTime ),
    m_srateHz( DefaultParameters().sampleRate )
{
}


// ---------------------------------------------------------------------------
//  Synthesizer constructor
// ---------------------------------------------------------------------------
//!	Construct a Synthesizer using the specified parameters and sample
//!	buffer (a standard library vector). Since Partials generated by the 
//! Loris Analyzer generally begin and end at non-zero amplitude, zero-amplitude
//!	Breakpoints are inserted at either end of the Partial, at a temporal
//!	distance equal to the fade time, to reduce turn-on and turn-off
//!	artifacts. If the fade time is unspecified, the default value of one
//!	millisecond (0.001 seconds) is used.
//!
//!	\param	params A Parameters struct storing the configuration of 
//!             Synthesizer parameters.
//!	\param	buffer The vector (of doubles) into which rendered samples
//!			   should be accumulated.
//!	\throw	InvalidArgument if any of the parameters is invalid.
//
Synthesizer::Synthesizer( Parameters params, std::vector<double> & buffer ) :
    m_sampleBuffer( & buffer )
{
    //  make sure that the parameters are valid before proceeding
    if ( IsValidParameters( params ) )
    {
        m_fadeTimeSec = params.fadeTime;
        m_srateHz = params.sampleRate;
        m_osc.filter() = params.filter;
    }
}

// ---------------------------------------------------------------------------
//  Synthesizer constructor
// ---------------------------------------------------------------------------
//!	Construct a Synthesizer using the specified sampling rate, sample
//!	buffer (a standard library vector), and the default fade time 
//!	stored in the DefaultParameters. Since Partials generated by the Loris 
//!	Analyzer generally begin and end at non-zero amplitude, zero-amplitude
//!	Breakpoints are inserted at either end of the Partial, at a temporal
//!	distance equal to the fade time, to reduce turn-on and turn-off
//!	artifacts.
//!
//!	\param	srate The rate (Hz) at which to synthesize samples
//!			   (must be positive).
//!	\param	buffer The vector (of doubles) into which rendered samples
//!			   should be accumulated.
//!	\throw	InvalidArgument if the specfied sample rate is non-positive.
Synthesizer::Synthesizer( double samplerate, std::vector<double> & buffer ) :
    m_sampleBuffer( & buffer ),
    m_fadeTimeSec( DefaultParameters().fadeTime ),
    m_srateHz( samplerate )
{
    //  check to make sure that the sample rate is valid:
    if ( m_srateHz <= 0. ) 
    {
        Throw( InvalidArgument, "Synthesizer sample rate must be positive." );
    }

    //  assign the default bw enhancement filter to the Oscillator
    m_osc.filter() = DefaultParameters().filter;
    
}

// ---------------------------------------------------------------------------
//  Synthesizer constructor
// ---------------------------------------------------------------------------
//! Construct a Synthesizer using the specified sampling rate, sample
//! buffer (a standard library vector), and Partial
//! fade time (in seconds). Since Partials generated by the Loris Analyzer
//! generally begin and end at non-zero amplitude, zero-amplitude
//! Breakpoints are inserted at either end of the Partial, at a temporal
//! distance equal to the fade time, to reduce turn-on and turn-off
//! artifacts. If the fade time is unspecified, the default value of one
//! millisecond (0.001 seconds) is used.
//!
//! \param  samplerate The rate (Hz) at which to synthesize samples
//!         (must be positive).
//! \param  buffer The vector (of doubles) into which rendered samples
//!         should be accumulated.
//! \param  fade The Partial fade time in seconds (must be non-negative).
//! \throw  InvalidArgument if the specfied sample rate is non-positive.
//! \throw  InvalidArgument if the specified fade time is negative.
Synthesizer::Synthesizer( double samplerate, std::vector<double> & buffer, 
                          double fade ) :
    m_sampleBuffer( & buffer ),
    m_fadeTimeSec( fade ),
    m_srateHz( samplerate )
{
    //  check to make sure that the sample rate is valid:
    if ( m_srateHz <= 0. ) 
    {
        Throw( InvalidArgument, "Synthesizer sample rate must be positive." );
    }

    //  check to make sure that the specified fade time
    //  is valid:
    if ( m_fadeTimeSec < 0. )
    {
        Throw( InvalidArgument, 
               "Synthesizer Partial fade time must be non-negative." );
    }
    
    //  assign the default bw enhancement filter to the Oscillator
    m_osc.filter() = DefaultParameters().filter;
    
}

//	-- synthesis --

// ---------------------------------------------------------------------------
//  synthesize
// ---------------------------------------------------------------------------
//! Synthesize a bandwidth-enhanced sinusoidal Partial. Zero-amplitude
//! Breakpoints are inserted at either end of the Partial to reduce
//! turn-on and turn-off artifacts, as described above. The synthesizer
//! will resize the buffer as necessary to accommodate all the samples,
//! including the fade out. Previous contents of the buffer are not
//! overwritten. Partials with start times earlier than the Partial fade
//! time will have shorter onset fades. Partials are not rendered at
//! frequencies above the half-sample rate. 
//!
//! \param  p The Partial to synthesize.
//! \return Nothing.
//! \pre    The partial must have non-negative start time.
//! \post   This Synthesizer's sample buffer (vector) has been 
//!         resized to accommodate the entire duration of the 
//!         Partial, p, including fade out at the end.
//! \throw  InvalidPartial if the Partial has negative start time.
//  
void
Synthesizer::synthesize( Partial p ) 
{
    if ( p.numBreakpoints() == 0 )
    {
        debugger << "Synthesizer ignoring a partial that contains no Breakpoints" << endl;
        return;
    }
    
    if ( p.startTime() < 0 )
    {
        Throw( InvalidPartial, "Tried to synthesize a Partial having start time less than 0." );
    }

    debugger << "synthesizing Partial from " << p.startTime() * m_srateHz 
             << " to " << p.endTime() * m_srateHz << " starting phase "
             << p.initialPhase() << " starting frequency " 
             << p.first().frequency() << endl;
             
    //  better to compute this only once:
    const double OneOverSrate = 1. / m_srateHz;
    
             
    //  use a Resampler to quantize the Breakpoint times and 
    //  correct the phases:
    Resampler quantizer( OneOverSrate );
    quantizer.setPhaseCorrect( true );
    quantizer.quantize( p );
    

    //  resize the sample buffer if necessary:
    typedef unsigned long index_type;
    index_type endSamp = index_type( ( p.endTime() + m_fadeTimeSec ) * m_srateHz );
    if ( endSamp+1 > m_sampleBuffer->size() )
    {
        //  pad by one sample:
        m_sampleBuffer->resize( endSamp+1 );
    }
    
    //  compute the starting time for synthesis of this Partial,
    //  m_fadeTimeSec before the Partial's startTime, but not before 0:
    double itime = ( m_fadeTimeSec < p.startTime() ) ? ( p.startTime() - m_fadeTimeSec ) : 0.;
    index_type currentSamp = index_type( (itime * m_srateHz) + 0.5 );   //  cheap rounding
    
    //  reset the oscillator:
    //  all that really needs to happen here is setting the frequency
    //  correctly, the phase will be reset again in the loop over 
    //  Breakpoints below, and the amp and bw can start at 0.
    m_osc.resetEnvelopes( BreakpointUtils::makeNullBefore( p.first(), p.startTime() - itime ), m_srateHz );

    //  cache the previous frequency (in Hz) so that it
    //  can be used to reset the phase when necessary
    //  in the sample computation loop below (this saves
    //  having to recompute from the oscillator's radian
    //  frequency):
    double prevFrequency = p.first().frequency();   
    
    //  synthesize linear-frequency segments until 
    //  there aren't any more Breakpoints to make segments:
    double * bufferBegin = &( m_sampleBuffer->front() );
    for ( Partial::const_iterator it = p.begin(); it != p.end(); ++it )
    {
        index_type tgtSamp = index_type( (it.time() * m_srateHz) + 0.5 );   //  cheap rounding
        Assert( tgtSamp >= currentSamp );
        
        //  if the current oscillator amplitude is
        //  zero, and the target Breakpoint amplitude
        //  is not, reset the oscillator phase so that
        //  it matches exactly the target Breakpoint 
        //  phase at tgtSamp:
        if ( m_osc.amplitude() == 0. )
        {
            //  recompute the phase so that it is correct
            //  at the target Breakpoint (need to do this
            //  because the null Breakpoint phase was computed
            //  from an interval in seconds, not samples, so
            //  it might be inaccurate):
            //
            //  double favg = 0.5 * ( prevFrequency + it.breakpoint().frequency() );
            //  double dphase = 2 * Pi * favg * ( tgtSamp - currentSamp ) / m_srateHz;
            //
            double dphase = Pi * ( prevFrequency + it.breakpoint().frequency() ) 
                               * ( tgtSamp - currentSamp ) * OneOverSrate;
            m_osc.setPhase( it.breakpoint().phase() - dphase );
        }

        m_osc.oscillate( bufferBegin + currentSamp, bufferBegin + tgtSamp,
                         it.breakpoint(), m_srateHz );
        
        currentSamp = tgtSamp;
        
        //  remember the frequency, may need it to reset the 
        //  phase if a Null Breakpoint is encountered:
        prevFrequency = it.breakpoint().frequency();
    }

    //  render a fade out segment:  
    m_osc.oscillate( bufferBegin + currentSamp, bufferBegin + endSamp,
                     BreakpointUtils::makeNullAfter( p.last(), m_fadeTimeSec ), m_srateHz );
    
}
    
// -- sample access --

// ---------------------------------------------------------------------------
//  samples (const)
// ---------------------------------------------------------------------------
//! Return a const reference to the sample buffer used (not
//! owned) by this Synthesizer.
const std::vector<double> &
Synthesizer::samples( void ) const 
{
    return *m_sampleBuffer;
}

// ---------------------------------------------------------------------------
//  samples (non-const)
// ---------------------------------------------------------------------------
//! Return a reference to the sample buffer used (not
//! owned) by this Synthesizer.
std::vector<double> &
Synthesizer::samples( void )  
{
    return *m_sampleBuffer;
}

// -- parameter access and mutation --

// ---------------------------------------------------------------------------
//  fadeTime
// ---------------------------------------------------------------------------
//! Return this Synthesizer's Partial fade time, in seconds.
double 
Synthesizer::fadeTime( void ) const 
{
    return m_fadeTimeSec;
}

// ---------------------------------------------------------------------------
//  sampleRate
// ---------------------------------------------------------------------------
//! Return the sampling rate (in Hz) for this Synthesizer.
double 
Synthesizer::sampleRate( void ) const 
{
    return m_srateHz;
}


// ---------------------------------------------------------------------------
//  setFadeTime
// ---------------------------------------------------------------------------
//! Set this Synthesizer's fade time to the specified value 
//! (in seconds, must be non-negative).
//!
//! \param  t The new Partial fade time.
//! \throw  InvalidArgument if the specified fade time is negative.
void 
Synthesizer::setFadeTime( double partialFadeTime )  
{
    //  check to make sure that the specified fade time
    //  is valid:
    if ( partialFadeTime < 0. )
    {
        Throw( InvalidArgument, "Synthesizer Partial fade time must be non-negative." );
    }

    m_fadeTimeSec = partialFadeTime;
}

// ---------------------------------------------------------------------------
//  setSampleRate
// ---------------------------------------------------------------------------
//!	Set this Synthesizer's sample rate to the specified value 
//!	(in Hz, must be positive).
//!
//!	\param	rate The new synthesis sample rate.
//!	\throw	InvalidArgument if the specified rate is nonpositive.
void 
Synthesizer::setSampleRate( double rate )  
{
    //  check to make sure that the specified rate
    //  is valid:
    if ( rate <= 0. )
    {
        Throw( InvalidArgument, "Synthesizer sample rate must be positive." );
    }

    m_srateHz = rate;
}

// ---------------------------------------------------------------------------
//  filter
// ---------------------------------------------------------------------------
//! Return access to the Filter used by this Synthesizer's 
//! Oscillator to implement bandwidth-enhanced sinusoidal 
//! synthesis. (Can use this access to make changes to the
//! filter coefficients.)
Filter & 
Synthesizer::filter( void ) 
{
    return m_osc.filter(); 
}

//  -- parameters structure --

// ---------------------------------------------------------------------------
//  Synthesizer::Parameters default constructor
// ---------------------------------------------------------------------------
//! Assign default initial values to the Synthesizer parameters, Filter
//! defaults are defined in Oscillator.C.
    
static const double Default_FadeTime_Ms = 1;
static const double Default_SampleRate_Hz = 44100;
//static const Synthesizer::EnhancementFlag Default_Enhancement_Flag = Synthesizer::BwEnhanced;


Synthesizer::Parameters::Parameters( void ) :
    fadeTime( Default_FadeTime_Ms * 0.001 ),
    sampleRate( Default_SampleRate_Hz ),
    // enhancement( Default_Enhancement_Flag ),
    filter( Oscillator::prototype_filter() )
{
}

// ---------------------------------------------------------------------------
//  Synthesizer default Parameters local access only
// ---------------------------------------------------------------------------

static
Synthesizer::Parameters & TheSynthesizerDefaultParameters( void ) 
{
    static Synthesizer::Parameters params;
    return params;

}

// ---------------------------------------------------------------------------
//  Synthesizer default Parameters access (static)
// ---------------------------------------------------------------------------
//! Default configuration of a Loris::Synthesizer. Modify the values 
//! in this structure to alter the configuration of all Synthesizers, 
//! including those used by the AiffFile class to render Partials.
const Synthesizer::Parameters & 
Synthesizer::DefaultParameters( void )
{
    return TheSynthesizerDefaultParameters();
}    

// ---------------------------------------------------------------------------
//  Synthesizer default Parameters access (static)
// ---------------------------------------------------------------------------
//! Assign a new default configuration of a Loris::Synthesizer
//! to alter the configuration of all Synthesizers, 
//! including those used by the AiffFile class to render Partials.
//!
//! \param params A Parameters struct describing the new default 
//!               configuration for Synthesizers.
//!	\throw	InvalidArgument if any of the parameters is invalid.
void Synthesizer::SetDefaultParameters( const Synthesizer::Parameters & params )
{
    if ( IsValidParameters( params ) )
    {
        TheSynthesizerDefaultParameters() = params;
    }
}

// ---------------------------------------------------------------------------
//  IsValidParameters (static)
// ---------------------------------------------------------------------------
//! Check the validty of a Parameters structure. Returns true if the
//! struct represents a valid Synthesizer configuration, and false otherwise.
//!
//! \param params A Parameters struct describing a configuration for 
//!               Synthesizers.
bool Synthesizer::IsValidParameters( const Parameters & params )
{    
    //  check to make sure that the sample rate is valid:
    if ( 0. >= params.sampleRate ) 
    {
        Throw( InvalidArgument, "Synthesizer sample rate must be positive." );
    }

    //  check to make sure that the specified fade time
    //  is valid:
    if ( 0. > params.fadeTime )
    {
        Throw( InvalidArgument, 
               "Synthesizer Partial fade time must be non-negative." );
    }
    
    //  check that the filter coefficients are valid -- pretty much 
    //  any coefficients are valid as long as the zeroeth feedback 
    //  coefficient is non-zero:
    if ( 0. == params.filter.denominator()[0] )
    {
        Throw( InvalidArgument, 
               "Synthesizer filter zeroeth feedback coefficient must be non-zero." );
    }
    
    //  if no exception has been raised, return true indicating valid params
    return true;

}

}   //  end of namespace Loris