minidsp.h

Go to the documentation of this file.

#ifndef MINIDSP_H
#define MINIDSP_H
 
/* Version macros — injected by Makefile via -D flags.
 * Defaults here allow the header to compile standalone. */
#ifndef MINIDSP_VERSION_MAJOR
#define MINIDSP_VERSION_MAJOR 0
#endif
#ifndef MINIDSP_VERSION_MINOR
#define MINIDSP_VERSION_MINOR 0
#endif
#ifndef MINIDSP_VERSION_PATCH
#define MINIDSP_VERSION_PATCH 0
#endif
#ifndef MINIDSP_VERSION
#define MINIDSP_VERSION "0.0.0"
#endif
 
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <math.h>
#include <stdbool.h>
 
/* -----------------------------------------------------------------------
 * Error handling
 * -----------------------------------------------------------------------*/

typedef enum {
    MD_ERR_NULL_POINTER  = 1, 
    MD_ERR_INVALID_SIZE  = 2, 
    MD_ERR_INVALID_RANGE = 3, 
    MD_ERR_ALLOC_FAILED  = 4  
} MD_ErrorCode;

typedef void (*MD_ErrorHandler)(MD_ErrorCode code,
                                const char  *func_name,
                                const char  *message);

void MD_set_error_handler(MD_ErrorHandler handler);
 
/* M_PI is not guaranteed by the C standard.  Define it if the system didn't. */
#ifndef M_PI
#define M_PI 3.14159265358979323846
#endif
#include <float.h>
#include <complex.h>
#include <fftw3.h>
 
/* -----------------------------------------------------------------------
 * Basic signal measurement functions
 * -----------------------------------------------------------------------*/

double MD_dot(const double *a, const double *b, unsigned N);

double MD_entropy(const double *a, unsigned N, bool clip);

double MD_energy(const double *a, unsigned N);

double MD_power(const double *a, unsigned N);

double MD_power_db(const double *a, unsigned N);
 
/* -----------------------------------------------------------------------
 * Signal analysis
 * -----------------------------------------------------------------------*/

double MD_rms(const double *a, unsigned N);

double MD_zero_crossing_rate(const double *a, unsigned N);

void MD_autocorrelation(const double *a, unsigned N,
                        double *out, unsigned max_lag);

void MD_peak_detect(const double *a, unsigned N, double threshold,
                    unsigned min_distance, unsigned *peaks_out,
                    unsigned *num_peaks_out);

double MD_f0_autocorrelation(const double *signal, unsigned N,
                             double sample_rate,
                             double min_freq_hz, double max_freq_hz);

double MD_f0_fft(const double *signal, unsigned N,
                 double sample_rate,
                 double min_freq_hz, double max_freq_hz);

void MD_mix(const double *a, const double *b, double *out,
            unsigned N, double w_a, double w_b);
 
/* -----------------------------------------------------------------------
 * Simple effects
 * -----------------------------------------------------------------------*/

void MD_delay_echo(const double *in, double *out, unsigned N,
                   unsigned delay_samples, double feedback,
                   double dry, double wet);

void MD_tremolo(const double *in, double *out, unsigned N,
                double rate_hz, double depth, double sample_rate);

void MD_comb_reverb(const double *in, double *out, unsigned N,
                    unsigned delay_samples, double feedback,
                    double dry, double wet);
 
/* -----------------------------------------------------------------------
 * FIR filters / convolution
 * -----------------------------------------------------------------------*/

unsigned MD_convolution_num_samples(unsigned signal_len, unsigned kernel_len);

void MD_convolution_time(const double *signal, unsigned signal_len,
                         const double *kernel, unsigned kernel_len,
                         double *out);

void MD_moving_average(const double *signal, unsigned signal_len,
                       unsigned window_len, double *out);

void MD_fir_filter(const double *signal, unsigned signal_len,
                   const double *coeffs, unsigned num_taps,
                   double *out);

void MD_convolution_fft_ola(const double *signal, unsigned signal_len,
                            const double *kernel, unsigned kernel_len,
                            double *out);

void MD_design_lowpass_fir(double *coeffs, unsigned num_taps,
                           double cutoff_freq, double sample_rate,
                           double kaiser_beta);
 
/* -----------------------------------------------------------------------
 * Signal scaling and conditioning
 * -----------------------------------------------------------------------*/

double MD_scale(double in,
                double oldmin, double oldmax,
                double newmin, double newmax);

void MD_scale_vec(double *in, double *out, unsigned N,
                  double oldmin, double oldmax,
                  double newmin, double newmax);

void MD_fit_within_range(double *in, double *out, unsigned N,
                         double newmin, double newmax);

