RapNote

Desktop application for writing and editing rap lyrics with syllable analysis, rhyme detection, and song structure management.

Features

• Block-based editor — organize lyrics into named sections (Verse, Chorus, Bridge, etc.)
• Syllable counter — automatic for Russian/Ukrainian, manual |-based for other languages
• Rhyme analyzer — visual quality indicators (good/mid/bad) for paired lines
• Rhyme finder — search rhymes from a built-in database with stress-aware scoring
• Reading mode — distraction-free view for reviewing lyrics
• Instrumental blocks — track non-lyrical sections (Break, Drop, Interlude, etc.)
• Instructions — attach generation/processing commands to blocks with template library
• Autosave — saves on focus loss, before open/new, and debounced fallback (500ms)
• Atomic writes — files are never corrupted (write to .tmp, then rename)
• Import/Export — work with plain TXT files alongside the native .rapnote format
• i18n — English and Russian interface

Requirements

• Python 3.10+
• PyQt6
• pytest (for running tests)

Installation

# Clone the repository
git clone <repository-url>
cd rapnote

# Create a virtual environment
python -m venv .venv
.venv/Scripts/activate   # Windows
# source .venv/bin/activate  # macOS/Linux

# Install dependencies
pip install -r requirements.txt
pip install pytest  # for running tests

Usage

python main.py

Running Tests

pytest tests/ -v

Keyboard Shortcuts

Action	Shortcut
New project	Ctrl+N
Open project	Ctrl+O
Save project	Ctrl+S
Export TXT	Ctrl+E
Insert lyrics block	Ctrl+Shift+N
Insert instrumental block	Ctrl+Shift+I
Delete block	Ctrl+Backspace
Move block up	Alt+Up
Move block down	Alt+Down
Undo	Ctrl+Z
Redo	Ctrl+Y

Syllable Marking

For languages other than Russian/Ukrainian, mark syllables manually using the pipe character:

|word1| |word2| |word3|

Each |-delimited segment counts as one syllable.

File Format

Projects are saved as .rapnote files — human-readable TXT with metadata:

# RapNote Project
# target: 16
# tol: 2
# lang: ru

[Verse]
# instruction: generate verse | описание
привет как дела
я пишу рэп про жизнь

[Chorus]
это припев

[Instrumental: Break]

• Metadata in # key: value comments at top
• Sections as [SectionName]
• Instrumental sections as [Instrumental: TypeName]
• Instructions as # instruction: command | description
• Legacy .json files are still supported for opening

Project Structure

rapnote/
  main.py            # Application entry point
  ui.py              # Main window
  model.py           # Data model (Project, Block)
  project_repo.py    # Repository: load/save/autosave/dirty tracking
  storage/           # Storage strategies (Strategy pattern)
    _base.py         # Storage ABC + atomic write
    rapnote.py       # .rapnote/.txt format
    json_storage.py  # .json format (legacy)
  logic.py           # Value classification
  block.py           # Block editor widgets
  block_controller.py # Background analysis (syllables + rhymes)
  block_navigation.py # Block list navigation
  panel_controller.py # Top panel <-> project sync
  toppanel.py        # Top control panel
  bottompanel.py     # Rhyme search panel
  i18n.py            # Internationalization strings
  styles.py          # Dark theme stylesheet
  constants.py       # Layout and label constants
  rhyme.py           # Rhyme extraction and classification
  syllables.py       # Syllable counting
  rhyme_backend.py   # SQLite rhyme database engine
  instructions.py    # Block instruction dialog
  mainmenu.py        # Menu bar
  combo_popup.py     # Custom combo box popup
  gui_utils.py       # Icon and resource helpers
  readmode.py        # Reading mode controller
  file_operations.py # File open/save/export dialogs
  db/                # Rhyme database (rhymes.db, runtime-generated)
  img/               # SVG/PNG icons
  tests/             # Unit tests
  user_data/         # Autosave and custom instructions (runtime-generated)

Architecture

• Storage Strategy — each file format (.rapnote, .json) is a separate class implementing Storage protocol
• ProjectRepo — single entry point for all project operations with dirty tracking and debounce autosave
• Atomic Writes — files are written to .tmp first, then atomically replaced via os.replace()
• Snapshot Stack — undo works across save/load operations

License

MIT