eyescore

⚡ Beta v1.0.0

Professional CLI music notation system with colorized TUI

Compose music directly in the terminal with a beautiful text-based interface. Full MusicXML export, MIDI playback, and multi-staff support.

GitHub Get Started

Quick Start

eyescore is a direct-input music notation editor for the terminal. Compose music by typing note letters, adjust durations, and export to MusicXML.

Launch

$score

[Beautiful colorized TUI appears] ♪ EYESCORE v1.0.0 ♪ F1 - Setup | q - Quit [Staff display with cursor]

Installation

From AUR (Arch Linux)

AUR

$yay -S score

$score

Launch eyescore

From RPM

DNF

$sudo dnf install eyescore

$score --version

eyescore 1.0.0

From Source

Cargo

$git clone https://github.com/musicsian-com/score.git

$cd score && cargo build --release

$./target/release/score

Dependencies

Runtime Requirements

alsa-lib - ALSA sound library for MIDI playback
Terminal with Unicode support
Terminal with true color support (recommended)

Build Requirements

Rust 1.70+ and cargo
gcc - C compiler
alsa-lib-devel - ALSA development headers

First Steps

Launch eyescore and configure your initial composition:

Press F1 to enter setup screen
Configure time signature (default: 4/4)
Set key signature (C major = 0 sharps/flats)
Choose staff count (1-4 staves)
Start composing by pressing letter keys (c-b) for notes
Press SPACE to change note duration
Press s to save as JSON
Press x to export to MusicXML

Configuration

eyescore uses interactive setup - no configuration files needed. Press F1 to configure initial settings.

Time Signatures

Available time signatures:

Option	Type	Default	Description
`4/4`	signature	yes	Common time (default)
`3/4`	signature	no	Waltz time
`2/4`	signature	no	March time
`6/8`	signature	no	Compound duple
`9/8`	signature	no	Compound triple
`12/8`	signature	no	Compound quadruple
`5/4`	signature	no	Irregular meter
`7/4`	signature	no	Irregular meter

Key Signatures

Sharp Keys

C major (0 sharps)
G major (1 sharp)
D major (2 sharps)
A major (3 sharps)
E major (4 sharps)
B major (5 sharps)
F# major (6 sharps)
C# major (7 sharps)

Flat Keys

F major (1 flat)
B♭ major (2 flats)
E♭ major (3 flats)
A♭ major (4 flats)
D♭ major (5 flats)
G♭ major (6 flats)
C♭ major (7 flats)

Composition Settings

Pitch Range: C4 to B4 (single octave)
Staff Count: 1 to 4 staves
Durations: Whole, Half, Quarter, Eighth, Sixteenth
Accidentals: Natural, Sharp, Flat
Tuplets: Triplets (3:2), Quintuplets (5:4)
Undo History: Up to 50 actions

File Locations

score.json - Default save file (current directory)
score.musicxml - MusicXML export file

Overview

eyescore is a professional-grade CLI music notation system built in Rust. It provides a beautiful colorized TUI for composing music directly in the terminal.

Key Features

Direct keyboard input music composition
Multi-staff support (up to 4 staves)
MusicXML 3.1 export for professional software
Real-time MIDI playback
Time and key signature changes mid-composition
Undo/redo with 50-action history
JSON save format for version control
Automatic scrolling for unlimited compositions

Important Note

Despite the name "eyescore," this is NOT an OCR tool that scans sheet music. It's a direct-input notation editor where you compose by typing note letters.

System Overview

eyescore is a single-file Rust application (~1200 lines) using ratatui for TUI rendering.

Technology Stack

ratatui 0.28 - TUI framework
crossterm 0.28 - Terminal control
serde/serde_json - JSON serialization
xml-rs 0.8 - MusicXML generation
midir 0.10 - MIDI output

Controls Reference

Complete keyboard and mouse controls for eyescore.

Navigation

