Csound and CsoundAC API  5.17
Public Member Functions | Protected Member Functions | Private Attributes
csound::Soundfile Class Reference

Simple, basic read/write access, in sample frames, to PCM soundfiles. More...

#include <Soundfile.hpp>

Public Member Functions

virtual void blank (double duration)
 Make the soundfile be so many seconds of silence.
virtual void blank (double duration)
 Make the soundfile be so many seconds of silence.
virtual int close ()
 Close the soundfile.
virtual int close ()
 Close the soundfile.
virtual void cosineGrain (double centerTimeSeconds, double durationSeconds, double frequencyHz, double amplitude, double phaseOffsetRadians, double pan, bool synchronousPhase=true, bool buffer=false)
 Mix a cosine grain into the soundfile.
virtual int create (std::string filename, int framesPerSecond=44100, int channelsPerFrame=2, int format=SF_FORMAT_WAV|SF_FORMAT_FLOAT)
 Create a new soundfile for writing and/or reading.
virtual int create (std::string filename, int framesPerSecond=44100, int channelsPerFrame=2, int format=SF_FORMAT_WAV|SF_FORMAT_FLOAT)
 Create a new soundfile for writing and/or reading.
virtual void error () const
 Print to stderr any current error status message.
virtual void error () const
 Print to stderr any current error status message.
virtual int getChannelsPerFrame () const
virtual int getChannelsPerFrame () const
virtual int getFormat () const
 See sndfile.h for a descriptive list of format numbers.
virtual int getFormat () const
 See sndfile.h for a descriptive list of format numbers.
virtual int getFrames () const
 Return the number of sample frames in a just opened file, or just after calling updateHeader.
virtual int getFrames () const
 Return the number of sample frames in a just opened file, or just after calling updateHeader.
virtual int getFramesPerSecond () const
virtual int getFramesPerSecond () const
virtual void jonesParksGrain (double centerTimeSeconds, double durationSeconds, double beginningFrequencyHz, double centerFrequencyHz, double centerAmplitude, double centerPhaseOffsetRadians, double pan, bool synchronousPhase=true, bool buffer=false)
 Mix a Gaussian chirp into the soundfile.
virtual int mixFrames (double *inputFrames, int samples, double *mixedFrames)
 Mix one or more samples, from a double array (in C++) or a binary string (in Python), into the existing signal in the soundfile.
virtual int mixFrames (double *inputFrames, int samples, double *mixedFrames)
 Mix one or more samples, from a double array (in C++) or a binary string (in Python), into the existing signal in the soundfile.
virtual void mixGrain ()
 Mix a grain that has already been computed into the soundfile.
virtual int open (std::string filename)
 Open an existing soundfile for reading and/or writing.
virtual int open (std::string filename)
 Open an existing soundfile for reading and/or writing.
virtual int readFrame (double *outputFrame)
 Read one sample frame, and return it in a double array (in C++) or a sequence (in Python).
virtual int readFrame (double *outputFrame)
 Read one sample frame, and return it in a double array (in C++) or a sequence (in Python).
virtual int readFrames (double *outputFrames, int samples)
 Read one or more samples, and return them in a double array (in C++) or a binary string (in Python).
virtual int readFrames (double *outputFrames, int samples)
 Read one or more samples, and return them in a double array (in C++) or a binary string (in Python).
virtual int seek (int frames, int whence=0)
 Position the soundfile read/write pointer at the indicated sample frame.
virtual int seek (int frames, int whence=0)
 Position the soundfile read/write pointer at the indicated sample frame.
virtual double seekSeconds (double seconds, int whence=0)
virtual double seekSeconds (double seconds, int whence=0)
virtual void setChannelsPerFrame (int channelsPerFrame)
virtual void setChannelsPerFrame (int channelsPerFrame)
virtual void setFormat (int format)
 See sndfile.h for a descriptive list of format numbers.
virtual void setFormat (int format)
 See sndfile.h for a descriptive list of format numbers.
