annotate hssf.h @ 5:5f3c32dc6e17

* Adjust comment syntax to permit Doxygen to generate HTML documentation; add Doxyfile

#ifndef hssfH
#define hssfH

/**
  \file hssf.h - source-filter modeling for harmonic sinusoids

  Further reading: Wen X. and M. Sandler, "Source-filter modeling in sinusoid domain," in Proc. AES 126th
  Convention, Munich, 2009.
*/


#include <stdio.h>
#include "hs.h"

//---------------------------------------------------------------------------
const double Amel=1127.0104803341574386544633680278;
const bool useA0=true; //if true, use A0D+A0C instead of A0C in S-F decomposition as pre-normalizer


/**
  TSF is the class implementing source-filter model for harmonic sinusoids. TSF shares the basic framework
  of the vibrato description class TVo, but implements a more compact source-filter representation. It does
  not go into detailed vibrato analysis such as extraction modulator shape.

  An analysis/synthesis cycle converts THS to TSF and back.
*/

struct TSF
{
	//basic characteristics
	int M;            ///< number of partials
	int L;            ///< number of frames
	int P;            ///< number of segmentation points
	double offst;     ///< hop size
	double* F0C;      ///< [0:L-1] pitch carrier
	double* F0D;      ///< [0:L-1] pitch modulator
  double* logA0C;   ///< [0:L-1] amplitude carreir
  double* logA0D;   ///< [0:L-1] amplitude modulator

	double* lp;       ///< [0:P-1] peak positions

  double F;         ///< filter: band with (linear or mel) associated to each b[][]
  double Fs;        ///< sampling frequency
  int FScaleMode;   ///< linear or mel
  int K;            ///< number of filter bands
  double** b;       ///< [0:L-1][0:M-1] single-frame source, in dB
  double** h;       ///< [0:L-1][0:K+1] single-frame filter, in dB
  double* avgb;     ///< [0:M-1] average source
  double* avgh;     ///< [0:K+1] average filter

	//other properties

  double rate;      ///< vibrato rate
  double regularity;///< vibrato regularity
  double F0max;     ///< maximal fundamental frequency
  double F0min;     ///< minimal fundamental frequency
  double F0Cmax;    ///< maximal fundamental carrier frequency
  double F0Cmin;    ///< minimal fundamental carrier frequency
  double F0Overall; ///< overall average fundamental frequency
  double F0Dmax;    ///< maximal fundamental modulator frequency
  double F0Dmin;    ///< minimal fundamental modulator frequency
  double* F0;       ///< [0:L-1] fundamental frequency
  double* logA0;		///< [0:L-1] log amplitude

	TSF();
	~TSF();

  //copy function
  void Duplicate(TSF& SF);

  //output routines
	double LogAF(double f);
	double LogAF(double f, int fr);
	double LogAS(int m, int fr);

  //memory handling routines
  void AllocateL(int AnL);
	void ReAllocateL(int newL);
	void AllocateP();
	void AllocateSF();

  //I/O routines
	void SaveSFToFileHandle(FILE* f);
	void SaveToFileHandle(FILE* f);
	void LoadSFFromFileHandle(FILE* f);
	void LoadFromFileHandle(FILE* f);
	void SaveToFile(char* filename);

  //other member functions
  void ShiftFilterByDB(double dB);
};

//--tool procedures----------------------------------------------------------
int Sign(double);

//--general source-filter model routines-------------------------------------
void S_F_b(TSF& SF, atom** Partials);

//--slow-variation SF estimation routines------------------------------------
double P2_DelFtr(double** d, int L, int K, double** x, double F);
double P3_DelSrc(double** d, int L, int M, int K, double** x, double** f, double F);
int SF_SV(double** h, int L, int M, int K, double** a, double** f, double F, double theta, double ep, int maxiter);
double S_F_SV(int M, atom** Partials, double* logA0C, double* lp, int P, int& K, double** h, double* avgh, double** b, double* avgb, double F=0.005, int FScaleMode=0, double theta=0.5, double Fs=44100);
void SF_SV_cf(double* h, double** b, int L, int M, int K, double** a, double** f, double F, double ep, int maxiter);
double S_F_SV_cf(int afres, double* LogAF, double* LogAS, int Fr, int M, atom** Partials, double* A0C, double* lp, int P, int& K, double** h, double** b, double F=0.005, int FScaleMode=0, double Fs=44100);

//--filter-bank SF estimation routines---------------------------------------
int SF_FB(double* hl, int M, int K, double** al, double** fl, double F, int LMode);
double S_F_FB(int M, atom** Partials, double* logA0C, double* lp, int P, int& K, double** h, double* avgh, double** b, double* avgb, double F=0.005, int FScaleMode=0, double Fs=44100);

//--source-filter analysis and synthesis routines----------------------------
void AnalyzeSF_1(THS& HS, TSF& SF, double sps, double offst);
void AnalyzeSF_2(THS& HS, TSF& SF, double*& cyclefrs, double*& cyclefs, double sps, int* cyclefrcount=0, int SFMode=0, double SFF=0.01, int SFFScale=0, double SFtheta=0);
void AnalyzeSF(THS& HS, TSF& SF, double*& cyclefrs, double*& cyclefs, double sps, double offst, int* cyclefrcount=0, int SFMode=0, double SFF=0.01, int SFFScale=0, double SFtheta=0);
void SynthesizeSF(THS* HS, TSF* SF, double sps);


#endif