Option	Type	Default	Description
`← / →`	key	-	Move cursor left/right with auto-scroll
`↑ / ↓`	key	-	Switch between staves
`Home`	key	-	Jump to beginning of staff
`End`	key	-	Jump to end of staff
`PgUp / PgDn`	key	-	Jump by half-viewport (fast navigation)
`Mouse Click`	mouse	-	Position cursor and switch staves

Note Entry

Option	Type	Default	Description
`c / d / e / f / g / a / b`	key	-	Enter notes (C4-B4 pitch range)
`SPACE`	key	-	Cycle duration (Whole → Half → Quarter → Eighth → 16th)
`#`	key	-	Cycle accidental (Natural → Sharp → Flat)
`t`	key	-	Toggle tie to next note
`3`	key	-	Cycle tuplet mode (Off → Triplets → Quintuplets)

Staff Management

Option	Type	Default	Description
`+`	key	-	Add new staff (max 4 staves)
`-`	key	-	Remove current staff (min 1 staff)
`T (Shift+T)`	key	-	Cycle/insert time signature
`K (Shift+K)`	key	-	Cycle/insert key signature
`Shift+R`	key	-	Remove signature change at cursor

Edit Operations

Option	Type	Default	Description
`Delete / Backspace`	key	-	Remove note at cursor
`Ctrl+Z`	key	-	Undo (up to 50 actions)
`Ctrl+Y`	key	-	Redo
`s`	key	-	Save to JSON file (score.json)
`l`	key	-	Load from JSON file

Playback & Export

Option	Type	Default	Description
`p`	key	-	Play current staff with MIDI
`x`	key	-	Export to MusicXML (score.musicxml)

System

Option	Type	Default	Description
`F1`	key	-	Enter setup screen (configure initial settings)
`q`	key	-	Quit application

Troubleshooting

Common issues and solutions when using eyescore.

MIDI playback fails

Problem: "MIDI output not available" error.

Solution: Install and configure ALSA:

Fix

$sudo dnf install alsa-lib

$aplay -l

List audio devices

Colors don't display

Problem: No colors or incorrect colors.

Solution: Enable true color in terminal:

Use a modern terminal (GNOME Terminal, Konsole, iTerm2)
Enable 24-bit color in terminal settings
Verify: echo $COLORTERM should show "truecolor"

Unicode characters broken

Problem: Music symbols display incorrectly.

Solution: Set UTF-8 locale:

Fix

$export LANG=en_US.UTF-8

$locale

Verify UTF-8 is set

Application quits immediately

Problem: Exits right after launch.

Cause: Terminal doesn't support alternate screen.

Solution: Use a modern terminal emulator.

MusicXML export fails

Problem: Can't write score.musicxml.

Solutions:

Check write permissions in current directory
Close other programs that might have the file open
Ensure sufficient disk space

Build fails with alsa-lib error

Problem: Can't compile due to missing ALSA headers.

Solution: Install development headers:

Dependencies

$sudo dnf install alsa-lib-devel

# Fedora/RHEL

$sudo apt install libasound2-dev

# Debian/Ubuntu

$sudo pacman -S alsa-lib

# Arch

Getting Help

GitHub Issues: Report bugs or request features
In-app Help: Press F1 for setup screen

eyescore

Quick Start

Installation

From AUR (Arch Linux)

From RPM

From Source

Dependencies

Runtime Requirements

Build Requirements

First Steps

Configuration

Time Signatures

Key Signatures

Sharp Keys

Flat Keys

Composition Settings

File Locations

Overview

Key Features

Important Note

Note Entry

Note Entry Workflow

Available Durations

Staff Management

Export Options

MusicXML Export

Compatible Software

MIDI Playback

JSON Save Format

JSON Benefits

Signature Changes

Mid-Composition Changes

Global Changes

System Overview

Technology Stack

Data Structures

TUI Rendering

Rendering Pipeline

Audio System

Controls Reference

Navigation

Note Entry

Staff Management

Edit Operations

Playback & Export

System

Troubleshooting

MIDI playback fails

Colors don't display

Unicode characters broken

Application quits immediately

MusicXML export fails

Build fails with alsa-lib error

Getting Help