Notes - KDE Desktop Application for Note Management

A native desktop application for KDE written in Python, similar to Joplin, with WYSIWYG editing, speech-to-text, and trash management. Features a dark theme interface with KDE native icons.

Features

• Notebook Management: Create, rename, delete notebooks
• Note Management: Create, edit, save notes in Markdown format
• WYSIWYG Editor: Rich text editing with formatting toolbar (bold, italic, headers, lists, code blocks, links)
• Image Support: Insert and auto-scale images in notes
• Speech-to-Text: Record audio and automatically transcribe with Vosk (English/Italian support)
• Voice Commands: Control formatting with voice commands ("bold this", "create list", etc.)
• Trash Management: Soft-delete with restore functionality (trash behaves like a notebook)
• Joplin-Style UI: Dark theme with 3-column layout
• KDE Integration: Native KDE icons and theme support
• Multi-Profile: Support for multiple profiles with --profile <directory>
• SQLite Database: All data saved locally with automatic migration
• Native KDE GUI: PyQt6 interface with native look and feel
• Note Search: Search by title and content
• Internationalization: English and Italian translations (extensible to other languages)

Requirements

• Python 3.9-3.14
• Poetry (for dependency management)
• gcc-c++ and python3-devel (for compiling numpy)
• System audio libraries (portaudio)

Dependencies (managed by Poetry):

• PyQt6 >=6.6.0 - GUI framework with dark theme support
• Vosk ^0.3.45 - Speech-to-text (offline, lightweight)
• sounddevice + wavio - Audio recording
• numpy - Numerical operations
• markdown - HTML/Markdown conversion

All dependencies are specified in pyproject.toml and will be installed automatically with poetry install.

Installation

1. Clone or copy the project

cd /tmp/Notes

2. Install Poetry (if not already installed)

curl -sSL https://install.python-poetry.org | python3 -

3. Install system dependencies

# Fedora/CentOS/RHEL
sudo dnf install gcc-c++ python3-devel portaudio-devel qt6-linguist

# Debian/Ubuntu
sudo apt install build-essential python3-dev portaudio19-dev qt6-linguist-tools

# Arch Linux
sudo pacman -S base-devel portaudio qt6-tools

4. Install Python dependencies with Poetry

poetry install
# Or if Poetry is installed as a Python module:
python3 -m poetry install
# Or use the helper script:
./poetry.sh install

Note: All dependencies are managed by Poetry in pyproject.toml.

5. Run interactive installer

The installer will download the appropriate Vosk speech model and set up the application:

./INSTALL.sh

Choose your preferred language when prompted. The installer will:

• Download Vosk models for selected language(s)
• Set up the data directory
• Verify all dependencies

Usage

Basic Launch (default directory ~/.config/Notes)

poetry run python main.py

Or enter Poetry shell:

poetry shell
python main.py

Launch with Custom Profile

poetry run python main.py --profile ~/Documents/NotesWork
poetry run python main.py --profile /mnt/data/notes-project

Language Selection

The application automatically detects your system language. To force a specific language:

poetry run python main.py --lang en  # English
poetry run python main.py --lang it  # Italian

Command-Line Parameters

python main.py --help

• --profile <directory>: Specify profile directory (default: ~/.config/Notes)
• --lang <code>: Force language (e.g., en, it). Auto-detected if not specified.

Project Structure

Notes/
├── main.py                 # Application entry point
├── models/                 # Models and database
│   ├── __init__.py
│   ├── database.py        # SQLite management with soft-delete
│   ├── notebook.py        # Notebook model
│   └── note.py            # Note model
├── gui/                    # Graphical interface
│   ├── __init__.py
│   ├── notebook_list.py   # Tree view with KDE icons
│   ├── note_list.py       # Notes list with trash support
│   ├── editor_widget.py   # WYSIWYG editor + speech integration
│   └── wysiwyg_editor.py  # Rich text editor widget
├── speech/                 # Speech processing
│   ├── __init__.py
│   └── transcriber.py     # Vosk transcription with voice commands
├── i18n/                   # Translations
│   ├── en.ts              # English strings
│   ├── en.qm              # English compiled
│   ├── it.ts              # Italian strings
│   └── it.qm              # Italian compiled
├── pyproject.toml         # Poetry dependencies and config
├── poetry.lock            # Locked dependencies (auto-generated)
├── INSTALL.sh             # Interactive installer
├── run_tests.py           # Test runner
├── pytest.ini             # Test configuration
└── README.md

Data Directory

Default Directory

~/.config/Notes/
├── notes.db              # SQLite database
└── (other config files)

Custom Directory (with --profile)

python main.py --profile ~/my-notes

Will create:

~/my-notes/
├── notes.db
└── (other config files)

Speech-to-Text with Vosk

The app uses Vosk for offline speech recognition.

Setup: Vosk models are downloaded automatically by INSTALL.sh. Manual setup:

# English model
wget https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip
unzip vosk-model-small-en-us-0.15.zip -d ~/.config/vosk/models/

# Italian model
wget https://alphacephei.com/vosk/models/vosk-model-small-it-0.22.zip
unzip vosk-model-small-it-0.22.zip -d ~/.config/vosk/models/

Usage:

1. Open a note in the editor
2. Click "Record & Transcribe" button
3. Speak clearly into your microphone
4. Click "Stop Recording" when finished
5. Transcribed text is inserted at cursor position

Voice Commands: Control formatting with voice commands:

English:

• "bold this" - Make selected text bold
• "italic this" - Make selected text italic
• "create list" - Insert bullet list
• "create numbered list" - Insert numbered list
• "insert code block" - Insert code block

