NoteForge

Smart Note Creation: Real-Time Transcription & Intelligent Note Summarization

NoteForge is a powerful dual-purpose application that combines real-time voice transcription with AI-powered note summarization. Perfect for students, professionals, and anyone who needs to capture and organize spoken content into study-ready notes.

Features

Real-Time Transcription

• Hybrid AI Architecture: Combines Vosk (instant streaming) + Whisper (high accuracy)
• Voice Activity Detection: Precise speech detection using WebRTC VAD
• Professional Audio Processing:
  • Noise reduction
  • Dynamic gain normalization
  • 16kHz optimized sample rate
• Modern UI: Dark mode, audio level meter, always-on-top mode
• Offline Capable: Runs completely locally after initial setup

Note Summarization

• Semantic Topic Extraction: Automatically organizes content by topics
• Legal Content Recognition: Detects case law, legal principles, and doctrines
• Smart Classification: Categorizes content into:
  • Definitions
  • Legal Rules & Principles
  • Key Cases (with citations)
  • Exceptions & Special Rules
  • Practical Examples
• Multiple Input Formats: Supports both text transcripts (.txt) and PowerPoint (.pptx)
• Study-Ready Output: Generates structured lecture notes organized by topic
• PDF Export: Save your notes as professional PDFs
• Automatic Session Export: (NEW) Automatically saves every recording as .wav and .txt in the recordings/ folder.

Installation

1. Clone the Repository

git clone https://github.com/slnquangtran/NoteForge.git
cd NoteForge

2. macOS Prerequisites (Install FIRST)

IMPORTANT: macOS users should see the dedicated macOS Installation Guide for step-by-step instructions.

If you're on macOS, install system dependencies before Python packages:

# Quick install (recommended)
chmod +x install-macos.sh
./install-macos.sh

# Or install system dependencies manually
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install portaudio llvm
xcode-select --install

Python 3.12 is recommended for best macOS compatibility. See MAC_INSTALLATION.md for detailed instructions including pre-flight checks.

3. Install Python Dependencies

# Set LLVM path for macOS (Python 3.12 users)
export LLVM_CONFIG=$(brew --prefix llvm)/bin/llvm-config  # macOS only

# Install all dependencies
pip install -r requirements.txt

4. Verify Installation

Check that all dependencies are installed:

python install_check.py

You should see All dependencies installed! before proceeding.

5. Troubleshooting (macOS)

For comprehensive macOS troubleshooting, see MAC_INSTALLATION.md

If you encounter "Failed to build wheel" or "PortAudio not found" errors on Mac, follow these steps:

1. Install Homebrew: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. Install System Deps: brew install portaudio llvm
3. Install Xcode Tools: xcode-select --install

Fix for llvmlite / numba Build Error

If you are on Python 3.12 and see TypeError: spawn() got an unexpected keyword argument 'dry_run', follow these steps:

1. Ensure LLVM is installed: brew install llvm
2. Use the correct env var:

export LLVM_CONFIG=$(brew --prefix llvm)/bin/llvm-config
pip install "llvmlite==0.42.0"
pip install -r requirements.txt

Fix for ModuleNotFoundError: No module named 'whisper'

If you see this error even after installing requirements:

1. Uninstall duplicates: pip uninstall whisper (this is a different package)
2. Reinstall correct package: pip install openai-whisper
3. Check environment: Ensure you are running python from the same environment where you ran pip install.

Verify Installation

After installing dependencies, verify everything is ready:

python -c "import torch; import whisper; import vosk; import pptx; print('✅ All dependencies installed!')"

If you see any ModuleNotFoundError, reinstall that specific package or run pip install -r requirements.txt again.

NoteForge v1.1.0 pins llvmlite==0.42.0 and numpy<2.0.0 which officially support Python 3.12.

6. Hardware Acceleration (Optional but Recommended)

• Windows (NVIDIA): Automatically uses CUDA if available.
• macOS (Apple Silicon): Automatically uses MPS (Metal Performance Shaders) for Whisper inference.

7. Launch NoteForge

# Recommended (Package Launch)
python main.py

# Or via installed script (if pip installed -e .)
noteforge

Models will be downloaded automatically on the first run. The app will detect your hardware (CUDA/MPS/CPU) and optimize performance accordingly.

Architecture (v3.0+)

NoteForge has been refactored from a monolithic script into a modular package-based architecture:

• src/noteforge/config/: Centralized settings and path management.
• src/noteforge/models/: Unified model registry and lifecycle management.
• src/noteforge/transcription/: Decoupled transcription engine and audio processing.
• src/noteforge/study/: Extracted note generation and PDF export services.
• tests/: Smoke tests for core modular components.

Legacy root-level scripts (app.py, study_assistant.py, model_manager.py) are now thin compatibility wrappers for the noteforge package.