void MD_adjust_dblevel(const double *in, double *out,
                       unsigned N, double dblevel);
 
/* -----------------------------------------------------------------------
 * FFT / Spectrum Analysis
 * -----------------------------------------------------------------------*/

void MD_magnitude_spectrum(const double *signal, unsigned N, double *mag_out);

void MD_power_spectral_density(const double *signal, unsigned N, double *psd_out);

void MD_phase_spectrum(const double *signal, unsigned N, double *phase_out);

unsigned MD_stft_num_frames(unsigned signal_len, unsigned N, unsigned hop);

void MD_stft(const double *signal, unsigned signal_len,
             unsigned N, unsigned hop,
             double *mag_out);

void MD_mel_filterbank(unsigned N, double sample_rate,
                       unsigned num_mels,
                       double min_freq_hz, double max_freq_hz,
                       double *filterbank_out);

void MD_mel_energies(const double *signal, unsigned N,
                     double sample_rate, unsigned num_mels,
                     double min_freq_hz, double max_freq_hz,
                     double *mel_out);

void MD_mfcc(const double *signal, unsigned N,
             double sample_rate,
             unsigned num_mels, unsigned num_coeffs,
             double min_freq_hz, double max_freq_hz,
             double *mfcc_out);
 
/* -----------------------------------------------------------------------
 * FFT-based filtering
 * -----------------------------------------------------------------------*/

void MD_lowpass_brickwall(double *signal, unsigned len,
                          double cutoff_hz, double sample_rate);
 
/* -----------------------------------------------------------------------
 * Math utilities
 * -----------------------------------------------------------------------*/

double MD_bessel_i0(double x);

double MD_sinc(double x);
 
/* -----------------------------------------------------------------------
 * Window generation
 * -----------------------------------------------------------------------*/

void MD_Gen_Hann_Win(double *out, unsigned n);

void MD_Gen_Hamming_Win(double *out, unsigned n);

void MD_Gen_Blackman_Win(double *out, unsigned n);

void MD_Gen_Rect_Win(double *out, unsigned n);

void MD_Gen_Kaiser_Win(double *out, unsigned n, double beta);
 
/* -----------------------------------------------------------------------
 * Signal generators
 * -----------------------------------------------------------------------*/

void MD_sine_wave(double *output, unsigned N, double amplitude,
                  double freq, double sample_rate);

void MD_white_noise(double *output, unsigned N, double amplitude,
                    unsigned seed);

void MD_impulse(double *output, unsigned N, double amplitude, unsigned position);

void MD_chirp_linear(double *output, unsigned N, double amplitude,
                     double f_start, double f_end, double sample_rate);

void MD_chirp_log(double *output, unsigned N, double amplitude,
                  double f_start, double f_end, double sample_rate);

void MD_square_wave(double *output, unsigned N, double amplitude,
                    double freq, double sample_rate);

void MD_sawtooth_wave(double *output, unsigned N, double amplitude,
                      double freq, double sample_rate);

void MD_shepard_tone(double *output, unsigned N, double amplitude,
                     double base_freq, double sample_rate,
                     double rate_octaves_per_sec, unsigned num_octaves);
 
/* -----------------------------------------------------------------------
 * DTMF tone detection and generation
 * -----------------------------------------------------------------------
 *
 * Dual-Tone Multi-Frequency (DTMF) signalling encodes each keypad
 * button as a pair of sinusoids -- one from a low-frequency "row" group
 * and one from a high-frequency "column" group:
 *
 *              1209 Hz   1336 Hz   1477 Hz   1633 Hz
 *   697 Hz        1         2         3         A
 *   770 Hz        4         5         6         B
 *   852 Hz        7         8         9         C
 *   941 Hz        *         0         #         D
 *
 * Detection uses frame-based FFT magnitude analysis with a state machine
 * that enforces ITU-T Q.24 minimum timing constraints (40 ms tone-on,
 * 40 ms inter-digit pause).
 */

typedef struct {
    char   digit;     
    double start_s;   
    double end_s;     
} MD_DTMFTone;

unsigned MD_dtmf_detect(const double *signal, unsigned signal_len,
                        double sample_rate,
                        MD_DTMFTone *tones_out, unsigned max_tones);

void MD_dtmf_generate(double *output, const char *digits,
                      double sample_rate,
                      unsigned tone_ms, unsigned pause_ms);

unsigned MD_dtmf_signal_length(unsigned num_digits, double sample_rate,
                               unsigned tone_ms, unsigned pause_ms);
 
/* -----------------------------------------------------------------------
 * Resource cleanup
 * -----------------------------------------------------------------------*/

void MD_shutdown(void);
 
