Metaoscillators to non-aliased sounds

MetaOscil.h

@@ -0,0 +1,231 @@
+/*
+ * MetaOscil.h
+ *
+ * A wrap-up to swap between different oscillators seemlessly, allowing to produce non-aliased sounds by automatically switching between oscillators.
+ *
+ * This file is part of Mozzi.
+ */
+
+#ifndef META_OSCIL_H
+#define META_OSCIL_H
+
+
+#if ARDUINO >= 100
+#include "Arduino.h"
+#else
+#include "WProgram.h"
+#endif
+
+#include "Oscil.h"
+#include "mozzi_fixmath.h"
+
+
+/**
+   MetaOscil is a wrapper for several Oscil. Once constructed it will behave exactly as an Oscil except that it will automatically switch between Oscil depending on the asked frequency. This allows to produce non-aliased sounds by switching between tables with less and less harmonics as the frequency increases.
+*/
+
+
+template<uint16_t NUM_TABLE_CELLS, uint16_t UPDATE_RATE, byte N_OSCIL>
+  class MetaOscil
+
+{
+ public:
+  /** Constructor
+      Declare a MetaOscil containing any number of Oscil pointers. Every Oscil should have the same TABLE_NUM_CELLS and UPDATE_RATE which are also passed in the MetaOscil constructor. 
+      @param N_OSCIL is the number of Oscil contained in the MetaOscil. This cannot be changed after construction. */ 
+  template<class... T>  MetaOscil(Oscil<NUM_TABLE_CELLS, UPDATE_RATE>* first, T*... elements):oscillators{first, elements...} {
+    current_osc=oscillators[0];};
+
+  MetaOscil(){};
+
+  /* Add one oscil to the MetaOscil.
+      @param osc is a pointer toward an Oscil
+      @param cutoff_freq is the cutoff frequency of this Oscil 
+  void addOscil(Oscil<NUM_TABLE_CELLS, UPDATE_RATE>* osc, int cutoff_freq)
+  {
+    oscillators[current_rank] = osc;
+    cutoff_freqs[current_rank] = cutoff_freq;
+    if (current_rank == 0) current_osc=oscillators[0];
+    current_rank += 1;
+  }*/
+
+
+  /** Set all Oscil of a MetaOscil.
+      @param first... is a list of pointers towards several Oscil */ 
+  template<typename ... T >  void setOscils(Oscil<NUM_TABLE_CELLS, UPDATE_RATE>* first,T... elements)
+    {
+      oscillators[current_rank]=first;
+      if (current_rank == 0) current_osc=oscillators[0];
+      current_rank+=1;
+      setOscils(elements...);
+      current_rank = 0;
+    }
+
+  void setOscils(){};
+
+
+  /** Set all the cutoff frequencies for changing between Oscil. They have to be sorted in increasing values and contain at least N_OSCIL-1 values. Note that the last Oscil will be used by default for frequencies higher than the higher cutoff, hence the last value can be discarded.
+      @param first, elements... a set of int cutoff frequencies.*/
+  template<typename ... T >  void setCutoffFreqs(int first,T... elements)
+    {
+      cutoff_freqs[current_rank]=first;
+      current_rank+=1;
+      setCutoffFreqs(elements...);
+      current_rank = 0;
+    }
+
+  void setCutoffFreqs() {};
+
+  /** Set or change the cutoff frequency of one Oscil.
+      @param rank is the rank of the Oscil.
+      @param freq is the cutoff frequency. */
+  void setCutoffFreq(int freq, byte rank)
+  {
+    cutoff_freqs[rank] = freq;
+  }
+
+  /** Updates the phase according to the current frequency and returns the sample at the new phase position.
+      @return the next sample.
+  */
+  inline
+    int8_t next() {return current_osc->next();}
+
+  /** Change the sound table which will be played by the Oscil of rank.
+      @param TABLE_NAME is the name of the array in the table ".h" file you're using.
+      @param rank is the Oscil.*/
+  void setTable(const int8_t * TABLE_NAME, byte rank) {oscillators[rank]->setTable(TABLE_NAME);}
+
+
+  /** Set the phase of the currently playing Oscil.
+      @param phase a position in the wavetable.*/
+  void setPhase(unsigned int phase) {current_osc->setPhase(phase);}
+
+
+  /** Set the phase of the currently playing Oscil in fractional format.
+      @param phase a position in the wavetable.*/
+  void setPhaseFractional(unsigned long phase) {current_osc->setPhaseFractional(phase);}
+
+
+  /** Get the phase of the currently playin Oscil in fractional format.
+      @return position in the wavetable, shifted left by OSCIL_F_BITS (which is 16 when this was written).
+  */
+  unsigned long getPhaseFractional() {return current_osc->getPhaseFractional();}
+
+
+
+  /** Returns the next sample given a phase modulation value.
+      @param phmod_proportion a phase modulation value given as a proportion of the wave. The
+      phmod_proportion parameter is a Q15n16 fixed-point number where the fractional
+      n16 part represents almost -1 to almost 1, modulating the phase by one whole table length in
+      each direction.
+      @return a sample from the table.*/
+  inline
+    int8_t phMod(Q15n16 phmod_proportion) {return current_osc->phMod(phmod_proportion);}
+
+
+  /** Set the MetaOsc frequency with an unsigned int.
+      @param frequency to play the wave table.*/
+  inline
+    void setFreq(int frequency, bool apply = true)
+  {
+    if (frequency < cutoff_freqs[0])  //getting out the extreme cases
+      {
+	oscillators[0]->setPhaseFractional(current_osc->getPhaseFractional());
+	current_osc = oscillators[0];
+	current_osc->setFreq(frequency);
+      }
+
+    else if (frequency > cutoff_freqs[N_OSCIL-1])
+      {	    
+	oscillators[N_OSCIL-1]->setPhaseFractional(current_osc->getPhaseFractional());
+	current_osc = oscillators[N_OSCIL-1];
+	current_osc->setFreq(frequency);      
+      }
+    else  // dichotomic search
+      {
+	byte low_point = 0, high_point = N_OSCIL-1, mid_point = (N_OSCIL-1)>>1;
+	while(low_point != high_point)
+	  {
+	    if (frequency > cutoff_freqs[mid_point]) low_point = mid_point+1;
+	    else if (frequency < cutoff_freqs[mid_point]) high_point = mid_point;
+	    else
+	      {
+		break;
+	      }
+	    mid_point = (low_point + high_point)>>1;
+	  }
+	oscillators[mid_point]->setPhaseFractional(current_osc->getPhaseFractional());
+	current_osc = oscillators[mid_point];
+	if (apply) current_osc->setFreq(frequency);      
+      }
+
+  }
+
+
+  /** Set the MetaOsc frequency with a float.
+      @param frequency to play the wave table.*/
+  inline
+    void setFreq(float frequency)
+  {
+    setFreq((int) frequency, false);
+    current_osc->setFreq(frequency);    
+  }
+
+
+  /** Set the MetaOsc frequency with a Q24n8 fixed-point number format.
+      @param frequency to play the wave table.*/
+  inline
+    void setFreq_Q24n8(Q24n8 frequency)
+  {
+    setFreq((int) (frequency>>8), false);
+    current_osc->setFreq_Q24n8(frequency);
+  }
+
+
+  /** Set the MetaOsc frequency with a Q16n16 fixed-point number format.
+      @param frequency to play the wave table.*/
+  inline
+    void setFreq_Q16n16(Q16n16 frequency)
+  {
+    setFreq((int) (frequency>>16), false);
+    current_osc->setFreq_Q16n16(frequency);
+  }
+
+
+  /**  Returns the sample at the given table index of the current Oscil.
+       @param index between 0 and the table size.The
+       index rolls back around to 0 if it's larger than the table size.
+       @return the sample at the given table index.
+  */
+  inline
+    int8_t atIndex(unsigned int index) {return current_osc->atIndex(index);}
+
+
+  /** phaseIncFromFreq() and setPhaseInc() are for saving processor time when sliding between frequencies.
+      @param frequency for which you want to calculate a phase increment value.
+      @return the phase increment value which will produce a given frequency.*/
+  inline
+    unsigned long phaseIncFromFreq(int frequency) {return current_osc->phaseIncFromFreq(frequency);}
+
+  /** Set a specific phase increment.
+      @param phaseinc_fractional a phase increment value as calculated by phaseIncFromFreq().
+  */
+  inline
+    void setPhaseInc(unsigned long phaseinc_fractional) {current_osc->setPhaseInc(phaseinc_fractional);}
+
+
+
+ private:
+  Oscil<NUM_TABLE_CELLS, UPDATE_RATE> * oscillators[N_OSCIL];
+  Oscil<NUM_TABLE_CELLS, UPDATE_RATE> * current_osc = NULL;
+  int cutoff_freqs[N_OSCIL];
+  byte current_rank = 0;
+
+};
+
+/**
+@example 06.Synthesis/NonAlias_MetaOscil/NonAlias_MetaOscil.ino
+This example demonstrates the Meta_Oscil class.
+*/
+
+#endif  /* META_OSCIL_H */