virtual void setFramesPerSecond (int framesPerSecond)
virtual void setFramesPerSecond (int framesPerSecond)
 Soundfile ()
 Soundfile ()
virtual void updateHeader ()
 Update the soundfile header with the current file size, RIFF chunks, and so on.
virtual void updateHeader ()
 Update the soundfile header with the current file size, RIFF chunks, and so on.
virtual int writeFrame (double *inputFrame)
 Write one sample frame, from a double array (in C++) or a sequence (in Python).
virtual int writeFrame (double *inputFrame)
 Write one sample frame, from a double array (in C++) or a sequence (in Python).
virtual int writeFrames (double *inputFrames, int samples)
 Write one or more samples, from a double array (in C++) or a binary string (in Python).
virtual int writeFrames (double *inputFrames, int samples)
 Write one or more samples, from a double array (in C++) or a binary string (in Python).
virtual ~Soundfile ()
virtual ~Soundfile ()

Protected Member Functions

virtual void initialize ()
virtual void initialize ()

Private Attributes

Eigen::MatrixXd grainBuffer
Eigen::MatrixXd grainOutput
size_t sampleCount
SF_INFO sf_info
SNDFILE * sndfile
double startTimeSeconds

Detailed Description

Simple, basic read/write access, in sample frames, to PCM soundfiles.

Reads and writes any format, but write defaults to WAV float format. This class is designed for Python wrapping with SWIG. See http://www.mega-nerd.com/libsndfile for more information on the underlying libsndfile library.

Constructor & Destructor Documentation

csound::Soundfile::Soundfile ( )
virtual csound::Soundfile::~Soundfile ( )
virtual
csound::Soundfile::Soundfile ( )
virtual csound::Soundfile::~Soundfile ( )
virtual

Member Function Documentation

virtual void csound::Soundfile::blank ( double  duration)
virtual

Make the soundfile be so many seconds of silence.

virtual void csound::Soundfile::blank ( double  duration)
virtual

Make the soundfile be so many seconds of silence.

virtual int csound::Soundfile::close ( )
virtual

Close the soundfile.

Should be called once for every opened or created soundfile, although the class destructor will automatically close an open soundfile.

virtual int csound::Soundfile::close ( )
virtual

Close the soundfile.

Should be called once for every opened or created soundfile, although the class destructor will automatically close an open soundfile.

virtual void csound::Soundfile::cosineGrain ( double  centerTimeSeconds,
double  durationSeconds,
double  frequencyHz,
double  amplitude,
double  phaseOffsetRadians,
double  pan,
bool  synchronousPhase = true,
bool  buffer = false 
)
virtual

Mix a cosine grain into the soundfile.

If the soundfile is stereo, the grain will be panned. If the synchronousPhase argument is true (the default value), then all grains of the same frequency will have synchronous phases, which can be useful in avoiding certain artifacts. For example, if cosine grains of the same frequency have synchronous phases, they can be overlapped by 1/2 their duration without artifacts to produce a continuous cosine tone.

If the buffer argument is true (the default is false), the grain is mixed into a buffer; this can be used to speed up writing grains that are arrangement in columns. To actually write the grain, call writeGrain().

The algorithm uses an efficient difference equation.

virtual int csound::Soundfile::create ( std::string  filename,
int  framesPerSecond = 44100,
int  channelsPerFrame = 2,
int  format = SF_FORMAT_WAV|SF_FORMAT_FLOAT 
)
virtual

Create a new soundfile for writing and/or reading.

The default soundfile format is WAV PCM float samples at 44100 frames per second, stereo.

virtual int csound::Soundfile::create ( std::string  filename,
int  framesPerSecond = 44100,
int  channelsPerFrame = 2,
int  format = SF_FORMAT_WAV|SF_FORMAT_FLOAT 
)
virtual

Create a new soundfile for writing and/or reading.

The default soundfile format is WAV PCM float samples at 44100 frames per second, stereo.

virtual void csound::Soundfile::error ( ) const
virtual

Print to stderr any current error status message.