/* -----------------------------------------------------------------------
 * Generalized Cross-Correlation (GCC) for delay estimation
 * -----------------------------------------------------------------------
 *
 * Given two microphone signals that captured the same sound source,
 * GCC-PHAT estimates how many samples one signal is delayed relative
 * to the other.  This is the basis of acoustic source localisation.
 *
 * The algorithm:
 *   1. FFT both signals.
 *   2. Multiply one spectrum by the conjugate of the other (cross-spectrum).
 *   3. Apply a weighting (PHAT normalises by magnitude, sharpening the peak).
 *   4. Inverse-FFT back to the time domain.
 *   5. The position of the peak tells you the delay in samples.
 */

enum MD_GCC_WEIGHTING_TYPE {
    SIMP, 
    PHAT  
};

void MD_get_multiple_delays(const double **sigs, unsigned M, unsigned N,
                            unsigned margin, int weightfunc,
                            int *outdelays);

int MD_get_delay(const double *siga, const double *sigb, unsigned N,
                 double *ent, unsigned margin, int weightfunc);

void MD_gcc(const double *siga, const double *sigb, unsigned N,
            double *lagvals, int weightfunc);
 
/* -----------------------------------------------------------------------
 * Spectrogram text art
 * -----------------------------------------------------------------------*/

unsigned MD_spectrogram_text(double *output, unsigned max_len,
                             const char *text,
                             double freq_lo, double freq_hi,
                             double duration_sec, double sample_rate);
 
/* -----------------------------------------------------------------------
 * Audio steganography
 * -----------------------------------------------------------------------*/

#define MD_STEG_LSB       0
#define MD_STEG_FREQ_BAND 1
#define MD_STEG_SPECTEXT  2

#define MD_STEG_TYPE_TEXT   0
#define MD_STEG_TYPE_BINARY 1

unsigned MD_steg_capacity(unsigned signal_len, double sample_rate, int method);

unsigned MD_steg_encode(const double *host, double *output,
                        unsigned signal_len, double sample_rate,
                        const char *message, int method);

unsigned MD_steg_decode(const double *stego, unsigned signal_len,
                        double sample_rate,
                        char *message_out, unsigned max_msg_len,
                        int method);

unsigned MD_steg_encode_bytes(const double *host, double *output,
                              unsigned signal_len, double sample_rate,
                              const unsigned char *data, unsigned data_len,
                              int method);

unsigned MD_steg_decode_bytes(const double *stego, unsigned signal_len,
                              double sample_rate,
                              unsigned char *data_out, unsigned max_len,
                              int method);

int MD_steg_detect(const double *signal, unsigned signal_len,
                   double sample_rate, int *payload_type_out);
 
/* -----------------------------------------------------------------------
 * Sample rate conversion
 * -----------------------------------------------------------------------*/

unsigned MD_resample_output_len(unsigned input_len,
                                double in_rate, double out_rate);

unsigned MD_resample(const double *input, unsigned input_len,
                     double *output, unsigned max_output_len,
                     double in_rate, double out_rate,
                     unsigned num_zero_crossings, double kaiser_beta);
 
/* -----------------------------------------------------------------------
 * Voice Activity Detection (VAD)
 * -----------------------------------------------------------------------*/

#define MD_VAD_FEAT_ENERGY             0  
#define MD_VAD_FEAT_ZCR                1  
#define MD_VAD_FEAT_SPECTRAL_ENTROPY   2  
#define MD_VAD_FEAT_SPECTRAL_FLATNESS  3  
#define MD_VAD_FEAT_BAND_ENERGY_RATIO  4  
#define MD_VAD_NUM_FEATURES            5  

typedef struct {
    double   weights[MD_VAD_NUM_FEATURES]; 
    double   threshold;        
    unsigned onset_frames;     
    unsigned hangover_frames;  
    double   adaptation_rate;  
    double   band_low_hz;      
    double   band_high_hz;     
} MD_vad_params;

typedef struct {
    MD_vad_params params;                      
    double   feat_min[MD_VAD_NUM_FEATURES];    
    double   feat_max[MD_VAD_NUM_FEATURES];    
    unsigned onset_counter;                    
    unsigned hangover_counter;                 
    int      current_decision;                 
    unsigned frames_processed;                 
} MD_vad_state;

void MD_vad_default_params(MD_vad_params *params);

void MD_vad_init(MD_vad_state *state, const MD_vad_params *params);

void MD_vad_calibrate(MD_vad_state *state, const double *signal,
                      unsigned N, double sample_rate);

int MD_vad_process_frame(MD_vad_state *state, const double *signal,
                         unsigned N, double sample_rate,
                         double *score_out, double *features_out);
 
#endif /* MINIDSP_H */