FlashRead

Learn Spanish vocabulary through flashcards generated from real Spanish texts.

FlashRead analyzes Spanish books, articles, or any text you provide, extracts the most common words, and presents them as interactive flashcards. The more you read in Spanish, the better your vocabulary becomes.

Quick Start

Prerequisites

• Python 3.7 or higher
• just command runner (optional but recommended)

Installation

# Clone the repository
git clone https://github.com/yourusername/flashread.git
cd flashread

# Option 1: Using just (recommended)
just setup
source .venv/bin/activate

# Option 2: Manual setup
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Add Your Spanish Texts

Create a corpus/ folder and add any Spanish text files (.txt) you want to learn from:

mkdir corpus
# Add your Spanish books, articles, or texts as .txt files
# Example: corpus/mi-libro-favorito.txt

Ideas for texts:

• Spanish news articles
• Spanish Wikipedia pages
• Public domain Spanish literature from Project Gutenberg
• Transcripts of Spanish podcasts or videos
• Spanish song lyrics

Generate and Run

# Process your texts and build vocabulary
python flashread.py generate

# Launch the flashcard app
python flashread.py run

Or with just:

just generate
just run

Using the Flashcard App

Once launched, you'll see an interactive window with:

• Word Display: A random Spanish word from your corpus appears at the top
• Click to Continue: Click on the word to see the next one
• Settings (cogwheel icon): Customize your learning experience

Filtering Options

• Word Length: Focus on shorter or longer words using the min/max sliders
• Starting Letters: Toggle specific letters on/off to practice words beginning with certain letters
• Display Case: Choose lowercase, UPPERCASE, or Title Case
• Hyphenation: Show syllable breaks to help with pronunciation (e.g., "es-pa-ñol")

Commands Reference

Command	Description
python flashread.py generate	Process corpus and create vocabulary
python flashread.py generate --plot	Also generate a word frequency chart
python flashread.py generate --force	Regenerate even if data exists
python flashread.py run	Launch the flashcard app

Using just

If you have just installed:

Command	Description
just setup	Create virtual environment and install
just generate	Process corpus texts
just run	Launch flashcard app
just clean	Remove generated files

Run just without arguments to see all available commands.

How It Works

1. Text Processing: FlashRead reads all .txt files in your corpus/ folder
2. Word Extraction: Common Spanish stopwords (like "el", "la", "de") are filtered out
3. Frequency Analysis: Words are ranked by how often they appear
4. Vocabulary Creation: Only words appearing 3+ times are included (configurable)
5. Flashcard Display: Words are shown randomly with your chosen filters

Project Structure

flashread/
├── src/                  # Application source code
├── corpus/               # Your Spanish text files (you create this)
├── data/                 # Generated vocabulary data (auto-created)
├── flashread.py          # Main entry point
├── justfile              # Task runner commands
└── requirements.txt      # Python dependencies

Tips for Effective Learning

1. Start with texts you enjoy - Learning is easier when the content interests you
2. Use the length filter - Begin with shorter words (4-6 letters) and gradually increase
3. Focus on letter groups - Practice words starting with letters you find challenging
4. Enable hyphenation - Helps you understand Spanish syllable patterns
5. Add more texts over time - Your vocabulary grows as your corpus grows

Troubleshooting

"No vocabulary data found"

Make sure you have:

1. Created the corpus/ directory
2. Added at least one .txt file with Spanish text
3. Run python flashread.py generate before running the app

"No words match current filters"

Try relaxing your filters:

• Increase the max length slider
• Enable more starting letters
• The settings panel shows how many words match your current filters

NLTK Download

On first run, FlashRead downloads required language data from NLTK. This happens automatically but requires an internet connection.

Contributing

Contributions are welcome! See CONTRIBUTE.md for development setup.

# Development setup
just setup-dev

# Run tests
just test

# Format code
just format

License

MIT License - see LICENSE for details.