path: root/src/loris/SpcFile.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
 *
 *
 * SpcFile.C
 *
 * Implementation of SpcFile class for Partial import and export for
 * real-time synthesis in Kyma.
 *
 * Spc files always represent a number of Partials that is a power of
 * two. This is not necessary for purely-sinusoidal files, but might be
 * (not clear) for enhanced data to be properly processed in Kyma. 
 *
 * All of this is kind of disgusting right now. This code has evolved 
 * somewhat randomly, and we are awaiting full support for bandwidth-
 * enhanced data in Kyma..
 *
 * Kelly Fitz, 8 Jan 2003 
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */

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

#include "SpcFile.h"

#include "AiffData.h"
#include "Breakpoint.h"
#include "BigEndian.h"
#include "LorisExceptions.h"
#include "Marker.h"
#include "Notifier.h"
#include "PartialUtils.h"

#include <algorithm>
#include <cmath>
#include <fstream>

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


//  Define this if SpcFiles should always have a number of 
//  Partials that is a power of two. Cannot decide whether 
//  or not they should. Lip?
#define PO2


using std::exp;
using std::log;
using std::sqrt;

//  begin namespace
namespace Loris {

// ---------------------------------------------------------------------------
//  constants, can, or should, these be made variable?
// ---------------------------------------------------------------------------

//  can't we change this? Seems like we could, but 
//  its part of the size of the magic junk in the 
//  Sose chunk.
const int LargestLabel = 256;   // max number of partials for SPC file

