📖 ELYSY — User Guide

Double-click install.bat. It checks for FFmpeg (installs via winget if missing — reopen the terminal so PATH refreshes), installs PyTorch with CUDA 12.8, then all dependencies.

Double-click run.bat — the app opens your browser automatically at http://127.0.0.1:8765.

macOS / Linux

chmod +x install.sh run.sh
./install.sh
./run.sh

The first run downloads ~3.5 GB of AI models (Whisper large-v3, wav2vec2, Demucs). One-time download — be patient.

2 · A quick tour of the interface

Left panel — upload audio, choose language, paste/import lyrics, pick a mode, toggle vocal separation.
Center panel — waveform + transport on top, live LRC preview below. Hover a line for edit/nudge buttons; hover a word for precision controls.
Right panel — stats (words, lines, match rate, durations, project state), guides, and export.
Header — Create New Project · Load · Save · Save As New · Reset Project.

3 · Workflow A — AI Auto-Align (fastest)

Drop your audio

MP3/WAV/FLAC/OGG/M4A, up to 100 MB.

Select the language

Spanish, English, and 8 more.

Paste the lyrics

One sentence per line — or click Import LRC.

Click Auto-Align Lyrics

~30–90 s on GPU.

Review & fix

Play; words highlight. Hover dotted words to nudge them.

Export

Pick your format (see section 6).

4 · Workflow B — Manual Tap + AI (most precise)

Best for distortion, spoken-word, hums, or unusual phrasing.

Upload audio + paste lyrics, switch to Manual Tap.

Click Start Tap Recording.

Press Space at the start of each line.

Review the Line Timing screen — nudge lines with « < > » or clear a mistap with 🗑️.

Click Refine Words with AI — word timing fills your tapped windows.

Fine-tune & export.

5 · Editing your alignment

Word precision controls

Hover any word → a popover with « < 00:23.45 > », ▶ preview and ×. « » nudge by 0.3 s; < > by 0.1 s. ▶ plays a short window starting exactly at the word.

Line controls

Hover a line → « < > » (whole line), ✏️ edit, ＋ insert, 🗑️ delete.

Multi-select + batch shift

Ctrl/Cmd+click lines, then use Shift sel: −0.1 / +0.1 in the toolbar.

Undo / Redo

Ctrl+Z · Ctrl+Shift+Z or Ctrl+Y · on-screen ↩️/↪️. 50-step history.

Karaoke word ends

Each word highlights up to the next word's start — continuous flow, no flashing gaps.

6 · Exporting

Button	File	Best for
⭐ Enhanced LRC	`song_enhanced-LRC.lrc`	Karaoke apps, word-highlight players
⭐ Enhanced SRT	`song_enhanced-SRT.srt`	Word-by-word captions in Premiere / CapCut
📄 Standard LRC	`song_standard-LRC.lrc`	Classic line-level lyrics
🎬 SRT (Premiere)	`song_premiere-SRT.srt`	Line-level subtitles in video editors
🔧 JSON	`song_JSON.json`	Programmatic use

For karaoke word-by-word captions in video editors, use Enhanced SRT. Standard LRC's angle brackets are not parsed by video software.

7 · Projects & LRC import

💾 Save — updates the current project in place (no prompt).
💾 Save As New — saves a new project (prompts for a name).
📂 Load — restores audio + lyrics + alignment instantly.
📥 Import LRC — loads an external .lrc file into the editor.

Projects are self-contained folders — portable and backup-friendly:

projects/
└── my-song/
    ├── audio.mp3
    └── project.json

Project State in Stats shows Saved (green), Unsaved (red), or Not saved (amber).

8 · Keyboard shortcuts

Key	Action
Space	Play / Pause (or tap in manual mode)
← →	Seek back / forward 3 s
↑ ↓	Seek back / forward 1 s
Enter	Run Auto-Align
Esc	Cancel tap mode
Ctrl+Z	Undo
Ctrl+Shift+Z / Ctrl+Y	Redo
Ctrl/Cmd+click (line)	Multi-select for batch shift
⏮	Seek to start

9 · Understanding the stats

Words / Lines — counts in the current alignment.
Match Rate — % of words timed directly by AI (green ≥ 80%, yellow ≥ 50%, red below). Lower on distorted songs is normal; the rest are estimated and dotted.
Vocal Duration — the span actually covered by aligned words.
Song Duration — full track length (from the waveform).
Project State — Saved / Unsaved / Not saved.

10 · Troubleshooting

Problem	Solution
"CUDA not available"	Update NVIDIA drivers; re-run install.bat (cu128 build).
Demucs slow / fails	Uncheck "Vocal separation" — works on the full mix.
Words missing / dotted	Interpolated estimates — hover and nudge, or use Manual Tap.
Repeated chorus mis-timed	Auto-fixed; if not, nudge those lines.
Edits missing from export	They sync automatically; if not, Save → re-export.
Server won't start	Port busy? `python backend\app.py --port 8777`.
Install file-lock errors	Close server + VS Code, pause Dropbox/AV, re-run.

11 · Privacy & data

Everything runs locally — audio and lyrics never leave your machine.
No accounts, no cloud, no tracking.
Projects stored in projects/ on your disk (git-ignored).

ELYSY · MIT Licensed · Full docs & support: gabrielx.com/open-source-mit-ai-tools 🎤