Options for wide tuning change

[juanotto]

I am helping with JJazlab, a Java app that uses fluidsynth (listed in the apps page using fluidsynth). We want to allow fine tuning fluidsynth (everything) to different frequencies.

For background check:

• I started reading Fluidsynth master fine tune #807 it should be possible using RPN
• Also, in a page linked there https://github.com/FluidSynth/fluidsynth/wiki/FluidFeatures#sysex-messages it seems sysex for tuning are supported
• the code for sysex shows midi note tune & midi note tune bank are supported https://github.com/FluidSynth/fluidsynth/blob/b8fb6c81e1ca27c0bba2f6a0168832214f91d497/src/midi/fluid_midi.h#L199-204
• I also read a bunch of docs, youtube videos, code, etc. I am new to MIDI in general so I was expecting that...

So, two simple questions:

• should wide tuning changes be possible with either Sysex OR RPN messages?
• if both are possible, are there reasons to prefer one over the other?

And one broad question:

• are there examples of the kind of hex messages needed for this? I found some references for Sysex tunnig, but not much for RPN. If it exists, some similar to this https://www.synthfont.com/SysEx.txt would be ideal. We call fluidsynth through an integration that sees the data array which, if I understand it correctly, are the bytes of the sysex message (not including 0xF0 and 0xF7, as per API docs). That would mean if we send the right bytes, the magic happens!

Thanks for an awesome lib and sorry for the lengthy post 🥲

I don't want to follow the code just yet if I can (I may get to that eventually) https://github.com/FluidSynth/fluidsynth/blob/master/src/synth/fluid_synth.c#L2119

[syntaro]

Will it help?

Im making java app wrapper for use fluidsynth.

https://star-advance.org/dx/use-fluid-synth/

So I am writing comment with SmartPhone today.
excuse me. I can't reprint code section at the moment. Please check url.

[juanotto]

A bit, it gives me more context but not a lot more. I see you are using https://www.fluidsynth.org/api/group__tuning.html#ga3a9f995c967a9a227f9603ff57ee2304 in your native-lib.cpp L252, which is the one I suspected can be used for this. Can you confirm that it works?

I'm trying to figure out what the midi message contents would be. I have been trying to follow the format in the published MIDI Tuning specification here -> https://midi.org/midi-tuning-updated-specification

[syntaro]

hello juanotto. And yes I am using it in our Android App.

And I think it seems working with User custom tuning by User Interface.

But, some another handling code in this page does not need for newer FluidSynth.so.

Best regards.

[derselbst]

Disclaimer: Fluidsynth's tuning implementation is entirely legacy code. It's that part of the codebase that I've successfully avoided dealing with for the past 11 years I've been dealing with fluidsynth already. There are no tests and barely any documentation. I never used it myself, as I don't have a use case for it. I'm still hoping for that day when someone comes up with some "real-world" use cases / examples / documentation. Regarding you questions:

should wide tuning changes be possible with either Sysex OR RPN messages?
if both are possible, are there reasons to prefer one over the other?

I'd say it depends on your use-case:

