https://github.com/SteveMCWin/ttune
A guitar tuner for your terminal
https://github.com/SteveMCWin/ttune
bubbletea golang lipgloss music tui
Last synced: 3 months ago
JSON representation
A guitar tuner for your terminal
- Host: GitHub
- URL: https://github.com/SteveMCWin/ttune
- Owner: SteveMCWin
- License: mit
- Created: 2026-01-01T17:13:46.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-03-17T23:09:41.000Z (3 months ago)
- Last Synced: 2026-03-18T13:16:07.250Z (3 months ago)
- Topics: bubbletea, golang, lipgloss, music, tui
- Language: Go
- Homepage:
- Size: 3.32 MB
- Stars: 43
- Watchers: 2
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- charm-in-the-wild - tTune - An aesthetic guitar tuner for your terminal. (built with Bubble Tea, Lip Gloss) (Applications / Media)
README
# tTune
tTune is a stylized, extendable, keyboard oriented guitar tuning app right in your terminal!
> **Note:** tTune is still actively developed. Future releases may be incompatible with previous ones due to my lack of foresight. If you cannot run the program after updating, please back up your configuration, delete your ~/.config/ttune directory and try running tTune again.
---
## Showcase
Tuning G string demo
Tuning view
Settings view
## Features
- Pitch detection based on the [YIN algorithm](http://audition.ens.fr/adc/pdf/2002_JASA_YIN.pdf)
- Modern terminal UI
- Easily customizable settings
- Batteries included
## Dependencies
- Go `1.24`
- Portaudio `19.7.0`
### Arch Linux
```bash
sudo pacman -S pkgconf portaudio go
```
### Debian
```bash
sudo apt-get install pkg-config portaudio19-dev golang-go
```
## Installation
### Arch Linux
```bash
yay -S ttune
```
### Build From Source
```bash
# get dependencies first
git clone https://github.com/SteveMCWin/ttune.git
cd ttune
go build
```
## Customization
You can add your own options to `custom_options.json` as long as you follow the existing format.
> **Note:** If something breaks, back up and delete the edited files or the entire `~/.config/ttune/` directory - the defaults will be regenerated on the next run.
---
### Ascii Art
Place your own ASCII art files in `~/.config/ttune/art/`. To display a tuning alongside your art, insert `%%%` where you'd like the notes to appear (see `~/.config/ttune/art/utf_guitar` for reference).
> **Recommended size:** no wider than **24 characters** and no taller than **20 lines**. Oversized art will not render properly.
---
### Border Style
Not extensible at the moment `:^/`
Want this to be moddable? [Open an issue](https://github.com/SteveMCWin/ttune/issues).
---
### Color Theme
To add a new color theme, open `~/.config/ttune/custom_options.json` and find the list of color themes. Add an entry with:
| Field | Description |
| ----------- | ------------------------ |
| `name` | Name of the color theme |
| `primary` | Hex color for borders |
| `secondary` | Hex color for text |
| `tertiary` | Hex color for selections |
> **Note:** Your terminal's background color will not be affected.
---
### Displayed Tuning
To add a new tuning, open `~/.config/ttune/custom_options.json` and find the list of tunings. Add an entry with:
| Field | Description |
| ------- | ------------------------- |
| `name` | Name of the tuning |
| `notes` | List of notes it contains |
> **Note:** Each note must be **exactly 3 characters long**. Pad shorter note names with spaces (e.g., `"E4 "`).
## Planned Features
- [x] Frequency detection
- [x] Customizable settings
- [x] Separate user settings
- [x] Scrollable settings options
- [ ] Options for frequency detection
- [ ] Improve pitch detection