path: root/src/loris/AiffFile.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
 *
 *
 * AiffFile.h
 *
 * Definition of AiffFile class for sample import and export in Loris.
 *
 * Kelly Fitz, 8 Jan 2003 
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */
#include "Marker.h"
#include "Synthesizer.h"

#if defined(NO_TEMPLATE_MEMBERS)
#include "PartialList.h"
#endif

#include <memory>
#include <string>
#include <vector>

//  begin namespace
namespace Loris {

class Partial;

// ---------------------------------------------------------------------------
//  class AiffFile
//
//! Class AiffFile represents sample data in a AIFF-format samples 
//! file, and manages file I/O and sample conversion. Since the sound
//! analysis and synthesis algorithms in Loris and the reassigned
//! bandwidth-enhanced representation are monaural, AiffFile imports
//! only monaural (single channel) AIFF-format samples files, though
//!	it can create and export a new two-channel file from a pair of 
//!	sample vectors.
//  
class AiffFile
{
//  -- public interface --
public:

//  -- types --

    //! The type of the sample storage in an AiffFile.
    typedef std::vector< double > samples_type;
    
    //! The type of all size parameters for AiffFile.
    typedef samples_type::size_type size_type;
    
    //! The type of AIFF marker storage in an AiffFile.
    typedef std::vector< Marker > markers_type;

//  -- construction --

    //! Initialize an instance of AiffFile by importing sample data from
    //! the file having the specified filename or path.
    //!
    //! \param filename is the name or path of an AIFF samples file
    explicit AiffFile( const std::string & filename );

    //! Initialize an instance of AiffFile with samples rendered
    //! from a sequnence of Partials. The Partials in the
    //! specified half-open (STL-style) range are rendered at 
    //! the specified sample rate, using the (optionally) 
    //! specified Partial fade time (see Synthesizer.h
    //! for an examplanation of fade time). Other synthesis 
	//!	parameters are taken from the Synthesizer DefaultParameters.
	//!	
	//!	\sa Synthesizer::DefaultParameters
    //!
    //! \param begin_partials is the beginning of a sequence of Partials
    //! \param end_partials is (one-past) the end of a sequence of
    //! Partials
    //! \param samplerate is the rate (Hz) at which Partials are rendered
    //! \param fadeTime is the Partial fade time (seconds) for rendering
    //! the Partials on the specified range. If unspecified, the
    //! fade time is taken from the Synthesizer DefaultParameters.
    //!
    //! If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts
    //! only PartialList::const_iterator arguments.
#if !defined(NO_TEMPLATE_MEMBERS)
    template<typename Iter>
    AiffFile( Iter begin_partials, Iter end_partials, 
              double samplerate, double fadeTime = FadeTimeUnspecified );
#else
    AiffFile( PartialList::const_iterator begin_partials, 
              PartialList::const_iterator end_partials,
              double samplerate, double fadeTime = FadeTimeUnspecified ); 
#endif

    //! Initialize an instance of AiffFile having the specified sample 
    //! rate, preallocating numFrames samples, initialized to zero.
    //!
    //! \param samplerate is the rate at which Partials are rendered
    //! \param numFrames is the initial number of (zero) samples. If
    //!        unspecified, no samples are preallocated.
    //! \param numChannels is the number of channels of audio data
    //!        to preallocate (default 1 channel)
    AiffFile( double samplerate, size_type numFrames = 0, 
              unsigned int numChannels = 1 );
    
    //! Initialize an instance of AiffFile from a buffer of sample
    //! data, with the specified sample rate.
    //!
    //! \param buffer is a pointer to a buffer of floating point samples.
    //! \param bufferlength is the number of samples in the buffer.
    //! \param samplerate is the sample rate of the samples in the buffer.
    AiffFile( const double * buffer, size_type bufferlength, double samplerate );

    //! Initialize an instance of AiffFile from two buffers of sample
    //! data, with the specified sample rate. Both buffers must store
    //! the same number (bufferLength) of samples.
    //!
    //! \param buffer_left is a pointer to a buffer of floating point samples 
    //!        representing the left channel samples.
    //! \param buffer_right is a pointer to a buffer of floating point samples 
    //!        representing the right channel samples.
    //! \param bufferlength is the number of samples in the buffer.
    //! \param samplerate is the sample rate of the samples in the buffer.
    //
    AiffFile( const double * buffer_left, const double * buffer_right, 
              size_type bufferlength, double samplerate );
     
    //! Initialize an instance of AiffFile from a vector of sample
    //! data, with the specified sample rate.
    //!
    //! \param vec is a vector of floating point samples.
    //! \param samplerate is the sample rate of the samples in the vector.
    AiffFile( const std::vector< double > & vec, double samplerate );
    
