diff --git a/OB-Xd.jucer b/OB-Xd.jucer index bad2f72..bda5540 100644 --- a/OB-Xd.jucer +++ b/OB-Xd.jucer @@ -1,6 +1,6 @@ - + + + + @@ -69,6 +74,7 @@ + tunedMidiNote(midiIndx); + //portamento on osc input voltage //implements rc circuit - float ptNote =tptlpupw(prtst, midiIndx-81, porta * (1+PortaDetune*PortaDetuneAmt),sampleRateInv); + float ptNote = tptlpupw(prtst, tunedMidiNote - 81, porta * (1+PortaDetune*PortaDetuneAmt),sampleRateInv); osc.notePlaying = ptNote; //both envelopes and filter cv need a delay equal to osc internal delay float lfoDelayed = lfod.feedReturn(lfoIn); diff --git a/Source/Engine/Tuning.h b/Source/Engine/Tuning.h new file mode 100644 index 0000000..6d3a693 --- /dev/null +++ b/Source/Engine/Tuning.h @@ -0,0 +1,80 @@ +// +// Tuning.h +// OB-Xd +// +// Created by Natalia Escalera on 12/28/21. +// Copyright © 2021 discoDSP. All rights reserved. +// + +#include "../MTS/libMTSClient.h" + +#pragma once + +class Tuning +{ +private: + MTSClient* mts_client{nullptr}; + enum Mode { + MTS_ESP, + TWELVE_TET + } mode{TWELVE_TET}; + +public: + Tuning() + { + + } + ~Tuning() + { + if (mts_client != nullptr) + { + MTS_DeregisterClient(mts_client); + mts_client = nullptr; + } + } + + void updateMTSESPStatus() + { + if (mts_client == nullptr) + { + mts_client = MTS_RegisterClient(); + } + + mode = hasMTSMaster() ? MTS_ESP : TWELVE_TET; + } + + double midiNoteFromMTS(int midiIndex) + { + return midiIndex + MTS_RetuningInSemitones(mts_client, midiIndex, -1); + } + + double tunedMidiNote(int midiIndex) + { + switch(mode) + { + case TWELVE_TET: + return midiIndex; + break; + case MTS_ESP: + return midiNoteFromMTS(midiIndex); + break; + } + return midiIndex; + } + + /* + These methods can be later be used for implementing other steps in the MTS-ESP guide: + https://github.com/ODDSound/MTS-ESP/blob/main/Client/libMTSClient.h + */ + + bool hasMTSMaster() + { + return MTS_HasMaster(mts_client); + } + + const char *getMTSScale() + { + return MTS_GetScaleName(mts_client); + } + +}; diff --git a/Source/MTS/libMTSClient.cpp b/Source/MTS/libMTSClient.cpp new file mode 100755 index 0000000..2655e35 --- /dev/null +++ b/Source/MTS/libMTSClient.cpp @@ -0,0 +1,390 @@ +/* +Copyright (C) 2021 by ODDSound Ltd. info@oddsound.com + +Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF +THIS SOFTWARE. +*/ + +#include "libMTSClient.h" +#include +#if defined(WIN32) || defined(_WIN32) || defined(__WIN32__) || defined(__NT__) || defined(__TOS_WIN__) || defined(_MSC_VER) +#define MTS_ESP_WIN +#define WIN32_LEAN_AND_MEAN +#include +typedef HRESULT (WINAPI* SHGetKnownFolderPathFunc) (const GUID*,DWORD,HANDLE,PWSTR*); +typedef void (WINAPI* CoTaskMemFreeFunc) (LPVOID); +#else +#include +#endif + +const static double ln2=0.693147180559945309417; +const static double ratioToSemitones=17.31234049066756088832; // 12./log(2.) +typedef void (*mts_void)(void); +typedef bool (*mts_bool)(void); +typedef bool (*mts_bcc)(char,char); +typedef const double *(*mts_cd)(void); +typedef const double *(*mts_cdc)(char); +typedef bool (*mts_bc)(char); +typedef const char *(*mts_pcc)(void); + +struct mtsclientglobal +{ + mtsclientglobal() : RegisterClient(0), DeregisterClient(0), HasMaster(0), ShouldFilterNote(0), ShouldFilterNoteMultiChannel(0), GetTuning(0), GetMultiChannelTuning(0), UseMultiChannelTuning(0), GetScaleName(0), esp_retuning(0), handle(0) + { + for (int i=0;i<128;i++) iet[i]=1./(440.*pow(2.,(i-69.)/12.)); + load_lib(); + if (GetTuning) esp_retuning=GetTuning(); + for (int i=0;i<16;i++) multi_channel_esp_retuning[i]=GetMultiChannelTuning?GetMultiChannelTuning(static_cast(i)):0; + } + virtual inline bool isOnline() const {return esp_retuning && HasMaster && HasMaster();} + + mts_void RegisterClient,DeregisterClient;mts_bool HasMaster;mts_bcc ShouldFilterNote,ShouldFilterNoteMultiChannel;mts_cd GetTuning;mts_cdc GetMultiChannelTuning;mts_bc UseMultiChannelTuning;mts_pcc GetScaleName; // Interface to lib + double iet[128];const double *esp_retuning;const double *multi_channel_esp_retuning[16]; // tuning tables + +#ifdef MTS_ESP_WIN + virtual void load_lib() + { + SHGetKnownFolderPathFunc SHGetKnownFolderPath=0; + CoTaskMemFreeFunc CoTaskMemFree=0; + HMODULE shell32Module=GetModuleHandleW(L"Shell32.dll"); + HMODULE ole32Module=GetModuleHandleW(L"Ole32.dll"); + if (shell32Module) SHGetKnownFolderPath=(SHGetKnownFolderPathFunc)GetProcAddress(shell32Module,"SHGetKnownFolderPath"); + if (ole32Module) CoTaskMemFree=(CoTaskMemFreeFunc)GetProcAddress(ole32Module,"CoTaskMemFree"); + if (SHGetKnownFolderPath && CoTaskMemFree) + { + const GUID FOLDERID_ProgramFilesCommonGUID={0xF7F1ED05,0x9F6D,0x47A2,0xAA,0xAE,0x29,0xD3,0x17,0xC6,0xF0,0x66}; + PWSTR cf=NULL; + if (SHGetKnownFolderPath(&FOLDERID_ProgramFilesCommonGUID,0,0,&cf)>=0) + { + WCHAR buffer[MAX_PATH];buffer[0]=L'\0'; + if (cf) wcsncpy(buffer,cf,MAX_PATH); + CoTaskMemFree(cf); + buffer[MAX_PATH-1]=L'\0'; + const WCHAR *libpath=L"\\MTS-ESP\\LIBMTS.dll"; + DWORD cfLen=wcslen(buffer); + wcsncat(buffer,libpath,MAX_PATH-cfLen-1); + if (!(handle=LoadLibraryW(buffer))) return; + } + else {CoTaskMemFree(cf);return;} + } + else return; + RegisterClient =(mts_void) GetProcAddress(handle,"MTS_RegisterClient"); + DeregisterClient =(mts_void) GetProcAddress(handle,"MTS_DeregisterClient"); + HasMaster =(mts_bool) GetProcAddress(handle,"MTS_HasMaster"); + ShouldFilterNote =(mts_bcc) GetProcAddress(handle,"MTS_ShouldFilterNote"); + ShouldFilterNoteMultiChannel =(mts_bcc) GetProcAddress(handle,"MTS_ShouldFilterNoteMultiChannel"); + GetTuning =(mts_cd) GetProcAddress(handle,"MTS_GetTuningTable"); + GetMultiChannelTuning =(mts_cdc) GetProcAddress(handle,"MTS_GetMultiChannelTuningTable"); + UseMultiChannelTuning =(mts_bc) GetProcAddress(handle,"MTS_UseMultiChannelTuning"); + GetScaleName =(mts_pcc) GetProcAddress(handle,"MTS_GetScaleName"); + } + virtual ~mtsclientglobal() {if (handle) FreeLibrary(handle);} + HINSTANCE handle; +#else + virtual void load_lib() + { + if (!(handle=dlopen("/Library/Application Support/MTS-ESP/libMTS.dylib",RTLD_NOW)) && + !(handle=dlopen("/usr/local/lib/libMTS.so",RTLD_NOW))) return; + RegisterClient =(mts_void) dlsym(handle,"MTS_RegisterClient"); + DeregisterClient =(mts_void) dlsym(handle,"MTS_DeregisterClient"); + HasMaster =(mts_bool) dlsym(handle,"MTS_HasMaster"); + ShouldFilterNote =(mts_bcc) dlsym(handle,"MTS_ShouldFilterNote"); + ShouldFilterNoteMultiChannel =(mts_bcc) dlsym(handle,"MTS_ShouldFilterNoteMultiChannel"); + GetTuning =(mts_cd) dlsym(handle,"MTS_GetTuningTable"); + GetMultiChannelTuning =(mts_cdc) dlsym(handle,"MTS_GetMultiChannelTuningTable"); + UseMultiChannelTuning =(mts_bc) dlsym(handle,"MTS_UseMultiChannelTuning"); + GetScaleName =(mts_pcc) dlsym(handle,"MTS_GetScaleName"); + } + virtual ~mtsclientglobal() {if (handle) dlclose(handle);} + void *handle; +#endif +}; + +static mtsclientglobal global; + +struct MTSClient +{ + MTSClient() : tuningName("12-TET"), supportsNoteFiltering(false), supportsMultiChannelNoteFiltering(false), supportsMultiChannelTuning(false), freqRequestReceived(false), supportsMTSSysex(false) + { + for (int i=0;i<128;i++) retuning[i]=440.*pow(2.,(i-69.)/12.); + if (global.RegisterClient) global.RegisterClient(); + } + virtual ~MTSClient() {if (global.DeregisterClient) global.DeregisterClient();} + bool hasMaster() {return global.isOnline();} + inline double freq(char midinote,char midichannel) + { + freqRequestReceived=true; + supportsMultiChannelTuning=!(midichannel&~15); + if (!global.isOnline()) return retuning[midinote&127]; + if ((!supportsNoteFiltering || supportsMultiChannelNoteFiltering) && supportsMultiChannelTuning && global.UseMultiChannelTuning && global.UseMultiChannelTuning(midichannel) && global.multi_channel_esp_retuning[midichannel&15]) + { + return global.multi_channel_esp_retuning[midichannel&15][midinote&127]; + } + return global.esp_retuning[midinote&127]; + } + inline double ratio(char midinote,char midichannel) + { + freqRequestReceived=true; + supportsMultiChannelTuning=!(midichannel&~15); + if (!global.isOnline()) return supportsMTSSysex?retuning[midinote&127]*global.iet[midinote&127]:1.; + if ((!supportsNoteFiltering || supportsMultiChannelNoteFiltering) && supportsMultiChannelTuning && global.UseMultiChannelTuning && global.UseMultiChannelTuning(midichannel) && global.multi_channel_esp_retuning[midichannel&15]) + { + return global.multi_channel_esp_retuning[midichannel&15][midinote&127]*global.iet[midinote&127]; + } + return global.esp_retuning[midinote&127]*global.iet[midinote&127]; + } + inline double semitones(char midinote,char midichannel) + { + freqRequestReceived=true; + supportsMultiChannelTuning=!(midichannel&~15); + if (!global.isOnline()) return supportsMTSSysex?ratioToSemitones*log(retuning[midinote&127]*global.iet[midinote&127]):0.; + if ((!supportsNoteFiltering || supportsMultiChannelNoteFiltering) && supportsMultiChannelTuning && global.UseMultiChannelTuning && global.UseMultiChannelTuning(midichannel) && global.multi_channel_esp_retuning[midichannel&15]) + { + return ratioToSemitones*log(global.multi_channel_esp_retuning[midichannel&15][midinote&127]*global.iet[midinote&127]); + } + return ratioToSemitones*log(global.esp_retuning[midinote&127]*global.iet[midinote&127]); + } + inline bool shouldFilterNote(char midinote,char midichannel) + { + supportsNoteFiltering=true; + supportsMultiChannelNoteFiltering=!(midichannel&~15); + if (!freqRequestReceived) supportsMultiChannelTuning=supportsMultiChannelNoteFiltering; // assume it supports multi channel tuning until a request is received for a frequency and can verify + if (!global.isOnline()) return false; + if (supportsMultiChannelNoteFiltering && supportsMultiChannelTuning && global.UseMultiChannelTuning && global.UseMultiChannelTuning(midichannel)) + { + return global.ShouldFilterNoteMultiChannel?global.ShouldFilterNoteMultiChannel(midinote&127,midichannel):false; + } + return global.ShouldFilterNote?global.ShouldFilterNote(midinote&127,midichannel):false; + } + inline char freqToNote(double freq,char midichannel) + { + bool online=global.isOnline(),multiChannel=false; + const double *freqs=online?global.esp_retuning:retuning; + if (online && !(midichannel&~15) && global.UseMultiChannelTuning && global.UseMultiChannelTuning(midichannel) && global.multi_channel_esp_retuning[midichannel]) + { + freqs=global.multi_channel_esp_retuning[midichannel]; + multiChannel=true; + } + int iLower,iUpper;iLower=0;iUpper=0; + double dLower,dUpper;dLower=0;dUpper=0; + for (int i=0;i<128;i++) + { + if (online) + { + if (multiChannel && global.ShouldFilterNoteMultiChannel && global.ShouldFilterNoteMultiChannel(static_cast(i),midichannel)) continue; + else if (global.ShouldFilterNote && global.ShouldFilterNote(static_cast(i),midichannel)) continue; + } + double d=freqs[i]-freq; + if (d==0.) return static_cast(i); + if (d<0) {if (dLower==0. || d>dLower) {dLower=d;iLower=i;}} + else if (dUpper==0. || d(iUpper); + if (dUpper==0. || iLower==iUpper) return static_cast(iLower); + double fmid=freqs[iLower]*pow(2.,0.5*(log(freqs[iUpper]/freqs[iLower])/ln2)); + return freq(iLower):static_cast(iUpper); + } + inline char freqToNote(double freq,char *midichannel) + { + if (!midichannel) return freqToNote(freq,static_cast(-1)); + if (global.isOnline() && global.UseMultiChannelTuning) + { + int channelsInUse[16];int nMultiChannels=0; + for (int i=0;i<16;i++) if (global.UseMultiChannelTuning(i) && global.multi_channel_esp_retuning[i]) channelsInUse[nMultiChannels++]=i; + if (nMultiChannels) + { + const int nFreqs=128*nMultiChannels; + int iLower,iUpper,channel,note;iLower=0;iUpper=0;channel=0;note=0; + double dLower,dUpper;dLower=0;dUpper=0; + for (int i=0;i>7];note=i&127; + if (global.ShouldFilterNoteMultiChannel && global.ShouldFilterNoteMultiChannel(static_cast(note),static_cast(channel))) continue; + double d=global.multi_channel_esp_retuning[channel][note]-freq; + if (d==0.) {*midichannel=static_cast(channel);return static_cast(note);} + if (d<0) {if (dLower==0. || d>dLower) {dLower=d;iLower=i;}} + else if (dUpper==0. || d(channelsInUse[iUpper>>7]);return static_cast(iUpper&127);} + if (dUpper==0. || iLower==iUpper) {*midichannel=static_cast(channelsInUse[iLower>>7]);return static_cast(iLower&127);} + double fLower=global.multi_channel_esp_retuning[channelsInUse[iLower>>7]][iLower&127]; + double fUpper=global.multi_channel_esp_retuning[channelsInUse[iUpper>>7]][iUpper&127]; + double fmid=fLower*pow(2.,0.5*(log(fUpper/fLower)/ln2)); + if (freq(channelsInUse[iLower>>7]);return static_cast(iLower&127);} + *midichannel=static_cast(channelsInUse[iUpper>>7]);return static_cast(iUpper&127); + } + } + *midichannel=static_cast(0); + return freqToNote(freq,static_cast(0)); + } + inline void parseMIDIData(const unsigned char *buffer,int len) + { + supportsMTSSysex=true; + int sysex_ctr=0,sysex_value=0,note=0,numTunings=0; + /*int bank=-1,prog=0,checksum=0,deviceID=0;short int channelBitmap=0;bool realtime=false;*/ // unused for now + eSysexState state=eIgnoring;eMTSFormat format=eBulk; + for (int i=0;i0x7F && b!=0xF0) continue; + switch (state) + { + case eIgnoring: + if (b==0xF0) state=eMatchingSysex; + break; + case eMatchingSysex: + sysex_ctr=0; + if (b==0x7E) state=eSysexValid; + else if (b==0x7F) {/*realtime=true;*/state=eSysexValid;} + else state=eIgnoring; + break; + case eSysexValid: + switch (sysex_ctr++) // handle device ID + { + case 0: /*deviceID=b;*/ break; + case 1: if (b==0x08) state=eMatchingMTS; break; + default: state=eIgnoring; break; // it's not an MTS message + } + break; + case eMatchingMTS: + sysex_ctr=0; + switch (b) + { + case 0: format=eRequest;state=eMatchingProg; break; + case 1: format=eBulk;state=eMatchingProg; break; + case 2: format=eSingle;state=eMatchingProg; break; + case 3: format=eRequest;state=eMatchingBank; break; + case 4: format=eBulk;state=eMatchingBank; break; + case 5: format=eScaleOctOneByte;state=eMatchingBank; break; + case 6: format=eScaleOctTwoByte;state=eMatchingBank; break; + case 7: format=eSingle;state=eMatchingBank; break; + case 8: format=eScaleOctOneByteExt;state=eMatchingChannel; break; + case 9: format=eScaleOctTwoByteExt;state=eMatchingChannel; break; + default: state=eIgnoring; break; // it's not a valid MTS format + } + break; + case eMatchingBank: + /*bank=b;*/ + state=eMatchingProg; + break; + case eMatchingProg: + /*prog=b;*/ + if (format==eSingle) state=eNumTunings;else {state=eTuningName;tuningName[0]='\0';} + break; + case eTuningName: + tuningName[sysex_ctr]=static_cast(b); + if (++sysex_ctr>=16) {tuningName[16]='\0';sysex_ctr=0;state=eTuningData;} + break; + case eNumTunings: + numTunings=b;sysex_ctr=0;state=eTuningData; + break; + case eMatchingChannel: + switch (sysex_ctr++) + { + case 0: /*for (int j=14;j<16;j++) channelBitmap|=(1<>14)&127,(sysex_value&16383)/16383.); + sysex_value=0;sysex_ctr++; + if (++note>=128) state=eCheckSum; + } + break; + case eSingle: + sysex_value=(sysex_value<<7)|b; + sysex_ctr++; + if (!(sysex_ctr&3)) + { + if (!(note==0x7F && sysex_value==16383)) updateTuning((sysex_value>>21)&127,(sysex_value>>14)&127,(sysex_value&16383)/16383.); + sysex_value=0; + if (++note>=numTunings) state=eIgnoring; + } + break; + case eScaleOctOneByte: case eScaleOctOneByteExt: + for (int j=sysex_ctr;j<128;j+=12) updateTuning(j,j,(static_cast(b)-64.)*0.01); + if (++sysex_ctr>=12) state=format==eScaleOctOneByte?eCheckSum:eIgnoring; + break; + case eScaleOctTwoByte: case eScaleOctTwoByteExt: + sysex_value=(sysex_value<<7)|b; + sysex_ctr++; + if (!(sysex_ctr&1)) + { + double detune=(static_cast(sysex_value&16383)-8192.)/(sysex_value>8192?8191.:8192.); + for (int j=note;j<128;j+=12) updateTuning(j,j,detune); + if (++note>=12) state=format==eScaleOctTwoByte?eCheckSum:eIgnoring; + } + break; + default: state=eIgnoring; break; + } + break; + case eCheckSum: + /*checksum=b;*/ + state=eIgnoring; + break; + } + } + } + inline void updateTuning(int note,int retuneNote,double detune) + { + if (note<0 || note>127 || retuneNote<0 || retuneNote>127) return; + retuning[note]=440.*pow(2.,((retuneNote+detune)-69.)/12.); + } + const char *getScaleName() {return global.isOnline() && global.GetScaleName?global.GetScaleName():tuningName;} + + enum eSysexState {eIgnoring=0,eMatchingSysex,eSysexValid,eMatchingMTS,eMatchingBank,eMatchingProg,eMatchingChannel,eTuningName,eNumTunings,eTuningData,eCheckSum}; + enum eMTSFormat {eRequest=0,eBulk,eSingle,eScaleOctOneByte,eScaleOctTwoByte,eScaleOctOneByteExt,eScaleOctTwoByteExt}; + + double retuning[128]; + char tuningName[17]; + bool supportsNoteFiltering,supportsMultiChannelNoteFiltering,supportsMultiChannelTuning,freqRequestReceived,supportsMTSSysex; +}; + +static char freqToNoteET(double freq) +{ + static double freqs[128];static bool init=false; + if (!init) {for (int i=0;i<128;i++) freqs[i]=440.*pow(2.,(i-69.)/12.);init=true;} + if (freq<=freqs[0]) return 0; + if (freq>=freqs[127]) return 127; + int mid=0;int n=-1;int n2=-1; + for (int first=0,last=127;freq!=freqs[(mid=first+(last-first)/2)];(freqlast) + { + if (!mid) {n=mid;break;} + if (mid>127) mid=127; + n=mid-((freq-freqs[mid-1])<(freqs[mid]-freq)); + break; + } + if (n==-1) {if (freq==freqs[mid]) n=mid;else return 60;} + if (!n) n2=1; + else if (n==127) n2=126; + else n2=n+1*(fabs(freqs[n-1]-freq)(n):static_cast(n2); +} + +// Exported functions: +MTSClient* MTS_RegisterClient() {return new MTSClient;} +void MTS_DeregisterClient(MTSClient* c) {delete c;} +bool MTS_HasMaster(MTSClient* c) {return c?c->hasMaster():false;} +bool MTS_ShouldFilterNote(MTSClient* c,char midinote,char midichannel) {return c?c->shouldFilterNote(midinote&127,midichannel):false;} +double MTS_NoteToFrequency(MTSClient* c,char midinote,char midichannel) {return c?c->freq(midinote,midichannel):(1./global.iet[midinote&127]);} +double MTS_RetuningAsRatio(MTSClient* c,char midinote,char midichannel) {return c?c->ratio(midinote,midichannel):1.;} +double MTS_RetuningInSemitones(MTSClient* c,char midinote,char midichannel) {return c?c->semitones(midinote,midichannel):0.;} +char MTS_FrequencyToNote(MTSClient *c,double freq,char midichannel) {return c?c->freqToNote(freq,midichannel):freqToNoteET(freq);} +char MTS_FrequencyToNoteAndChannel(MTSClient *c,double freq,char *midichannel) {if (c) return c->freqToNote(freq,midichannel);if (midichannel) *midichannel=0;return freqToNoteET(freq);} +const char *MTS_GetScaleName(MTSClient *c) {return c?c->getScaleName():"";} +void MTS_ParseMIDIDataU(MTSClient *c,const unsigned char *buffer,int len) {if (c) c->parseMIDIData(buffer,len);} +void MTS_ParseMIDIData(MTSClient *c,const char *buffer,int len) {if (c) c->parseMIDIData(reinterpret_cast(buffer),len);} + diff --git a/Source/MTS/libMTSClient.h b/Source/MTS/libMTSClient.h new file mode 100755 index 0000000..c8e3b79 --- /dev/null +++ b/Source/MTS/libMTSClient.h @@ -0,0 +1,161 @@ +/* +Copyright (C) 2021 by ODDSound Ltd. info@oddsound.com + +Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF +THIS SOFTWARE. +*/ + +#ifndef libMTSClient_h +#define libMTSClient_h + +#ifdef __cplusplus +extern "C" { +#endif + + /* + Steps for using the MTS-ESP client API to add microtuning support to a plug-in. + Steps 1 and 2 are required, however it is recommended to include further steps when + integrating: + + + 1. REQUIRED: Register and de-register a plug-in instance as a client with MTS-ESP. + On startup in the plug-in constructor call: + + MTSClient *client = MTS_RegisterClient(); + + Store the returned MTSClient pointer to supply when calling other MTS-ESP client API + functions. On shutdown in the plug-in destructor call: + + MTS_DeregisterClient(client); + + + 2. REQUIRED: Query retuning when a note-on message is received and adjust tuning accordingly. + When given a note call: + + double freq = MTS_NoteToFrequency(client, midinote, midichannel); + OR + double retune_semitones = MTS_RetuningInSemitones(client, midinote, midichannel); + OR + double retune_ratio = MTS_RetuningAsRatio(client, midinote, midichannel); + + MIDI channel arguments should use the range [0,15] however if you don’t know the MIDI + channel, use -1 (see step 6 for more on MIDI channels). + + + 3. RECOMMENDED: Continuously query retuning whilst a note is held, allowing tuning to change + along the flight of a note. Do this if you can and as often as possible, ideally at the same + time as processing any other pitch modulation sources (envelopes, MIDI controllers, LFOs etc.). + + + 4. RECOMMENDED: Provide an option to the user to select whether tuning is queried at note-on + only, as in step 2, or continuously, as in step 3. There are creative and practical + advantages to both, depending on the use case, and offering an option to the user will + provide the most useful MTS-ESP integration. If not offering such an option, continuous + retuning should be preferred over note-on only retuning. + + + 5. RECOMMENDED: Query whether a note should be sounded when a note-on message is received. + The Scala .kbm keyboard mapping format allows for MIDI keys to be unmapped i.e. no frequency + is specified for them, and the MTS-ESP library supports this too. You can query whether a note + is unmapped and should be ignored with: + + bool should_ignore_note = MTS_ShouldFilterNote(client, midinote, midichannel); + + If this returns true, ignore the note-on and don’t play anything. Calling this function is + recommended but optional and a valid value for frequency/retuning will be returned for an + unmapped note. MIDI channel arguments should use the range [0,15] however if you don’t + know the MIDI channel, use -1. + + + 6. RECOMMENDED: Always supply a MIDI channel when querying retuning or note filtering. Doing + so allows your plug-in to multi-channel tuning tables, useful for microtonal MIDI controllers + with more than 128 keys or working with large scales. Even if multi-channel tables are not + in use, a master may still make use of channel-specific note filtering for functions such as + key switches to change tunings. If your plug-in supports MPE and has a switch for enabling MPE + support, it is recommended to NOT supply a MIDI channel if MPE is enabled. + + + 7. RECOMMENDED: If you are adding MTS-ESP support to a plug-in that already has some kind + of microtuning support, e.g. loading .scl or .tun files, let the local tuning automatically + override MTS-ESP, or provide an option for MTS-ESP retuning to be explicitly disabled. + This affords a user the option to use a different tuning to the global MTS-ESP table + for a specific plug-in instance. + + + 8. OPTIONAL: Add support for MIDI Tuning Standard (or MTS, from the MIDI specification) SysEx + messages to your plug-in. When not connected to an MTS-ESP master plug-in, these can be used + to retune it instead, providing microtuing support even when MTS-ESP is not in use. + When a SysEx message is received, call: + + MTS_ParseMIDIData(client, buffer, len); // if buffer is signed char * + OR + MTS_ParseMIDIDataU(client, buffer, len); // if buffer is unsigned char * + + These will update a local tuning table which is used when querying retuning as in steps 2 + and 3. + + + 9. OPTIONAL: If you want to display to the user whether the plug-in is "connnected" to an + MTS-ESP master plug-in, call: + + bool has_master = MTS_HasMaster(client); + + + 10: OPTIONAL: It is possible to query the name of the current scale. This function is necessarily + supplied for the case where a client is sending MTS SysEx messages, however it can be used + to display the current scale name to the user on your UI too: + + const char *name = MTS_GetScaleName(client); + + + 11: EXTRAS: Helper functions are available which return the MIDI note whose pitch is nearest + a given frequency. The MIDI note returned is guaranteed to be mapped. If you intend to + generate a note-on message using the returned note number, you may already know which MIDI + channel it will be sent on, in which case you must specify this in the call, else the client + library can prescribe a channel for you. This is done so that multi-channel mapping + and note filtering can be respected. See below for further details. + */ + + // Opaque datatype for MTSClient. + typedef struct MTSClient MTSClient; + + // Register/deregister as a client. Call from the plugin constructor and destructor. + extern MTSClient *MTS_RegisterClient(); + extern void MTS_DeregisterClient(MTSClient *client); + + // Check if the client is currently connected to a master plugin. + extern bool MTS_HasMaster(MTSClient *client); + + // Returns true if note should not be played. MIDI channel argument should be included if possible (0-15), else set to -1. + extern bool MTS_ShouldFilterNote(MTSClient *client, char midinote, char midichannel); + + // Retuning a midi note. Pick the version that makes your life easiest! MIDI channel argument should be included if possible (0-15), else set to -1. + extern double MTS_NoteToFrequency(MTSClient *client, char midinote, char midichannel); + extern double MTS_RetuningInSemitones(MTSClient *client, char midinote, char midichannel); + extern double MTS_RetuningAsRatio(MTSClient *client, char midinote, char midichannel); + + // MTS_FrequencyToNote() is a helper function returning the note number whose pitch is closest to the supplied frequency. Two versions are provided: + // The first is for the simplest case: supply a frequency and get a note number back. + // If you intend to use the returned note number to generate a note-on message on a specific, pre-determined MIDI channel, set the midichannel argument to the destination channel (0-15), else set to -1. + // If a MIDI channel is supplied, the corresponding multi-channel tuning table will be queried if in use, else multi-channel tables are ignored. + extern char MTS_FrequencyToNote(MTSClient *client, double freq, char midichannel); + // Use the second version if you intend to use the returned note number to generate a note-on message and where you have the possibility to send it on any MIDI channel. + // The midichannel argument is a pointer to a char which will receive the MIDI channel on which the note message should be sent (0-15). + // Multi-channel tuning tables are queried if in use. + extern char MTS_FrequencyToNoteAndChannel(MTSClient *client, double freq, char *midichannel); + + // Returns the name of the current scale. + extern const char *MTS_GetScaleName(MTSClient *client); + + // Parse incoming MIDI data to update local retuning. All formats of MTS sysex message accepted. + extern void MTS_ParseMIDIDataU(MTSClient *client, const unsigned char *buffer, int len); + extern void MTS_ParseMIDIData(MTSClient *client, const char *buffer, int len); + +#ifdef __cplusplus +} +#endif + +#endif +