Technical Documentation Overview
The documentation for the Inharmonicity Tuner is currently under construction. This means that there may be incomplete sections, errors, omissions, or other issues with the content of this report. If you find any issues with this report, please do not hesitate to submit an edit request at the marigin of the page or contact the team.
The Inharmonicity Tuner is a piano tuning application that uses real-time DSP techniques to analyze the harmonic content of piano notes, calculate the inharmonicity constant of each note, and generate a custom tuning curve for the piano. This project is meant to not only be a practical professional tool for piano technicians but also an educational resource for those interested in practical DSP techniques applied to audio processing.
Although the README covers the high level overview of the project and its software architecture, this document will dive deep into the technical mathematics and algorithms of the project. This is a non-introductory document and assumes a basic understanding of digital signal processing and mathematics.
Mathematical Prerequisites
Before diving into the technical details of the project, it is important to have a solid understanding of the mathematical concepts that underpin the algorithms used in the project. However, if one is familiar but not proficient in these topics, the language and interactability of this document should allow one to intuit the concepts. Generally the fields of mathematics this project draws from are Linear Systems Theory and Difference Equations. Specifically we will be covering:
- FIR and IIR Filters
- Z-Transforms
- Discrete Fourier Transforms
- Autocorrelation
Project Overview
As brief overview the project’s real-time audio processing pipeline is broken down into the following threads:
- The Audio Stream
- The Audio Processing Pipeline
- The Tuner Worker Thread
- The UI Thread
We will only be covering the first three of these in this document as the UI thread is not relevant to the purpose of this document.
Audio Stream
The audio stream is responsible for capturing audio from the microphone and sending it to the audio processing pipeline. This simplicity ensures that the audio stream is not a bottleneck in the audio processing pipeline. It performs no signal processing with the exception of DC blocking, which is necessary to prevent DC offset from corrupting the audio processing pipeline.
Gatekeeper Audio Processing Pipeline
The Gatekeeper acts as the primary signal validator and “traffic cop” for the real-time audio processing pipeline
Its primary function is to evaluate a continuous stream of audio through a strict 5-state machine, successfully isolating clean, stable harmonic tones from environmental silence and chaotic percussive transients.
State 0: IDLE (Silence Gating) The pipeline measures the smoothed amplitude (RMS + EMA) of the frame. If the energy falls below a dynamically calibrated environmental noise floor, the signal is classified as Silence and processing halts.
State 1: ATTACK (Transient Detection) Moving into the frequency domain, the pipeline uses Complex Spectral Difference (CSD) to detect instantaneous spectral changes. This identifies the chaotic burst of energy caused by a physical hammer strike.
State 2: TRANSIENT (Bypass Delay) Following a strike, the signal is highly inharmonic. The pipeline enters a hard delay (counted in frames) to wait for the physical broadband noise to decay, classifying the signal as Unstable.
State 3: HARMONIC DECAY (Stability) Once the transient clears, the pipeline uses the NINOS2 sparsity metric to evaluate the spectrum. The audio must maintain a concentrated, peak-heavy harmonic structure for a required number of consecutive frames before it is officially classified as Stable.
State 4: RELEASE (Capture & Dispatch) Upon achieving stability, the pipeline triggers a capture sequence. It counts frames until it either exceeds a maximum threshold (roughly 1.5 seconds of audio) or the signal is no longer classified as Stable. Once the capture sequence is complete, the pipeline dispatches the captured buffer to a background worker for heavy analysis, and resets its internal counters.