virtual void csound::Soundfile::error ( ) const
virtual

Print to stderr any current error status message.

virtual int csound::Soundfile::getChannelsPerFrame ( ) const
virtual
virtual int csound::Soundfile::getChannelsPerFrame ( ) const
virtual
virtual int csound::Soundfile::getFormat ( ) const
virtual

See sndfile.h for a descriptive list of format numbers.

virtual int csound::Soundfile::getFormat ( ) const
virtual

See sndfile.h for a descriptive list of format numbers.

virtual int csound::Soundfile::getFrames ( ) const
virtual

Return the number of sample frames in a just opened file, or just after calling updateHeader.

virtual int csound::Soundfile::getFrames ( ) const
virtual

Return the number of sample frames in a just opened file, or just after calling updateHeader.

virtual int csound::Soundfile::getFramesPerSecond ( ) const
virtual
virtual int csound::Soundfile::getFramesPerSecond ( ) const
virtual
virtual void csound::Soundfile::initialize ( )
protectedvirtual
virtual void csound::Soundfile::initialize ( )
protectedvirtual
virtual void csound::Soundfile::jonesParksGrain ( double  centerTimeSeconds,
double  durationSeconds,
double  beginningFrequencyHz,
double  centerFrequencyHz,
double  centerAmplitude,
double  centerPhaseOffsetRadians,
double  pan,
bool  synchronousPhase = true,
bool  buffer = false 
)
virtual

Mix a Gaussian chirp into the soundfile.

If the soundfile is stereo, the grain will be panned. If the synchronousPhase argument is true (the default value), then all grains of the same frequency will have synchronous phases, which can be useful in avoiding certain artifacts.

If the buffer argument is true (the default is false), the grain is mixed into a buffer; this can be used to speed up writing grains that are arrangement in columns. To actually write the grain, call writeGrain().

The algorithm uses an efficient difference equation.

virtual int csound::Soundfile::mixFrames ( double *  inputFrames,
int  samples,
double *  mixedFrames 
)
virtual

Mix one or more samples, from a double array (in C++) or a binary string (in Python), into the existing signal in the soundfile.

The arrays or the strings must contain as many elements as there are samples (channels times frames) Channels are interleaved within frames. For efficiency, there is no checking of bounds or type in Python; the string must contain binary Float64.

virtual int csound::Soundfile::mixFrames ( double *  inputFrames,
int  samples,
double *  mixedFrames 
)
virtual

Mix one or more samples, from a double array (in C++) or a binary string (in Python), into the existing signal in the soundfile.

The arrays or the strings must contain as many elements as there are samples (channels times frames) Channels are interleaved within frames. For efficiency, there is no checking of bounds or type in Python; the string must contain binary Float64.

virtual void csound::Soundfile::mixGrain ( )
virtual

Mix a grain that has already been computed into the soundfile.

virtual int csound::Soundfile::open ( std::string  filename)
virtual

Open an existing soundfile for reading and/or writing.

virtual int csound::Soundfile::open ( std::string  filename)
virtual

Open an existing soundfile for reading and/or writing.

virtual int csound::Soundfile::readFrame ( double *  outputFrame)
virtual

Read one sample frame, and return it in a double array (in C++) or a sequence (in Python).

The array or the sequence must already contain as many elements as there are channels. For efficiency, there is no bounds checking.

virtual int csound::Soundfile::readFrame ( double *  outputFrame)
virtual

Read one sample frame, and return it in a double array (in C++) or a sequence (in Python).

The array or the sequence must already contain as many elements as there are channels. For efficiency, there is no bounds checking.

virtual int csound::Soundfile::readFrames ( double *  outputFrames,
int  samples 
)
virtual

Read one or more samples, and return them in a double array (in C++) or a binary string (in Python).

The array or the string must already contain as many elements as there are samples (channels times frames). Channels are interleaved within frames. For efficiency, there is no bounds checking; on return the string will contain binary Float64. In Python this function is not thread-safe, as a static buffer is used internally.