    //  1 Mar 05
    //  Found that this cannot actually be 512 for enhanced
    //  Partials, it crashes with a segmentation fault above 256. 
    //  Unfortunately, whatever is causing the problem is not
    //  using this constant, but some other hardcoded thing.
    //  if I change this to 256, then I can still export
    //  256 enhanced Partials, but I don't know what to change
    //  to allow 512! Ugh!
    //  -kel


//  this used to be hard coded into Partial, don't know
//  whether it is needed to make spc files work.
const double Fade = 0.001;

//  this always has to be 24 bits, 1 channel
const int Bps = 24;
const int Nchans = 1;


// ---------------------------------------------------------------------------
//  static helper prototypes, defined at bottom
// ---------------------------------------------------------------------------
static void 
configureEnvelopeDataCk( SoundDataCk & ck, const SpcFile::partials_type & partials );

static void 
configureSosMarkerCk( MarkerCk & ck, const std::vector< Marker > & markers  );

static void
configureSosEnvelopesCk( SosEnvelopesCk & ck );

static std::ostream & 
writeSosEnvelopesChunk( std::ostream & s, const SosEnvelopesCk & ck );

static void
configureExportStruct( const SpcFile::partials_type & partials, double midipitch,
                       double endApproachTime, int enhanced );

static unsigned long getNumSampleFrames( void );

const int SpcFile::MinNumPartials = 32;
const double SpcFile::DefaultRate = 44100.;

// -- construction --
// ---------------------------------------------------------------------------
//  SpcFile constructor from filename
// ---------------------------------------------------------------------------
//  Initialize an instance of SpcFile by importing envelope parameter 
//  streams from the file having the specified filename or path.
//
SpcFile::SpcFile( const std::string & filename ) :
    notenum_( 60 ),
    rate_( DefaultRate )
{
    readSpcData( filename );
}

// ---------------------------------------------------------------------------
//  SpcFile constructor, empty.
// ---------------------------------------------------------------------------
//  Initialize an instance of SpcFile having the specified fractional
//  MIDI note number, and no Partials (or envelope parameter streams). 
//
SpcFile::SpcFile( double midiNoteNum ) :
    notenum_( midiNoteNum ),
    rate_( DefaultRate )
{
    growPartials( MinNumPartials );
}

// ---------------------------------------------------------------------------
//  write 
// ---------------------------------------------------------------------------
//  Export the phase-correct bandwidth-enhanced envelope parameter 
//  streams represented by this SpcFile to the file having the specified 
//  filename or path. 
//  
//  A nonzero endApproachTime indicates that the Partials do not include a
//  release or decay, but rather end 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.
//  
//  If the endApproachTime is not specified, it is assumed to be zero, 
//  corresponding to Partials that decay or release normally.
//
void 
SpcFile::write( const std::string & filename, double endApproachTime )
{
    write( filename, true, endApproachTime );
}

// ---------------------------------------------------------------------------
//  write 
// ---------------------------------------------------------------------------
//  Export the pure sinsoidal (omitting phase and bandwidth data) envelope 
//  parameter streams represented by this SpcFile to the file having the 
//  specified filename or path. 
//  
//  A nonzero endApproachTime indicates that the Partials do not include a
//  release or decay, but rather end 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.
//  
//  If the endApproachTime is not specified, it is assumed to be zero, 
//  corresponding to Partials that decay or release normally.
//
void 
SpcFile::writeSinusoidal( const std::string & filename, double endApproachTime )
{
    write( filename, false, endApproachTime );
}

// ---------------------------------------------------------------------------
//  write 
// ---------------------------------------------------------------------------
//  Export the envelope parameter streams represented by this SpcFile to
//  the file having the specified filename or path. Export phase-correct 
//  bandwidth-enhanced envelope parameter streams if enhanced is true 
//  (the default), or pure sinsoidal streams otherwise.
//
//  
//  A nonzero endApproachTime indicates that the Partials do not include a
//  release or decay, but rather end 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.
//  
//  If the endApproachTime is not specified, it is assumed to be zero, 
//  corresponding to Partials that decay or release normally.
//
//  This version of write is deprecated, but is handy for internal use,
//  called by the above write and writeSiunsoidal members.
//
void
SpcFile::write( const std::string & filename, bool enhanced, double endApproachTime )
{
    if ( endApproachTime < 0 )
    {
        Throw( InvalidArgument, "End Approach Time may not be negative." );
    }
    
    std::ofstream s( filename.c_str(), std::ofstream::binary );
    if ( ! s )
    {
        std::string s = "Could not create file \"";
        s += filename;
        s += "\". Failed to write Spc file.";
        Throw( FileIOException, s );
    }
    
    //  have to do this before trying to do anything else:
    configureExportStruct( partials_, notenum_, endApproachTime, enhanced );
    
    unsigned long dataSize = 0;

    CommonCk commonChunk;
    configureCommonCk( commonChunk, getNumSampleFrames(), Nchans, Bps, rate_ );
    dataSize += commonChunk.header.size + sizeof(CkHeader);
    
    SoundDataCk soundDataChunk;
    configureEnvelopeDataCk( soundDataChunk, partials_ );
    dataSize += soundDataChunk.header.size + sizeof(CkHeader);
    
    InstrumentCk instrumentChunk;
    configureInstrumentCk( instrumentChunk, notenum_ );
    dataSize += instrumentChunk.header.size + sizeof(CkHeader);

    MarkerCk markerChunk;
    if ( ! markers_.empty() )
    {
        configureSosMarkerCk( markerChunk, markers_ );
        dataSize += markerChunk.header.size + sizeof(CkHeader);
    }
    
    SosEnvelopesCk soseChunk;
    configureSosEnvelopesCk( soseChunk );
    dataSize += soseChunk.header.size + sizeof(CkHeader);
    
    ContainerCk containerChunk;
    configureContainer( containerChunk, dataSize );
    
    try 
    {
        writeContainer( s, containerChunk );
        writeCommonData( s, commonChunk );
        if ( ! markers_.empty() )
            writeMarkerData( s, markerChunk );
        writeInstrumentData( s, instrumentChunk );
        writeSosEnvelopesChunk( s, soseChunk );
        writeSampleData( s, soundDataChunk );
        
        s.close();
    }
    catch ( Exception & ex ) 
    {
        ex.append( " Failed to write Spc file." );
        throw;
    }
}

// -- access --

// ---------------------------------------------------------------------------
//  markers 
// ---------------------------------------------------------------------------
//  Return a reference to the Marker (see Marker.h) container 
//  for this SpcFile. 
//
SpcFile::markers_type & 
SpcFile::markers( void )
{
    return markers_;
}

const SpcFile::markers_type & 
SpcFile::markers( void ) const
{
    return markers_;
}

// ---------------------------------------------------------------------------
//  midiNoteNumber 
// ---------------------------------------------------------------------------
//  Return the fractional MIDI note number assigned to this SpcFile. 
//  If the sound has no definable pitch, note number 60.0 is used.
//
double 
SpcFile::midiNoteNumber( void ) const
{
    return notenum_;
}

// ---------------------------------------------------------------------------
//  partials 
// ---------------------------------------------------------------------------
//  Return a read-only (const) reference to the bandwidth-enhanced
//  Partials represented by the envelope parameter streams in this SpcFile.
//
const SpcFile::partials_type & 
SpcFile::partials( void ) const
{
    return partials_;
}

// ---------------------------------------------------------------------------
//  sampleRate 
// ---------------------------------------------------------------------------
//  Return the sampling freqency in Hz for the spc data in this
//  SpcFile. This is the rate at which Kyma must be running to ensure
//  proper playback of bandwidth-enhanced Spc data.
//
double 
SpcFile::sampleRate( void ) const
{
    return rate_;
}

// -- mutation --

// ---------------------------------------------------------------------------
//  addPartial 
// ---------------------------------------------------------------------------
//  Add the specified Partial to the enevelope parameter streams
//  represented by this SpcFile. 
//  
//  A SpcFile can contain only one Partial having any given (non-zero) 
//  label, so an added Partial will replace a Partial having the 
//  same label, if such a Partial exists.
//
//  This may throw an InvalidArgument exception if an attempt is made
//  to add unlabeled Partials, or Partials labeled higher than the
//  allowable maximum.
//
void 
SpcFile::addPartial( const Partial & p )
{
    addPartial( p, p.label() );
}

// ---------------------------------------------------------------------------
//  addPartial 
// ---------------------------------------------------------------------------
//  Add a Partial, assigning it the specified label (and position in the
//  Spc data). 
//
//  A SpcFile can contain only one Partial having any given (non-zero) 
//  label, so an added Partial will replace a Partial having the 
//  same label, if such a Partial exists.
//
//  This may throw an InvalidArgument exception if an attempt is made
//  to add unlabeled Partials, or Partials labeled higher than the
//  allowable maximum.
//
void 
SpcFile::addPartial( const Partial & p, int label  )
{
    if ( p.label() == 0 )
    {
        Throw( InvalidArgument, "Spc Partials must be labeled." );
    }
    if ( label < 1 )
    {
        Throw( InvalidArgument, "Spc Partials must have positive labels." );
    }
    if ( label > LargestLabel )
    {
        Throw( InvalidArgument, "Spc Partial label is too large, cannot have more than 256." );
    }

    if ( label > partials_.size() )
    {
        growPartials( label );
    }
        
    partials_[label - 1] = p;
    partials_[label - 1].setLabel( label );
}

// ---------------------------------------------------------------------------
//  setMidiNoteNumber 
// ---------------------------------------------------------------------------
//  Set the fractional MIDI note number assigned to this SpcFile. 
//  If the sound has no definable pitch, use note number 60.0 (the default).
//
void 
SpcFile::setMidiNoteNumber( double nn )
{
    if ( nn < 0 || nn > 128 )
    {
        Throw( InvalidArgument, "MIDI note number outside of the valid range [1,128]" );
    }
    notenum_ = nn;
}

// ---------------------------------------------------------------------------
//  setSampleRate 
// ---------------------------------------------------------------------------
//  Set the sampling freqency in Hz for the spc data in this
//  SpcFile. This is the rate at which Kyma must be running to ensure
//  proper playback of bandwidth-enhanced Spc data.
//
void 
SpcFile::setSampleRate( double rate )
{
    if ( rate <= 0 )
    {
        Throw( InvalidArgument, "Sample rate must be positive." );
    }
    rate_ = rate;
}

// -- helpers --

// ---------------------------------------------------------------------------
//  growPartials 
// ---------------------------------------------------------------------------
//
void 
SpcFile::growPartials( partials_type::size_type sz )
{
    if ( partials_.size() < sz )
    {
#ifdef PO2
        partials_type::size_type po2sz = MinNumPartials;
        while ( po2sz < sz )
        {
            po2sz *= 2;
        }
        partials_.resize( po2sz );
#else
        partials_.resize( sz );
#endif
        for ( partials_type::size_type j = 0; j < partials_.size(); ++j )
        {
            partials_[j].setLabel( j+1 );
        }
    }
}

// -- export structures --

// ---------------------------------------------------------------------------
//  Export Structures
// ---------------------------------------------------------------------------
//

//  structure for export information
struct SpcExportInfo
{
    double midipitch;       //  note number (69.00 = A440) for spc file;
                            //  this is the core parameter, others are, by default,
                            //  computed from this one
    double endApproachTime; //  in seconds, this indicates 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 spectral content at the end,
                            //  0.0 indicates no such modifications are to be done
    int numPartials;        //  number of partials in spc file
    int fileNumPartials;    //  the actual number of partials plus padding to make a 2**n value
    int enhanced;           //  true for bandwidth-enhanced spc file, false for pure sines
    double startTime;       //  in seconds, time of first frame in spc file
    double endTime;         //  in seconds, this indicates the time at which to truncate the end
                            //  of the spc file, 0.0 indicates no truncation
    double markerTime;      //  in seconds, this indicates time at which a marker is inserted in the
                            //  spc file, 0.0 indicates no marker is desired
    double sampleRate;      //  in hertz, intended sample rate for synthesis of spc file
    double hop;             //  hop size, based on numPartials and sampleRate
    double ampEpsilon;      //  small amplitude value (related to lsb value in spc file log-amp)
};

static struct SpcExportInfo spcEI;      // yikky global spc Export information


// -- export helpers by Lippold --

// ---------------------------------------------------------------------------
//  fileNumPartials
// ---------------------------------------------------------------------------
//  Find number of partials in SOS file.  This is the actual number of partials,
//  plus padding to make a 2**n value. 
//
static int fileNumPartials( int partials )
{
    if ( partials <= 32 )   
        return 32;
    if ( partials <= 64 )   
        return 64;
    if ( partials <= 128 )  
        return 128;
    else if ( partials <= 256 )
        return 256;
    else if ( partials <= LargestLabel )
        return LargestLabel;

    Throw( FileIOException, "Too many SPC partials!" );
    return LargestLabel;
}

// ---------------------------------------------------------------------------
//  envLog( )
// ---------------------------------------------------------------------------
//  For a range 0 to 1, this returns a log value, 0x0000 to 0xFFFF.
//
static unsigned long envLog( double floatingValue )
{
    static double coeff = 65535.0 / log( 32768. );

    return (unsigned long)( coeff * log( 32768.0 * floatingValue + 1.0 ) );

}   //  end of envLog( )

// ---------------------------------------------------------------------------
//  envExp( )
// ---------------------------------------------------------------------------
//  For a range 0x0000 to 0xFFFF, this returns an exponentiated value in the range 0..1.
//  This is the counterpart of SpcFile::envLog().
//
static double envExp( long intValue )
{
    static double coeff = 65535.0 / log( 32768. );

    return ( exp( intValue / coeff ) - 1.0 ) / 32768.0;

}   //  end of envExp( )

// ---------------------------------------------------------------------------
//  getPhaseRefTime
// ---------------------------------------------------------------------------
//  Find the time at which to reference phase.
//  The time will be shortly after amplitude onset, if we are before the onset.
//
static double getPhaseRefTime( int label, const Partial & p, double time  )
{
// Keep array of previous values to optimize spc export.
// This depends on this routine being called in increasing-time order.
    static double prevPRT[LargestLabel + 1];
    if ( prevPRT[label] > time && time > spcEI.startTime )
        return prevPRT[ label ]; 
            
// Go forward to nonzero amplitude.
    while ( p.amplitudeAt( time, Fade ) < spcEI.ampEpsilon && time < spcEI.endTime + spcEI.hop)
    {
        time += spcEI.hop;
    }

    prevPRT[ label ] = time;

// Use phase value at initial onset time.
    return time;
        
}

// ---------------------------------------------------------------------------
//  afbp
// ---------------------------------------------------------------------------
//  Find amplitude, frequency, bandwidth, phase value.  
//
static void afbp( const Partial & p, double time, double phaseRefTime,
                  double magMult, double freqMult, 
                  double & amp, double & freq, double & bw, double & phase)
{   
    
// Optional endApproachTime processing:
// Approach amp, freq, and bw values at endTime, and stick at endTime amplitude.
// We avoid a sudden transition when using stick-at-end-frame sustains.
// Compute weighting factor between "normal" envelope point and static point.
    if ( spcEI.endApproachTime && time > spcEI.endTime - spcEI.endApproachTime )
    {
        if ( time > p.endTime() && p.endTime() > spcEI.endTime - 2 * spcEI.hop)
            time = p.endTime();
        double wt = ( spcEI.endTime - time ) / spcEI.endApproachTime;
        amp   = magMult  * ( wt * p.amplitudeAt( time, Fade ) + 
                             (1.0 - wt) * p.amplitudeAt( spcEI.endTime, Fade )  );
        freq  = freqMult * ( wt * p.frequencyAt( time ) + (1.0 - wt) * p.frequencyAt( spcEI.endTime )  );
        bw    =            ( wt * p.bandwidthAt( time ) + (1.0 - wt) * p.bandwidthAt( spcEI.endTime )  );
        phase = p.phaseAt( time );
    }
    
// If we are before the phase reference time, or on the final frame,
// use zero amp and offset phase.
    else if ( time < phaseRefTime - spcEI.hop / 2 || time > spcEI.endTime - spcEI.hop / 2 )
    {
        amp = 0.;
        freq = freqMult * p.frequencyAt( phaseRefTime );
        bw = 0.;
        phase = p.phaseAt( phaseRefTime ) - 2. * Pi * (phaseRefTime - time) * freq;
    }
    
// Use envelope values at "time".
    else
    {
        amp = magMult * p.amplitudeAt( time, Fade );
        freq = freqMult * p.frequencyAt( time );
        bw = p.bandwidthAt( time );
        phase = p.phaseAt( time );
    }
}

// ---------------------------------------------------------------------------
//  pack
// ---------------------------------------------------------------------------
//  Pack envelope breakpoint value for interpretation by Envelope Reader sounds
//  in Kyma.  The packed result is two 24-bit quantities, lval and rval.
//
//  In lval, the log of the sine magnitude occupies the top 8 bits, the log of the
//  frequency occupies the bottom 16 bits.
//
//  In rval, the log of the noise magnitude occupies the top 8 bits, the scaled
//  linear phase occupies the bottom 16 bits. 
//
//  lval and rval are pointers to 3-bytes each, filled in by this function.
//
static void pack( double amp, double freq, double bw, double phase,
                  Byte * lbytes, Byte * rbytes )
{   

// Set phase for one hop earlier, so that Kyma synthesis target phase is correct.
// Add offset to phase for difference between Kyma and Loris representation.
    phase -= 2. * Pi * spcEI.hop * freq; 
    phase += Pi / 2;

// Make phase into range 0..1.  
    phase = std::fmod( phase, 2. * Pi );
    while ( phase < 0. ) 	// used to be if, I think it should be while
    {						// -kel 12 May 2006
        phase += 2. * Pi; 
    }
    double zeroToOnePhase = phase / (2. * Pi);

// Make frequency into range 0..1.
    double zeroToOneFreq = freq / 22050.0;      // 0..1 , 1 is 22.050 kHz

// Compute sine magnitude and noise magnitude from amp and bw.  
    double theSineMag = amp * sqrt( 1. - bw );
    double theNoiseMag = 64.0 * amp * sqrt( bw );
    if (theNoiseMag > 1.0)
        theNoiseMag = 1.0;

// Pack amp and freq into 24 least-significant bits of lval:    
// 7 bits of log-sine-amplitude with 16 bits of zero to right.
// 16 bits of log-frequency with 0 bits of zero to right.
    unsigned long lval;
    lval = ( envLog( theSineMag ) & 0xFE00 ) << 7;
    lval |= ( envLog( zeroToOneFreq ) & 0xFFFF );
    
//  store in lbytes:
//  store the sample bytes in big endian order, 
//  most significant byte first:
    const int BytesPerSample = 3;
    for ( int j = BytesPerSample; j > 0; --j )
    {
        //  mask the lowest byte after shifting:
        *(lbytes++) = 0xFF & (lval >> (8*(j-1)));
    }

// Pack noise amp and phase into 24 least-significant bits of rval:
// 7 bits of log-noise-amplitude with 16 bits of zero to right.
// 16 bits of phase with 0 bits of zero to right.
    unsigned long rval;
    rval = ( envLog( theNoiseMag ) & 0xFE00 ) << 7;
    rval  |= ( (unsigned long) ( zeroToOnePhase * 0xFFFF ) );

//  store in rbytes:
//  store the sample bytes in big endian order, 
//  most significant byte first:
    for ( int j = BytesPerSample; j > 0; --j )
    {
        //  mask the lowest byte after shifting:
        *(rbytes++) = 0xFF & (rval >> (8*(j-1)));
    }
}

// ---------------------------------------------------------------------------
//  packEnvelopes
// ---------------------------------------------------------------------------
//  The partials should be labeled and distilled before this is called.
//
static bool notEmpty( const Partial & p )  { return p.size() > 0; }

static void packEnvelopes( const SpcFile::partials_type & partials, 
                           std::vector< Byte > & bytes )
{   
//  Assert( partials.size() == spcEI.fileNumPartials );

    int frames = int( ( spcEI.endTime - spcEI.startTime ) / spcEI.hop ) + 1;
    unsigned long dataSize = 
        frames * spcEI.fileNumPartials * ( 24 / 8 ) * (spcEI.enhanced ? 2 : 1);
    bytes.clear();
    bytes.reserve( dataSize );
    
    // get the reference partial; the lowest-nonzero-labeled partial with any breakpoints
    SpcFile::partials_type::const_iterator pos = 
        std::find_if( partials.begin(), partials.end(), notEmpty );
    Assert( pos != partials.end() );
    const Partial & refPar = *pos;
    int refLabel = refPar.label();
    Assert( (refLabel - 1) == (pos - partials.begin()) );
    
    // write out one frame at a time:
    for (double tim = spcEI.startTime; tim <= spcEI.endTime; tim += spcEI.hop ) 
    {
        //  for each frame, write one value for every partial:
        //  (this loop extends to the pad partials)
        for (unsigned int label = 1; label <= spcEI.fileNumPartials; ++label ) 
        {
            double amp, freq, bw, phase;
            //  find partial with the correct label
            //  if partial with the correct is empty, 
            //  frequency-multiply the reference partial
#ifndef PO2
            if ( label > partials.size() || partials[ label - 1 ].size() == 0 )
#else
            if ( partials[ label - 1 ].size() == 0 )
#endif
            {
                //  find the reference time for the phase
                double phaseRefTime = getPhaseRefTime( label, refPar, tim );
                
                //  find amplitude, frequency, bandwidth, phase value
                double freqMult = (double) label / (double) refLabel; 
                double magMult = 0.0;
                afbp( refPar, tim, phaseRefTime, magMult, freqMult, amp, freq, bw, phase );
            }
            else
            {
                //  find the reference time for the phase
                double phaseRefTime = getPhaseRefTime( label, partials[ label - 1 ], tim );
                
                //  find amplitude, frequency, bandwidth, phase value
                afbp( partials[ label - 1 ], tim, phaseRefTime, 1, 1, amp, freq, bw, phase );
            }
            
            //  pack log amplitude and log frequency into 24-bit lval,
            //  log bandwidth and phase into 24-bit rval:
            Byte leftbytes[3], rightbytes[3];
            pack( amp, freq, bw, phase, leftbytes, rightbytes);
    
            //  pack integer samples into the Byte vector without 
            //  byte swapping, they are already correctly packed
            //  (see pack above): 
            bytes.insert( bytes.end(), leftbytes, leftbytes + 3 );
            if ( spcEI.enhanced )
            {
                bytes.insert( bytes.end(), rightbytes, rightbytes + 3 );
            }               
        }
    }
    
    Assert( bytes.size() == dataSize );
}

// ---------------------------------------------------------------------------
//  configureEnvelopeDataCk
// ---------------------------------------------------------------------------
//  Configure a special SoundDataCk for exporting Spc envelopes.
//
static void 
configureEnvelopeDataCk( SoundDataCk & ck, const SpcFile::partials_type & partials  )
{
    packEnvelopes( partials, ck.sampleBytes );
    
    ck.header.id = SoundDataId;

    //  size is everything after the header:
    ck.header.size = sizeof(Uint_32) +      //  offset
                     sizeof(Uint_32) +      //  block size
                     ck.sampleBytes.size(); //  sample data

    //  no block alignment: 
    ck.offset = 0;
    ck.blockSize = 0;
}

// ---------------------------------------------------------------------------
//  configureSosMarkerCk
// ---------------------------------------------------------------------------
//  Spc needs a special version of this, because Marker times have to be
//  rounded to the nearest frame.
//
void 
configureSosMarkerCk( MarkerCk & ck, const std::vector< Marker > & markers  )
{
    ck.header.id = MarkerId;

    //  accumulate data size
    Uint_32 dataSize = sizeof(Uint_16); //  num markers
    
    ck.numMarkers = markers.size();
    ck.markers.resize( markers.size() );
    for ( int j = 0; j < markers.size(); ++j )
    {
        MarkerCk::Marker & m = ck.markers[j];
        m.markerID = j+1;
        //m.position = Uint_32((markers[j].time() * srate) + 0.5);
        
        //  align marker with nearest frame time:
        m.position = Uint_32( markers[j].time() / spcEI.hop ) 
                     * spcEI.fileNumPartials 
                     * ( spcEI.enhanced ? 2 : 1 ); 

        m.markerName = markers[j].name();
        
        #define MAX_PSTRING_CHARS 254
        if ( m.markerName.size() > MAX_PSTRING_CHARS )
            m.markerName.resize( MAX_PSTRING_CHARS );
        
        //  the size of a pascal string is the number of 
        //  characters plus the size byte, plus the terminal '\0':
        //  
        //  Actualy, at least one web source indicates that Pascal
        //  strings are not null-terminated, but that they _are_
        //  padded with an extra (not part of the count) byte
        //  if necessary to ensure that the total length (including
        //  count) is even, and this seems to work better with other
        //  programs (e.g. Kyma)
        if ( m.markerName.size()%2 == 0 )
                m.markerName += '\0';
        dataSize += sizeof(Uint_16) + sizeof(Uint_32) + (m.markerName.size() + 1);
    }

    //  must be an even number of bytes
    if ( dataSize%2 )
        ++dataSize;

    ck.header.size = dataSize;
}


// ---------------------------------------------------------------------------
//  configureSosEnvelopesCk
// ---------------------------------------------------------------------------
//  Configure a the application-specific chunk for exporting Spc envelopes.
//
static void
configureSosEnvelopesCk( SosEnvelopesCk & ck )
{
    ck.header.id = ApplicationSpecificId;

    //  size is everything after the header:
    ck.header.size = sizeof(Uint_32) +                  // signature
                     sizeof(Uint_32) +                  // enhanced
                     sizeof(Uint_32) +                  // validPartials
                     // this last bit is a big, obsolete array, that
                     // we now use two positions in, an they aren't
                     // even the first two! Truly nasty.
                     4*LargestLabel + 8 * sizeof(Int_32);// initPhase[] et al
    
    ck.signature = SosEnvelopesId;

    ck.enhanced = spcEI.enhanced;
    
    //  the number of partials is doubled in bandwidth-enhanced spc files
    ck.validPartials = spcEI.numPartials * ( spcEI.enhanced ? 2 : 1 );
    
    //  resolution in microseconds
    ck.resolution = long( 1000000.0 * spcEI.hop );
    
    //  all partials quasiharmonic
    //  the number of partials is doubled in bandwidth-enhanced spc files
    ck.quasiHarmonic =  spcEI.numPartials * ( spcEI.enhanced ? 2 : 1); 

}

// ---------------------------------------------------------------------------
//  writeSosEnvelopesChunk
// ---------------------------------------------------------------------------
//
std::ostream & 
writeSosEnvelopesChunk( std::ostream & s, const SosEnvelopesCk & ck )
{
    //  write it out:
    try 
    {
        BigEndian::write( s, 1, sizeof(Int_32), (char *)&ck.header.id );
        BigEndian::write( s, 1, sizeof(Int_32), (char *)&ck.header.size );
        BigEndian::write( s, 1, sizeof(Int_32), (char *)&ck.signature );
        BigEndian::write( s, 1, sizeof(Int_32), (char *)&ck.enhanced );
        BigEndian::write( s, 1, sizeof(Int_32), (char *)&ck.validPartials );
        
        // The SOSresultion and SOSquasiHarmonic fields are in the phase table memory.
        //BigEndian::write( s, initPhaseLth, sizeof(Int_32), (char *)&ck.initPhase[0] );
        static const int InitPhaseLth = ( LargestLabel + 8 );
        Int_32 bogus[ InitPhaseLth ]; // obsolete initial phase array
        std::fill( bogus, bogus + InitPhaseLth, 0 );
        bogus[ ck.validPartials ] = ck.resolution;
        bogus[ ck.validPartials + 1 ] = ck.quasiHarmonic;
        BigEndian::write( s, InitPhaseLth, sizeof(Int_32), (char *)bogus );
    }
    catch( FileIOException & ex ) 
    {
        ex.append( "Failed to write AIFF file Container chunk." );
        throw;
    }
    
    return s;

}

// ---------------------------------------------------------------------------
//  computeHop
// ---------------------------------------------------------------------------
//  Find the hop size, based on number of partials and sample rate. 
//
static double computeHop( int numPartials, double sampleRate )
{
    return 2 * numPartials / sampleRate;
}


// ---------------------------------------------------------------------------
//  computeStartTime
// ---------------------------------------------------------------------------
//  Find the start time: the earliest time of any labeled partial.
//
static double computeStartTime( const SpcFile::partials_type & pars )
{
    double startTime = 1000.;
    for ( SpcFile::partials_type::const_iterator pIter = pars.begin(); pIter != pars.end(); ++pIter )
        if ( pIter->size() > 0 && startTime > pIter->startTime() && pIter->label() > 0 )
            startTime = pIter->startTime();
    return startTime;
}


// ---------------------------------------------------------------------------
//  computeEndTime
// ---------------------------------------------------------------------------
//  Find the end time: the latest time of any labeled partial.
//
static double computeEndTime( const SpcFile::partials_type & pars )
{
    double endTime = -1000.;
    for ( SpcFile::partials_type::const_iterator pIter = pars.begin(); pIter != pars.end(); ++pIter )
        if ( pIter->size() > 0 && endTime < pIter->endTime()  && pIter->label() > 0 )
            endTime = pIter->endTime();
    return endTime;
}


// ---------------------------------------------------------------------------
//  computeNumPartials
// ---------------------------------------------------------------------------
//  Find the number of partials.
//
static long computeNumPartials( const SpcFile::partials_type & pars )
{

// We purposely consider partials with no breakpoints, to allow
// a larger number of partials than actually have data.
    int numPartials = 0;
    for ( SpcFile::partials_type::const_iterator pIter = pars.begin(); pIter != pars.end(); ++pIter )
        if ( numPartials < pIter->label() )
            numPartials = pIter->label();

// To ensure a reasonable hop time, make at least 32 partials.
    return numPartials ? std::max( 32, numPartials ) : 0;
}

// ---------------------------------------------------------------------------
//  configureExportStruct
// ---------------------------------------------------------------------------
static void
configureExportStruct( const SpcFile::partials_type & plist, double midipitch,
                       double endApproachTime, int enhanced )
{   
    //  note number (69.00 = A440) for spc file
    spcEI.midipitch = midipitch;
    
    //  enhanced indicates a bandwidth-enhanced spc file; by default it is true.
    //  if enhanced is false, no bandwidth or noise information is exported.
    spcEI.enhanced = enhanced;
    
    //  endApproachTime is in seconds; by default it is zero (and has no effect).
    //  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.
    spcEI.endApproachTime = endApproachTime;
    
    //  number of partials in spc file
    spcEI.numPartials = computeNumPartials( plist );
    spcEI.fileNumPartials = fileNumPartials( spcEI.numPartials );
    
    //  start and end time of spc file
    spcEI.startTime = computeStartTime( plist );
    spcEI.endTime = computeEndTime( plist );

    //  in seconds, this indicates time at which a marker is inserted 
    //  in the spc file, 0.0 indicates no marker.  this is not being used currently.
    spcEI.markerTime = 0.;
        
    //  in hertz, intended sample rate for synthesis of spc file
    spcEI.sampleRate = 44100.;      
    
    //  compute hop size
    spcEI.hop = computeHop( spcEI.numPartials, spcEI.sampleRate );

    //  compute ampEpsilon, a small amplitude value twice the lsb value 
    //  of log amp in packed spc format. 
    spcEI.ampEpsilon = 2. * envExp( 0x200 );

    // Max number of partials is due to (arbitrary) size of initPhase[].
    if ( spcEI.numPartials < 1 || spcEI.numPartials > LargestLabel )
        Throw( FileIOException, "Partials must be distilled and labeled between 1 and 512." );

    debugger << "startTime = " << spcEI.startTime << " endTime = " << spcEI.endTime 
             << " hop = " << spcEI.hop << " partials = " << spcEI.numPartials << endl;
}

// ---------------------------------------------------------------------------
//  getNumSampleFrames
// ---------------------------------------------------------------------------
//  The number of exported sample frames is computed from data stored in
//  the icky global export struct.
//
static unsigned long getNumSampleFrames( void )
{
    int frames = int( ( spcEI.endTime - spcEI.startTime ) / spcEI.hop ) + 1;
    return frames * spcEI.fileNumPartials * ( spcEI.enhanced ? 2 : 1 );
}

// -- import helpers by Lippold --
// ---------------------------------------------------------------------------
//  processEnhancedPoint
// ---------------------------------------------------------------------------
//  Add ehanced-spc breakpoint to existing Loris partials.
//
static void
processEnhancedPoint( Byte * leftbytes, Byte * rightbytes, 
                      const double frameTime, 
                      Partial & par )
{
//  represent bytes as 24 bit integers:
    const int BytesPerSample = 3;   

    //  assign the leading byte, so that the sign
    //  is preserved:
    long left = static_cast<char>(*(leftbytes++));
    for ( int j = 1; j < BytesPerSample; ++j )
    {
        //  OR bytes after the most significant, so
        //  that their sign is ignored:
        left = (left << 8) + (unsigned char)*(leftbytes++);
    }
    
    long right = static_cast<char>(*(rightbytes++));
    for ( int j = 1; j < BytesPerSample; ++j )
    {
        //  OR bytes after the most significant, so
        //  that their sign is ignored:
        right = (right << 8) + (unsigned char)*(rightbytes++);
    }
//
// Unpack values.  
//
    double freq = envExp( left & 0xffff ) * 22050.0;
    double sineMag =     envExp( (left >> 7)  & 0xfe00 );
    double noiseMag = envExp( (right >> 7) & 0xfe00 ) / 64.;
    double phase = ( right & 0xffff ) * ( 2. * Pi / 0xffff );
    
    double total = sineMag * sineMag + noiseMag * noiseMag;

    double amp = sqrt( total );
    
    double noise = 0.;
    if (total != 0.)
        noise = noiseMag * noiseMag / total;
    if (noise > 1.)
        noise = 1.;
    
    phase -= Pi / 2.;
    if (phase < 0.)
        phase += 2. * Pi;

//
// Create a new breakpoint and insert it.
//  
    Breakpoint newbp( freq, amp, noise, phase );
    par.insert( frameTime, newbp );
}

// ---------------------------------------------------------------------------
//  processSineOnlyPoint
// ---------------------------------------------------------------------------
//  Add sine-only spc breakpoint to existing Loris partials.
//
static void
processSineOnlyPoint( Byte * bytes, 
                      const double frameTime, 
                      Partial & par )
{
//  represent bytes as 24 bit integers:
    const int BytesPerSample = 3;   

    //  assign the leading byte, so that the sign
    //  is preserved:
    long packed = static_cast<char>(*(bytes++));
    for ( int j = 1; j < BytesPerSample; ++j )
    {
        //  OR bytes after the most significant, so
        //  that their sign is ignored:
        packed = (packed << 8) + (unsigned char)*(bytes++);
    }

//
// Unpack values.  
//
    double freq = envExp( packed & 0xffff ) * 22050.0;
    double amp =     envExp( (packed >> 7)  & 0xfe00 );
    double noise = 0.;
    double phase = 0.;

//
// Create a new breakpoint and insert it.
//  
    Breakpoint newbp( freq, amp, noise, phase );
    par.insert( frameTime, newbp );
}

// ---------------------------------------------------------------------------
//  readSpcData
// ---------------------------------------------------------------------------
//
void 
SpcFile::readSpcData( const std::string & filename )
{
    ContainerCk containerChunk;
    CommonCk commonChunk;
    SoundDataCk soundDataChunk;
    InstrumentCk instrumentChunk;
    MarkerCk markerChunk;
    SosEnvelopesCk soseChunk;

    try 
    {
        std::ifstream s( filename.c_str(), std::ifstream::binary );
    
        //  the Container chunk must be first, read it:
        readChunkHeader( s, containerChunk.header );
        if( containerChunk.header.id != ContainerId )
            Throw( FileIOException, "Found no Container chunk." );
        readContainer( s, containerChunk, containerChunk.header.size );
        
        //  read other chunks, we are only interested in
        //  the Common chunk, the Sound Data chunk, the Markers: 
        CkHeader h;
        while ( readChunkHeader( s, h ) )
        {           
            switch (h.id)
            {
                case CommonId:
                    readCommonData( s, commonChunk, h.size );
                    if ( commonChunk.channels != 1 )
                    {
                        Throw( FileIOException, 
                               "Loris only processes single-channel AIFF samples files." );
                    }                   
                    if ( commonChunk.bitsPerSample != 8 &&
                         commonChunk.bitsPerSample != 16 &&
                         commonChunk.bitsPerSample != 24 &&
                         commonChunk.bitsPerSample != 32 )
                    {
                        Throw( FileIOException, "Unrecognized sample size." );
                    }                                       
                    break;
                case SoundDataId:
                    readSampleData( s, soundDataChunk, h.size );
                    break;
                case InstrumentId:
                    readInstrumentData( s, instrumentChunk, h.size );
                    break;
                case MarkerId:
                    readMarkerData( s, markerChunk, h.size );
                    break;
                case ApplicationSpecificId:
                    readApplicationSpecifcData( s, soseChunk, h.size );
                    break;
                default:
                    s.ignore( h.size );
            }
        }
    
        if ( ! commonChunk.header.id || ! soundDataChunk.header.id )
        {
            Throw( FileIOException, 
                   "Reached end of file before finding both a Common chunk and a Sound Data chunk." );
        }
        if ( soseChunk.signature != SosEnvelopesId )
        {
            Throw( FileIOException, 
                   "Reached end of file before finding a Spc Envelope Data chunk, this must not be a Spc file." );
        }
    }
    catch ( Exception & ex ) 
    {
        ex.append( " Failed to read Spc file." );
        throw;
    }
    
    //  all the chunks have been read, use them to initialize
    //  the SpcFile members:
    rate_ = commonChunk.srate;

    // why was this like this:
    // double rate  = commonChunk.srate;
    
    if ( instrumentChunk.header.id )
    {
        notenum_ = instrumentChunk.baseNote;
        notenum_ -= 0.01 * instrumentChunk.detune;
    }
    
    //  extract information from SOSe chunk:
    //  enhanced file format has number of partials doubled
    //  sine-only file format has proper number of partials
    bool enhanced = soseChunk.enhanced != 0;
    int numPartials = enhanced ? soseChunk.validPartials / 2 : soseChunk.validPartials;
    int numFrames = commonChunk.sampleFrames / ( fileNumPartials( numPartials ) * ( enhanced ? 2 : 1 ) );
    double hop = soseChunk.resolution * 0.000001;   // resolution is in microseconds
    
    //  read markers, need to compute times corresponding to
    //  spc frames:
    if ( markerChunk.header.id )
    {
        for ( int j = 0; j < markerChunk.numMarkers; ++j )
        {
            MarkerCk::Marker & m = markerChunk.markers[j];
            double markerTime = m.position * hop / ( fileNumPartials( numPartials ) * ( enhanced ? 2 : 1 ) );
            markers_.push_back( Marker( markerTime, m.markerName ) );
        }       
    }


    //  check for valid file
    if ( numPartials == 0 || commonChunk.bitsPerSample != 24 )
            Throw( FileIOException, "Not an SPC file." );
    if ( numPartials < MinNumPartials || numPartials > LargestLabel )
            Throw( FileIOException, "Bad number of partials in SPC file." );

    //  check the number of bytes of Spc data:  
    const int BytesPerSample = 3;
    const int PredictedNumBytes = 
        BytesPerSample * numFrames * fileNumPartials( numPartials ) * ( enhanced ? 2 : 1 );
    if ( soundDataChunk.sampleBytes.size() != PredictedNumBytes )
    {
        notifier << "Found " << soundDataChunk.sampleBytes.size() << " bytes of "
                 << commonChunk.bitsPerSample << "-bit sample data." << endl;
        notifier << "Header says there should be " << PredictedNumBytes
                 << "." << endl;
    }

    //  process SPC data points
    partials_.clear();
    growPartials( numPartials );
    Byte * bytes = &soundDataChunk.sampleBytes.front();
    for ( int frame = 0; frame < numFrames; ++frame ) 
    {
        for ( int partial = 0; partial < fileNumPartials( numPartials ); ++partial )
        {
            if (enhanced)
            {
                Byte * lbytes = bytes;
                bytes += BytesPerSample;
                Byte * rbytes = bytes;
                bytes += BytesPerSample;
                if ( partial < partials_.size() )
                    processEnhancedPoint( lbytes, rbytes, frame * hop, partials_[partial] );
            }
            else
            {
                if ( partial < partials_.size() )
                    processSineOnlyPoint( bytes, frame * hop, partials_[partial] );
                bytes += BytesPerSample;
            }
        }
    }
}

}   //  end of namespace Loris