    //! Initialize an instance of AiffFile from two vectors of sample
    //! data, with the specified sample rate. If the two vectors have different
    //! lengths, the shorter one is padded with zeros.
    //!
    //! \param vec_left is a vector of floating point samples representing the 
    //!        left channel samples.
    //! \param vec_right is a vector of floating point samples representing the 
    //!        right channel samples.
    //! \param samplerate is the sample rate of the samples in the vectors.
    //
    AiffFile( const std::vector< double > & vec_left,
              const std::vector< double > & vec_right, 
              double samplerate );    
     
    //! Initialize this and AiffFile that is an exact copy, having
    //! all the same sample data, as another AiffFile.
    //!
    //! \param other is the AiffFile to copy
    AiffFile( const AiffFile & other );
     
    //! Assignment operator: change this AiffFile to be an exact copy
    //! of the specified AiffFile, rhs, that is, having the same sample
    //! data.
    //!
    //! \param rhs is the AiffFile to replicate
    AiffFile & operator= ( const AiffFile & rhs );

//  -- access --

    //! Return a reference to the Marker (see Marker.h) container 
    //! for this AiffFile. 
    markers_type & markers( void );

    //! Return a const reference to the Marker (see Marker.h) container 
    //! for this AiffFile. 
    const markers_type & markers( void ) const;
     
    //! Return the fractional MIDI note number assigned to this AiffFile. 
    //! If the sound has no definable pitch, note number 60.0 is used.
    double midiNoteNumber( void ) const;

    //! Return the number of channels of audio samples represented by
    //! this AiffFile, 1 for mono, 2 for stereo.
    unsigned int numChannels( void ) const;

    //! Return the number of sample frames represented in this AiffFile.
    //! A sample frame contains one sample per channel for a single sample
    //! interval (e.g. mono and stereo samples files having a sample rate of
    //! 44100 Hz both have 44100 sample frames per second of audio samples).
    size_type numFrames( void ) const;

    //! Bad old legacy name for numFrames.
    //! \deprecated Use numFrames instead.
    size_type sampleFrames( void ) const { return numFrames(); }

    //! Return the sampling freqency in Hz for the sample data in this
    //! AiffFile.
    double sampleRate( void ) const;
    
    //! Return a reference (or const reference) to the vector containing
    //! the floating-point sample data for this AiffFile.
    samples_type & samples( void );

    //! Return a const reference (or const reference) to the vector containing
    //! the floating-point sample data for this AiffFile.
    const samples_type & samples( void ) const;

//  -- mutation --

    //! Render the specified Partial using the (optionally) specified
    //! Partial fade time (see Synthesizer.h for an examplanation 
	//!	of fade time), and accumulate the resulting samples into
    //! the sample vector for this AiffFile. Other synthesis parameters 
	//!	are taken from the Synthesizer DefaultParameters.
	//!
	//!	\sa Synthesizer::DefaultParameters
    //!
    //! \param p is the partial to render into this AiffFile
    //! \param fadeTime is the Partial fade time for rendering
    //! the Partials on the specified range. If unspecified, the
	//! fade time is taken from the Synthesizer DefaultParameters.
    void addPartial( const Loris::Partial & p, double fadeTime = FadeTimeUnspecified );
     
	//! Accumulate samples rendered from a sequence of Partials.
	//! The Partials in the specified half-open (STL-style) range are
	//! rendered at this AiffFile's sample rate, using the (optionally) 
	//! specified Partial fade time (see Synthesizer.h for an examplanation 
	//!	of fade time). Other synthesis parameters are taken from the 
	//!	Synthesizer DefaultParameters.
	//!	
	//!	\sa Synthesizer::DefaultParameters
	//!
	//! \param begin_partials is the beginning of a sequence of Partials
	//! \param end_partials is (one-past) the end of a sequence of
	//! Partials
	//! \param fadeTime is the Partial fade time for rendering
	//! the Partials on the specified range. If unspecified, the
	//! fade time is taken from the Synthesizer DefaultParameters.
	//! 
	//! If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts
	//! only PartialList::const_iterator arguments.
#if !defined(NO_TEMPLATE_MEMBERS)
    template<typename Iter>
    void addPartials( Iter begin_partials, Iter end_partials, 
    				  double fadeTime = FadeTimeUnspecified  );
#else
    void addPartials( PartialList::const_iterator begin_partials, 
                      PartialList::const_iterator end_partials,
                      double fadeTime = FadeTimeUnspecified  );
#endif

