README.md

A portable guitar training tool & DIY kit.
^{Written in Rust & built with Ratatui}

---

Learning how to play guitar with a TUI - hence "Tuitar".

Tuitar is a terminal-based guitar training tool that runs standalone on ESP32 hardware.
Available as a DIY kit, see the firmware and hardware sections for more details.

• Jump to the features ➡️
• Read the Hackster.io article about the project 📰

Table of Contents

• Promo Video
• Launch & Live Demo
• Try it out!
• Features
  • Tuning
  • Fretboard Tracking
  • Signal Analysis
    • Waveform
    • Spectrum
• UI
  • Input modes
  • FPS
• Controls
  • Global
  • Fretboard
  • Frequency/Spectrum/Waveform
• Old Demos
• License & Contributions
• Copyright

Promo Video

▶️ https://www.youtube.com/watch?v=tZm7cLaHAR0

Launch & Live Demo

Tuitar was presented for the first time at Rust Forge Conference in New Zealand.

▶️ https://www.youtube.com/watch?v=es48dmNWMVQ&t=29905s

Try it out!

Tuitar was originally designed to run in the terminal.

So you can install the binary here:

cargo install tuitar --locked

And run it with:

tuitar

If you want the full experience, you can also build the kit, which looks like this:

Features

Tuning

Tuitar offers real-time visualizations from an input source which can be used for tuning your guitar or other instruments.

The frequency graph above shows the detected frequency of the input sound. When a fundamental frequency is detected, the closest musical note is being displayed with the respective cents with a bar at the top.

Also, the dots next to the displayed note indicate the distance to the perfect note in cents (left/red for flat, right/green for sharp).

When the displayed note is green and the bar is centered, it means that the input sound is perfectly in tune with that note.

Fretboard Tracking

Tuitar can track the notes you play on your guitar in real-time and display them on a virtual fretboard.

The default (live) mode shows the currently pressed strings and frets:

One fun thing you can do is to switch to random mode which is a small game where you get points by playing the correct notes shown on the screen. There is a timer and a score counter at the top.

The song mode is also available which shows the notes of a pre-loaded song. It's useful for learning riffs, solos or any melody.

The scale mode also helps with learning scales.

The available scales are:

• Major and Minor
• Pentatonic (Major and Minor)
• Blues
• Mixolydian
• Dorian
• Lydian

You can also press the mode and menu buttons to toggle the root note. (See controls for more information.)

In every fretboard mode, turning the control knob will change the focused region of the fretboard. This is useful for practicing scales or riffs in different positions. Unison is also supported, so you can play the same note on different strings and it will be highlighted on the fretboard.

Signal Analysis

If you need additional information about the input signal, you can use the waveform and spectrum graphs.

Waveform

Shows the raw audio signal over time. You can change the focused region in the chart by turning the knob. It is especially useful for debugging the input since the y-axis is simply shows a voltage from 0 to 3.3V.

Click to see the demo

Spectrum

Shows the frequency spectrum of the input signal. Especially useful for dB measurements and debugging the input. The x-axis is frequency in Hz while the y-axis is the amplitude in dB.

Click to see the demo

UI

Input modes

Tuitar currently supports 2 input modes:

1. Microphone input
2. Jack input (6.35mm)

Press the mode button to switch between the input modes. The current mode is displayed at the left bottom corner of the screen. ([M] or [J])

FPS

The current FPS is being shown on the right bottom corner of the screen.

Controls

Tuitar has a simple control scheme with 2 buttons and 2 knobs. The controls are context-sensitive, meaning they change their function based on the current tab.

Global

Control	Action	Function
Gain knob	Turn	Adjust input gain (jack sensitivity)

Fretboard

Control	Action	Function
Mode button	Short press	Switch fretboard mode (Live ↔ Random ↔ Scales ↔ Song)
Mode button	Long press	Switch input mode (Mic ↔ Jack)
Menu button	Short press	Go to the next tab
Menu button	Long press	Change scale
Mode + Menu	Short press	Toggle root note or song
Ctrl knob	Turn	Scroll fretboard

Frequency/Spectrum/Waveform

Control	Action	Function
Mode button	Short press	Switch input mode (Mic ↔ Jack)
Menu button	Short press	Go to the next tab
Ctrl knob	Turn	Scroll frequency chart

It only supports pitch detection and fretboard tracking for now, but you can use it to practice your guitar skills without the hardware.

Old Demos

Here are some demos from the development phase.

Tuitar running on ESP32 T-Display:

With jack input:

License & Contributions

This project can be used under the terms of the Apache-2.0 or MIT licenses. Contributions to this project, unless noted otherwise, are automatically licensed under the terms of both of those licenses.

🦀 ノ( º _ º ノ) - respect crables!

Feel free to open issues or PRs for improvements, bug fixes, or ideas!

Copyright

Copyright © 2025, Orhun Parmaksız