What is Gingoduino?

A music theory engine that runs entirely on a microcontroller. Notes, intervals, chords, scales, harmonic fields, fretboard layouts, progressions — all computed in real-time on the chip. No cloud, no latency, no external dependencies.

Feed it MIDI notes, get back chord names, scale degrees, harmonic functions, and predicted next chords. Works on anything from an Arduino Uno to an ESP32-S3.

Why does this exist?

Most music theory tools run on desktop or in the browser. I wanted one that runs inside the instrument itself — a pedal that knows what chord you're playing, a synth that suggests the next chord, a MIDI display that shows scale degrees in real-time.

Gingoduino makes that possible. Pair it with any MIDI input and you get instant musical intelligence on a $3 chip.

What it knows

  • Notes — 12-note chromatic system, enharmonic equivalents, MIDI numbers, frequencies
  • Intervals — all intervals with names, semitone distances, consonance/dissonance
  • Chords — 42 chord formulas, reverse lookup (play notes → get chord name: "Cmaj7", "Dm7b5")
  • Scales — 40+ types including modes, pentatonics, blues, jazz, with signatures and brightness
  • Harmonic Fields — build triads/tetrads from any scale, identify T/S/D functions
  • Harmonic Tree — directed graph of chord progressions (classical + jazz traditions)
  • Progressions — identify, deduce from notes, predict next chord
  • Fretboard — guitar, cavaquinho, bandolim, ukulele with fingering scoring
  • Events & Sequences — musical events with tempo and time signature

Platform Tiers

The library auto-selects what to include based on your hardware:

  • Tier 1 (AVR — Uno, Nano): Note, Interval, Chord
  • Tier 2 (ESP8266): + Scale, Field, Duration, Tempo, TimeSig, Fretboard
  • Tier 3 (ESP32, RP2040, Teensy, Daisy Seed): + Event, Sequence, Tree, Progression

Everything fits. Even an Arduino Uno can identify chords in real-time.

Quick Example

#include <Gingoduino.h>
using namespace gingoduino;

void setup() {
    Serial.begin(9600);

    GingoChord chord("Dm7");
    GingoNote notes[7];
    chord.notes(notes, 7);       // D, F, A, C

    GingoScale scale("C", SCALE_MAJOR);
    Serial.println(scale.signature());  // 0 (no sharps/flats)

    GingoField field("C", SCALE_MAJOR);
    GingoChord triads[7];
    field.chords(triads, 7);     // CM, Dm, Em, FM, GM, Am, Bdim
}

Real-Time Chord Detection

Plug a USB MIDI keyboard into an ESP32-S3 running ESP32_Host_MIDI, feed the notes into Gingoduino, and see chord names appear on a display as you play. The two libraries were designed to work together.

Technical Details

  • Zero-heap architecture — no dynamic allocation, ever
  • PROGMEM lookup tables for chord and scale formulas
  • C++11 compatible (works on AVR)
  • 275 native tests passing
  • Port of gingo (C++17 / Python library)

Installation

  • Arduino IDE: Library Manager → search "Gingoduino" → Install
  • PlatformIO: lib_deps = sauloverissimo/Gingoduino
  • ESP-IDF: idf.py add-dependency "sauloverissimo/gingoduino"

Links

MIT License. v0.1.0 released February 2026.