    //! Set the fractional MIDI note number assigned to this AiffFile. 
    //! If the sound has no definable pitch, use note number 60.0 (the default).
    //!
    //! \param nn is a fractional MIDI note number, 60 is middle C.
    void setMidiNoteNumber( double nn );
     
//  -- export --

    //! Export the sample data represented by this AiffFile to
    //! the file having the specified filename or path. Export
    //! signed integer samples of the specified size, in bits
    //! (8, 16, 24, or 32).
    //!
    //! \param filename is the name or path of the AIFF samples file
    //! to be created or overwritten.
    //! \param bps is the number of bits per sample to store in the
    //! samples file (8, 16, 24, or 32).If unspeicified, 16 bits
    void write( const std::string & filename, unsigned int bps = 16 );

private:
//  -- implementation --
    double notenum_, rate_;     // MIDI note number and sample rate
    unsigned int numchans_;
    markers_type markers_;      // AIFF Markers
    samples_type samples_;      // floating point samples [-1.0, 1.0]


//  -- helpers --

	//	Construct a Synthesizer for rendering Partials and set its fadeTime.
	//	Modify the default synthesizer parameters with this file's sample rate
	//	and, if specified (not equal to FadeTimeUnspecified), the fade time.
	Synthesizer configureSynthesizer( double fadeTime );

	//	Import data from an AIFF file on disk.
    void readAiffData( const std::string & filename );
    
    enum { FadeTimeUnspecified = -9999999 };
    //	This is not pretty, but it is better (perhaps) than defining two 
    //	of every member having an optional fade time parameter.

};  //  end of class AiffFile

// -- template members --

// ---------------------------------------------------------------------------
//  constructor from Partial range
// ---------------------------------------------------------------------------
//! Initialize an instance of AiffFile with samples rendered
//! from a sequnence of Partials. The Partials in the
//! specified half-open (STL-style) range are rendered at 
//! the specified sample rate, using the (optionally) 
//! specified Partial fade time (see Synthesizer.h
//! for an examplanation of fade time). Other synthesis 
//!	parameters are taken from the Synthesizer DefaultParameters.
//!	
//!	\sa Synthesizer::DefaultParameters
//!
//! \param begin_partials is the beginning of a sequence of Partials
//! \param end_partials is (one-past) the end of a sequence of
//! Partials
//! \param samplerate is the rate (Hz) at which Partials are rendered
//! \param fadeTime is the Partial fade time (seconds) for rendering
//! the Partials on the specified range. If unspecified, the
//! fade time is taken from the Synthesizer DefaultParameters.
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts
//! only PartialList::const_iterator arguments.
//
#if !defined(NO_TEMPLATE_MEMBERS)
template< typename Iter >
 AiffFile::AiffFile( Iter begin_partials, Iter end_partials, 
                     double samplerate, double fadeTime ) :
#else
 AiffFile::AiffFile( PartialList::const_iterator begin_partials, 
                     PartialList::const_iterator end_partials,
                     double samplerate, double fadeTime ) :
#endif
//  initializers:
    notenum_( 60 ),
    rate_( samplerate ),
    numchans_( 1 )
{
    addPartials( begin_partials, end_partials, fadeTime );
}

// ---------------------------------------------------------------------------
//  addPartials 
// ---------------------------------------------------------------------------
//! Accumulate samples rendered from a sequence of Partials.
//! The Partials in the specified half-open (STL-style) range are
//! rendered at this AiffFile's sample rate, using the (optionally) 
//! specified Partial fade time (see Synthesizer.h for an examplanation 
//!	of fade time). Other synthesis parameters are taken from the 
//!	Synthesizer DefaultParameters.
//!	
//!	\sa Synthesizer::DefaultParameters
//!
//! \param begin_partials is the beginning of a sequence of Partials
//! \param end_partials is (one-past) the end of a sequence of
//! Partials
//! \param fadeTime is the Partial fade time for rendering
//! the Partials on the specified range. If unspecified, the
//! fade time is taken from the Synthesizer DefaultParameters.
//! 
//! If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts
//! only PartialList::const_iterator arguments.
//
#if !defined(NO_TEMPLATE_MEMBERS)
template< typename Iter >
void 
 AiffFile::addPartials( Iter begin_partials, Iter end_partials, double fadeTime )
#else
void 
 AiffFile::addPartials( PartialList::const_iterator begin_partials, 
                        PartialList::const_iterator end_partials,
                        double fadeTime )
#endif
{ 
    Synthesizer synth = configureSynthesizer( fadeTime );    
    synth.synthesize( begin_partials, end_partials );
} 

}   //  end of namespace Loris