examples/06.Synthesis/NonAlias_MetaOscil/NonAlias_MetaOscil.ino

@@ -0,0 +1,121 @@
+/*  Example using a MetaOscil to generate an alias free square wave on a sweep
+    using Mozzi sonification library.
+
+    Waveforms which are not only sines (Saw, square, triangle) are composed by a lot of harmonics which are at frequencies multiple of the fundamental frequency.
+    If the frequency of one of these harmonics is higher than half the sampling frequency (https://en.wikipedia.org/wiki/Nyquist_frequency) (AUDIO_RATE/2 here)
+    it will create "aliases" (https://en.wikipedia.org/wiki/Aliasing) which will sound out of tune are they not harmonically related to the fundamental.
+    The higher the pitch, the more harmonics are above the Nyquist limit and the more aliased will be present for a given waveform. 
+
+    One way to avoid aliases is to use "band-limited" waveforms which have a limited sets of harmonics in order to avoid them to reach the Nyquist limit.
+    As these waveforms are band-limited they will sound less "crunchy" if they are used at frequencies lower than what they are meant to be because they 
+    lack the high frequency contents.
+
+    In order to paliate that, a common technique is to "swap" wave tables on the fly in order to keep the frequency content up to the Nyquist frequency but
+    not above. This is the principal usage of MetaOscil.
+
+    MetaOscil can be used (after construction) as a proper Oscil but really is a bunch of oscillators with only one playing.
+    It will switch between different oscils seemlessly depending on the asked frequency. This allows to switch between oscillators with less 
+    and less harmonics as the pitch goes up, in order to avoid aliases, which is demonstrated by this example.
+
+    The bandlimited tables are nammed according to the max frequency they can play without bringing aliases at a given frequency. For example:
+    square_max_90_at_16384_512_int8.h ensures that no aliases will be present up to 90Hz at 16384Hz sampling rate (the default for Arduino).
+    If your sampling rate is higher (say 32768 which is the default for most 32bits platforms) this table will be able to play up to 
+    180=90*2Hz without aliases, as the Nyquist frequency is two times higher.
+
+    Circuit: Audio output on digital pin 9 on a Uno or similar, or
+    DAC/A14 on Teensy 3.1, or
+    check the README or http://sensorium.github.com/Mozzi/
+
+    Mozzi documentation/API
+		https://sensorium.github.io/Mozzi/doc/html/index.html
+
+		Mozzi help/discussion/announcements:
+    https://groups.google.com/forum/#!forum/mozzi-users
+
+    Tim Barrass 2012, Combriat T. 2021, CC by-nc-sa.
+*/
+
+#include <MozziGuts.h>
+#include <Oscil.h> // oscillator template
+#include <MetaOscil.h>
+
+// All the tables used for the MetaOscil need to be included
+#include <tables/BandLimited_SQUARE/512/square_max_90_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 90Hz at a sampling frequency of 16384 (or 180Hz at a sampling frequency of 32768Hz)
+#include <tables/BandLimited_SQUARE/512/square_max_101_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 101Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_122_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 122Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_138_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 138Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_154_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 154Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_174_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 174Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_210_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 210Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_264_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 264Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_327_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 327Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_431_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 431Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_546_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 546Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_744_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 744Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_910_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 910Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_1170_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 1170Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_1638_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 1638Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_2730_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 2730Hz at a sampling frequency of 16384
+#include <tables/BandLimited_SQUARE/512/square_max_8192_at_16384_512_int8.h>  // band limited table that guarantee no alias up to a frequency of 8192Hz at a sampling frequency of 16384 (this is basically a sine wave)
+
+// The proper Oscillators that will be managed by the MetaOscil
+// use: Oscil <table_size, update_rate> oscilName (wavetable), look in .h file of table #included above
+Oscil <SQUARE_MAX_90_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq90(SQUARE_MAX_90_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_101_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq101(SQUARE_MAX_101_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_122_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq122(SQUARE_MAX_122_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_138_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq138(SQUARE_MAX_138_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_154_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq154(SQUARE_MAX_154_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_174_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq174(SQUARE_MAX_174_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_210_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq210(SQUARE_MAX_210_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_264_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq264(SQUARE_MAX_264_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_327_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq327(SQUARE_MAX_327_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_431_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq431(SQUARE_MAX_431_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_546_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq546(SQUARE_MAX_546_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_744_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq744(SQUARE_MAX_744_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_910_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq910(SQUARE_MAX_910_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_1170_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq1170(SQUARE_MAX_1170_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_1638_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq1638(SQUARE_MAX_1638_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_2730_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq2730(SQUARE_MAX_2730_AT_16384_512_DATA);
+Oscil <SQUARE_MAX_8192_AT_16384_512_NUM_CELLS, AUDIO_RATE> aSq8192(SQUARE_MAX_8192_AT_16384_512_DATA);
+
+// use: MetaOscil <table_size, update_rate, number_of_oscil> MetaoscilName. All oscils used should have the same table_size and **have to be put in increasing order of cutoff_frequencies**.
+MetaOscil<SQUARE_MAX_90_AT_16384_512_NUM_CELLS, AUDIO_RATE, 16> BL_aSq {&aSq90, &aSq101, &aSq122, &aSq138, &aSq154, &aSq174, &aSq210, &aSq264, &aSq327, &aSq431, &aSq546, &aSq744, &aSq1170, &aSq1638, &aSq2730, &aSq8192};
+
+
+// use #define for CONTROL_RATE, not a constant
+#define CONTROL_RATE 256 // Hz, powers of 2 are most reliable
+
+int freq = 10;
+
+
+void setup() {
+  // Set the cutoff frequencies for all the Oscil in the MetaOscil ie at which frequency the MetaOscil will switch to the next Oscillator. Note that these are the same frequencies than the tables names in this case.
+  // This have to follow the order given at the MetaOscil creation: this needs to be in increasing order.
+  BL_aSq.setCutoffFreqs(90, 101, 122, 138, 154, 174, 210, 264, 327, 431, 546, 744, 1170, 1638, 2730, 8192);
+
+  // Cutoff frequencies can also be set or changed individually.
+  BL_aSq.setCutoffFreq(3000, 14);
+  startMozzi(CONTROL_RATE);
+}
+
+
+void updateControl() {
+  // Manually increasing the frequency by 1Hz
+  freq += 1;
+  if (freq > 3000) freq = 10;
+
+  aSq90.setFreq(freq);
+  BL_aSq.setFreq(freq);  //BL_aSq which is a metaOscil can be used just as a regular Oscil.
+}
+
+
+AudioOutput_t updateAudio() {
+  //return MonoOutput::from8Bit(aSq90.next());  // try to use this line instead to hear the non-band limited version, sounds a bit like a radio
+  return MonoOutput::from8Bit(BL_aSq.next());  // return a sample of the correct oscil to acheive no alias
+
+}
+
+
+void loop() {
+  audioHook(); // required here
+}

keywords.txt

@@ -372,8 +372,15 @@ setPDEnv	KEYWORD2
 update	KEYWORD2
 next	KEYWORD2
 
+MetaOscil	KEYWORD1
+setCutoffFreqs	KEYWORD2
+setCutoffFreq	KEYWORD2
+addOscil	KEYWORD2
+addOscils	KEYWORD2
+
 WaveFolder	KEYWORD1
 setHighLimit	KEYWORD2
 setLowLimit	KEYWORD2
 setLimits	KEYWORD2
 next	KEYWORD2
+