Italian:

• "grassetto questo" - Rendi grassetto il testo selezionato
• "corsivo questo" - Rendi corsivo il testo selezionato
• "crea lista" - Inserisci lista puntata
• "crea lista numerata" - Inserisci lista numerata
• "inserisci blocco codice" - Inserisci blocco di codice

Supported languages: Download the appropriate model for your language from https://alphacephei.com/vosk/models

WYSIWYG Editor

Formatting Toolbar

• Bold/Italic/Underline
• Headers (H1, H2, H3)
• Lists (bullet, numbered)
• Code blocks
• Links
• Images

Image Support

• Insert images via toolbar button
• Images are auto-scaled to fit editor width (max 800px)
• Stored as base64 in Markdown for portability
• No external file dependencies

Markdown Storage

• All notes stored as Markdown internally
• WYSIWYG editing converted to/from Markdown
• Compatible with other Markdown editors

Features Detail

Notebooks

• Create: "+ New Notebook" button
• Rename: Right-click -> Rename
• Delete: Right-click -> Delete (moves to trash)
• Trash: Deleted notebooks appear under "Trash" in the tree
• Tree View: Hierarchical view with native KDE icons

Notes

• Create: "+ New Note" button (requires notebook selection)
• Edit: Click on a note to open in WYSIWYG editor
• Save: Auto-save when switching notes
• Formatting: Rich text editing with toolbar (bold, italic, lists, etc.)
• Images: Insert and auto-scale images
• Rename: Right-click -> Rename
• Delete: Right-click -> Delete (moves to trash)

Trash Management

• Soft Delete: Notes and notebooks are moved to trash (not permanently deleted)
• Trash as Notebook: Trash appears in the notebook tree and behaves like a folder
• Read-Only View: Notes in trash are read-only (can view but not edit)
• Restore: Right-click deleted items to restore them
• Permanent Delete: Permanently remove items from trash

Editor

• WYSIWYG editing with rich formatting toolbar
• Image insertion and auto-scaling
• Markdown storage (converted from HTML)
• Voice command integration
• Insert transcribed text from audio

Tests

The application includes a complete test suite.

Run all tests

poetry run python run_tests.py
# or
poetry run pytest

Run specific tests

poetry run python run_tests.py test_database
poetry run python -m unittest tests.test_gui

With coverage

poetry run pytest --cov=. --cov-report=html tests/

See tests/README.md for complete details.

Dependency Management

This project uses Poetry for dependency management. All dependencies are specified in pyproject.toml.

Adding New Dependencies

# Add a production dependency
poetry add package-name

# Add a development dependency
poetry add --group dev package-name

# Update dependencies
poetry update

# Show installed packages
poetry show

# Remove a package
poetry remove package-name

Helper Script

If you're on a system where Poetry is installed as python3 -m poetry, use the included helper script:

./poetry.sh add package-name
./poetry.sh install
./poetry.sh run python main.py

Note: requirements.txt has been removed. Use only Poetry for dependency management.

Internationalization (i18n)

The application supports multiple languages:

• English (default)
• Italian

Language is auto-detected from your system locale, or you can force a specific language with --lang parameter.

Adding New Translations

1. Edit translation files: i18n/en.ts, i18n/it.ts
2. Update strings with Qt Linguist:

   linguist i18n/en.ts

3. Or run the update script:

   ./update_translations.sh

4. Compile translations (requires Qt tools):

   lrelease i18n/*.ts

Adding a New Language

1. Copy i18n/en.ts to i18n/<lang>.ts (e.g., i18n/es.ts for Spanish)
2. Translate strings in the new file
3. Compile: lrelease i18n/<lang>.ts
4. Launch with: python main.py --lang <lang>

Future Development

• Live Markdown preview with syntax highlighting
• Cloud synchronization (optional)
• PDF/HTML export
• Customizable themes
• Plugin system
• Note encryption
• Drag-and-drop between notes
• More language models (Spanish, French, German)
• Note templates
• Search functionality
• Tags system

Database Schema

Table notebooks

id INTEGER PRIMARY KEY
name TEXT
created TIMESTAMP

Table notes

id INTEGER PRIMARY KEY
notebook_id INTEGER
title TEXT
content TEXT
created TIMESTAMP
modified TIMESTAMP

Table tags (future)

id INTEGER PRIMARY KEY
note_id INTEGER
tag TEXT

Database Migration

Existing installations automatically migrate the database schema to support trash functionality. The migration adds:

• is_deleted boolean columns
• deleted_at timestamp columns
• Indexes for performance

No manual intervention required.

Troubleshooting

Error: "No module named PyQt6"

poetry install
# Ensure PyQt6 >= 6.6.0

Error: "Vosk model not found"

./INSTALL.sh  # Re-run installer
# Or manually download models to ~/.config/vosk/models/

Error: "PortAudio not found"

sudo apt install portaudio19-dev  # Debian/Ubuntu
sudo dnf install portaudio-devel   # Fedora

Error: "Images not scaling properly"

• Check editor width is sufficient
• Images scale to min(editor_width - 40, 800) pixels

Error: "Trash not showing deleted items"

• Database migration runs automatically
• Check notes.db has is_deleted columns

Error: "Qt translations not working"

Make sure you have Qt tools installed:

sudo apt install qt6-linguist-tools  # Debian/Ubuntu
sudo dnf install qt6-linguist        # Fedora

Then compile translations:

lrelease-qt6 i18n/*.ts

License

Open source project - use as you wish!

Author

Created for efficient note management on Linux/KDE with integrated speech support.

---

Happy note-taking with Notes!