virtual int csound::Soundfile::readFrames ( double *  outputFrames,
int  samples 
)
virtual

Read one or more samples, and return them in a double array (in C++) or a binary string (in Python).

The array or the string must already contain as many elements as there are samples (channels times frames). Channels are interleaved within frames. For efficiency, there is no bounds checking; on return the string will contain binary Float64. In Python this function is not thread-safe, as a static buffer is used internally.

virtual int csound::Soundfile::seek ( int  frames,
int  whence = 0 
)
virtual

Position the soundfile read/write pointer at the indicated sample frame.

Set whence to 0 for SEEK_SET, 1 for SEEK_CUR, 2 for SEEK_END. Calling with whence = SEEK_CUR and frames = 0 returns the current read/write pointer.

virtual int csound::Soundfile::seek ( int  frames,
int  whence = 0 
)
virtual

Position the soundfile read/write pointer at the indicated sample frame.

Set whence to 0 for SEEK_SET, 1 for SEEK_CUR, 2 for SEEK_END. Calling with whence = SEEK_CUR and frames = 0 returns the current read/write pointer.

virtual double csound::Soundfile::seekSeconds ( double  seconds,
int  whence = 0 
)
virtual
virtual double csound::Soundfile::seekSeconds ( double  seconds,
int  whence = 0 
)
virtual
virtual void csound::Soundfile::setChannelsPerFrame ( int  channelsPerFrame)
virtual
virtual void csound::Soundfile::setChannelsPerFrame ( int  channelsPerFrame)
virtual
virtual void csound::Soundfile::setFormat ( int  format)
virtual

See sndfile.h for a descriptive list of format numbers.

virtual void csound::Soundfile::setFormat ( int  format)
virtual

See sndfile.h for a descriptive list of format numbers.

virtual void csound::Soundfile::setFramesPerSecond ( int  framesPerSecond)
virtual
virtual void csound::Soundfile::setFramesPerSecond ( int  framesPerSecond)
virtual
virtual void csound::Soundfile::updateHeader ( )
virtual

Update the soundfile header with the current file size, RIFF chunks, and so on.

virtual void csound::Soundfile::updateHeader ( )
virtual

Update the soundfile header with the current file size, RIFF chunks, and so on.

virtual int csound::Soundfile::writeFrame ( double *  inputFrame)
virtual

Write one sample frame, from a double array (in C++) or a sequence (in Python).

The array or the sequence must contain as many elements as there are channels. For efficiency, there is no checking of bounds or type in Python; the string must contain Floats. In Python this function is not thread-safe, as a static buffer is used internally.

virtual int csound::Soundfile::writeFrame ( double *  inputFrame)
virtual

Write one sample frame, from a double array (in C++) or a sequence (in Python).

The array or the sequence must contain as many elements as there are channels. For efficiency, there is no checking of bounds or type in Python; the string must contain Floats. In Python this function is not thread-safe, as a static buffer is used internally.

virtual int csound::Soundfile::writeFrames ( double *  inputFrames,
int  samples 
)
virtual

Write one or more samples, from a double array (in C++) or a binary string (in Python).

The array or the string must contain as many elements as there are samples (channels times frames) Channels are interleaved within frames. For efficiency, there is no checking of bounds or type in Python; the string must contain binary Float64.

virtual int csound::Soundfile::writeFrames ( double *  inputFrames,
int  samples 
)
virtual

Write one or more samples, from a double array (in C++) or a binary string (in Python).

The array or the string must contain as many elements as there are samples (channels times frames) Channels are interleaved within frames. For efficiency, there is no checking of bounds or type in Python; the string must contain binary Float64.

Field Documentation

Eigen::MatrixXd csound::Soundfile::grainBuffer
private
Eigen::MatrixXd csound::Soundfile::grainOutput
private
size_t csound::Soundfile::sampleCount
private
SF_INFO csound::Soundfile::sf_info
private
SNDFILE * csound::Soundfile::sndfile
private
double csound::Soundfile::startTimeSeconds
private