• The RPN approach allows you to mess with the (coarse / fine) tuning of a MIDI channel (without accounting for which preset is assigned to that channel). And it allows you to fluid_synth_activate_tuning for a particular bank / prog combination. This effectively seems to create and "memorize" the tuning for that bank / prog (no idea how this could be useful, because RPN doesn't allow you to actually tune the tuning...). Here's the code:

fluidsynth/src/synth/fluid_synth.c

Lines 1949 to 1973 in 3f28690

	case RPN_PITCH_BEND_RANGE: /* Set bend range in semitones plus cents */
	fluid_channel_set_pitch_wheel_sensitivity(synth->channel[channum], msb_value + lsb_value / 100.0f); /* 0-127 maps to 0-100 cents */
	fluid_synth_update_pitch_wheel_sens_LOCAL(synth, channum); /* Update bend range */
	break;
	case RPN_CHANNEL_FINE_TUNE: /* Fine tune is 14 bit over +/-1 semitone (+/- 100 cents, 8192 = center) */
	fluid_synth_set_gen_LOCAL(synth, channum, GEN_FINETUNE,
	(float)(data - 8192) * (100.0f / 8192.0f));
	break;
	case RPN_CHANNEL_COARSE_TUNE: /* Coarse tune is 7 bit and in semitones (64 is center) */
	fluid_synth_set_gen_LOCAL(synth, channum, GEN_COARSETUNE,
	msb_value - 64);
	break;
	case RPN_TUNING_PROGRAM_CHANGE:
	fluid_channel_set_tuning_prog(chan, msb_value);
	fluid_synth_activate_tuning(synth, channum,
	fluid_channel_get_tuning_bank(chan),
	msb_value, TRUE);
	break;
	case RPN_TUNING_BANK_SELECT:
	fluid_channel_set_tuning_bank(chan, msb_value);
	break;

• The SysEx approach in addition grants you access to fluid_synth_tune_notes() and fluid_synth_activate_octave_tuning(). I.e. with those you can tune the tuning. It is implemented in this... beautiful function:

fluidsynth/src/synth/fluid_synth.c

Lines 2211 to 2500 in 3f28690

	static int
	fluid_synth_sysex_midi_tuning(fluid_synth_t *synth, const char *data, int len,
	char *response, int *response_len, int avail_response,
	int *handled, int dryrun)
	{
	int realtime, msgid;
	int bank = 0, prog, channels;
	double tunedata[128];
	int keys[128];
	char name[17]={0};
	int note, frac, frac2;
	uint8_t chksum;
	int i, count, index;
	const char *dataptr;
	char *resptr;;
	realtime = data[0] == MIDI_SYSEX_UNIV_REALTIME;
	msgid = data[3];
	switch(msgid)
	{
	case MIDI_SYSEX_TUNING_BULK_DUMP_REQ:
	case MIDI_SYSEX_TUNING_BULK_DUMP_REQ_BANK:
	if(data[3] == MIDI_SYSEX_TUNING_BULK_DUMP_REQ)
	{
	if(len != 5 || data[4] & 0x80 || !response)
	{
	return FLUID_OK;
	}
	*response_len = 406;
	prog = data[4];
	}
	else
	{
	if(len != 6 || data[4] & 0x80 || data[5] & 0x80 || !response)
	{
	return FLUID_OK;
	}
	*response_len = 407;
	bank = data[4];
	prog = data[5];
	}
	if(dryrun)
	{
	if(handled)
	{
	*handled = TRUE;
	}
	return FLUID_OK;
	}
	if(avail_response < *response_len)
	{
	return FLUID_FAILED;
	}
	/* Get tuning data, return if tuning not found */
	if(fluid_synth_tuning_dump(synth, bank, prog, name, 17, tunedata) == FLUID_FAILED)
	{
	*response_len = 0;
	return FLUID_OK;
	}
	resptr = response;
	*resptr++ = MIDI_SYSEX_UNIV_NON_REALTIME;
	*resptr++ = synth->device_id;
	*resptr++ = MIDI_SYSEX_MIDI_TUNING_ID;
	*resptr++ = MIDI_SYSEX_TUNING_BULK_DUMP;
	if(msgid == MIDI_SYSEX_TUNING_BULK_DUMP_REQ_BANK)
	{
	*resptr++ = bank;
	}
	*resptr++ = prog;
	/* copy 16 ASCII characters (potentially not null terminated) to the sysex buffer */
	FLUID_MEMCPY(resptr, name, 16);
	resptr += 16;
	for(i = 0; i < 128; i++)
	{
	note = tunedata[i] / 100.0;
	fluid_clip(note, 0, 127);
	frac = ((tunedata[i] - note * 100.0) * 16384.0 + 50.0) / 100.0;
	fluid_clip(frac, 0, 16383);
	*resptr++ = note;
	*resptr++ = frac >> 7;
	*resptr++ = frac & 0x7F;
	}
	if(msgid == MIDI_SYSEX_TUNING_BULK_DUMP_REQ)
	{
	/* NOTE: Checksum is not as straight forward as the bank based messages */
	chksum = MIDI_SYSEX_UNIV_NON_REALTIME ^ MIDI_SYSEX_MIDI_TUNING_ID
	^ MIDI_SYSEX_TUNING_BULK_DUMP ^ prog;
	for(i = 21; i < 128 * 3 + 21; i++)
	{
	chksum ^= response[i];
	}
	}
	else
	{
	for(i = 1, chksum = 0; i < 406; i++)
	{
	chksum ^= response[i];
	}
	}
	*resptr++ = chksum & 0x7F;
	if(handled)
	{
	*handled = TRUE;
	}
	break;
	case MIDI_SYSEX_TUNING_NOTE_TUNE:
	case MIDI_SYSEX_TUNING_NOTE_TUNE_BANK:
	dataptr = data + 4;
	if(msgid == MIDI_SYSEX_TUNING_NOTE_TUNE)
	{
	if(len < 10 || data[4] & 0x80 || data[5] & 0x80 || len != data[5] * 4 + 6)
	{
	return FLUID_OK;
	}
	}
	else
	{
	if(len < 11 || data[4] & 0x80 || data[5] & 0x80 || data[6] & 0x80
	|| len != data[6] * 4 + 7)
	{
	return FLUID_OK;
	}
	bank = *dataptr++;
	}
	if(dryrun)
	{
	if(handled)
	{
	*handled = TRUE;
	}
	return FLUID_OK;
	}
	prog = *dataptr++;
	count = *dataptr++;
	for(i = 0, index = 0; i < count; i++)
	{
	note = *dataptr++;
	if(note & 0x80)
	{
	return FLUID_OK;
	}
	keys[index] = note;
	note = *dataptr++;
	frac = *dataptr++;
	frac2 = *dataptr++;
	if(note & 0x80 || frac & 0x80 || frac2 & 0x80)
	{
	return FLUID_OK;
	}
	frac = frac << 7 | frac2;
	/* No change pitch value? Doesn't really make sense to send that, but.. */
	if(note == 0x7F && frac == 16383)
	{
	continue;
	}
	tunedata[index] = note * 100.0 + (frac * 100.0 / 16384.0);
	index++;
	}
	if(index > 0)
	{
	if(fluid_synth_tune_notes(synth, bank, prog, index, keys, tunedata,
	realtime) == FLUID_FAILED)
	{
	return FLUID_FAILED;
	}
	}
	if(handled)
	{
	*handled = TRUE;
	}
	break;
	case MIDI_SYSEX_TUNING_OCTAVE_TUNE_1BYTE:
	case MIDI_SYSEX_TUNING_OCTAVE_TUNE_2BYTE:
	if((msgid == MIDI_SYSEX_TUNING_OCTAVE_TUNE_1BYTE && len != 19)
	|| (msgid == MIDI_SYSEX_TUNING_OCTAVE_TUNE_2BYTE && len != 31))
	{
	return FLUID_OK;
	}
	if(data[4] & 0x80 || data[5] & 0x80 || data[6] & 0x80)
	{
	return FLUID_OK;
	}
	if(dryrun)
	{
	if(handled)
	{
	*handled = TRUE;
	}
	return FLUID_OK;
	}
	channels = (data[4] & 0x03) << 14 | data[5] << 7 | data[6];
	if(msgid == MIDI_SYSEX_TUNING_OCTAVE_TUNE_1BYTE)
	{
	for(i = 0; i < 12; i++)
	{
	frac = data[i + 7];
	if(frac & 0x80)
	{
	return FLUID_OK;
	}
	tunedata[i] = (int)frac - 64;
	}
	}
	else
	{
	for(i = 0; i < 12; i++)
	{
	frac = data[i * 2 + 7];
	frac2 = data[i * 2 + 8];
	if(frac & 0x80 || frac2 & 0x80)
	{
	return FLUID_OK;
	}
	tunedata[i] = (((int)frac << 7 | (int)frac2) - 8192) * (200.0 / 16384.0);
	}
	}
	if(fluid_synth_activate_octave_tuning(synth, 0, 0, "SYSEX",
	tunedata, realtime) == FLUID_FAILED)
	{
	return FLUID_FAILED;
	}
	if(channels)
	{
	for(i = 0; i < 16; i++)
	{
	if(channels & (1 << i))
	{
	fluid_synth_activate_tuning(synth, i, 0, 0, realtime);
	}
	}
	}
	if(handled)
	{
	*handled = TRUE;
	}
	break;
	}
	return FLUID_OK;
	}

In addition, fluidsynth provides a few more tuning functions, which are only usable via API (or builtin shell):

Function	Accessible via API	via Shell	via RPN	via SysEx
fluid_synth_activate_key_tuning	✔️	✔️	❌	❌
fluid_synth_activate_octave_tuning	✔️	❌	❌	✔️
fluid_synth_activate_tuning	✔️	✔️	✔️	✔️
fluid_synth_deactivate_tuning	✔️	✔️	❌	❌
fluid_synth_tune_notes	✔️	✔️	❌	✔️
fluid_synth_tuning_dump	✔️	✔️	❌	✔️

Whether you need those functions really depends on your use case. E.g. if you're happy with the default 12-tone well-tempered tuning, but just want to pitch beyond what the pitch wheel allows, using RPN Coarse / Fine Tune is probably sufficient. Otherwise, you need to figure it out. Consider asking Copilot to help you understand the mentioned code snippets.

are there examples of the kind of hex messages needed for this?

Not to my knowledge. IMO, only use SysEx or RPN messages if you really have to. Otherwise, you should consider calling those functions directly via the API, rather than having to deal with all that hex clutter.

Hope that help, good luck.

[juanotto]

Hey @derselbst , I read your answer but didn't have time to get back to this and didn't thank you as deserved!

Awesome info, I'll be back to this soon, I saved it as reference for what I need.