📊 MuseStat - Manuscript Statistics Analyzer

Beautiful terminal UI for comprehensive manuscript analysis with advanced features for fiction writers.

✨ Features

Core Statistics

• 📝 Word & Character Count: Accurate counts with markdown cleaning
• 📖 Chapter Analysis: Automatic detection with smart patterns
• ⏱️ Reading Time: Estimated based on average reading speed
• 🎯 Writing Milestones: Track progress towards novel length goals
• 🏆 Achievement Badges: Unlock titles as you cross word count thresholds
• ✍️ Writer's Wisdom: Motivational quotes from famous authors
• 📄 Multiple Format Support: .md, .txt, .docx, .rtf files

Advanced Features

• 🌐 Language Detection: Auto-detect language and use appropriate stop words
• 📊 Readability Metrics: Flesch-Kincaid, Gunning Fog, Coleman-Liau, and more
• 💬 Dialogue Analysis: Count dialogue lines and calculate dialogue ratio
• ⚡ Pacing Detection: Identify long sentences/paragraphs that may affect pacing
• 📈 Progress Tracking: Compare with previous analyses to track your writing progress
• 🎭 Scene Detection: Count scene breaks within chapters
• 🔤 Word Frequency: Most common words with language-aware stop word filtering

Visual Enhancements

• ✨ Sparkline Charts: Inline unicode sparklines showing chapter length trends at a glance
• 🚦 Color-Coded Indicators: Traffic light system (Green/Yellow/Red) for readability scores
• 📊 Trend Arrows: Directional arrows (↑↓→) showing if metrics improved or declined
• 🎨 Heat Maps: Visual density maps showing word and sentence distribution across chapters
• ⚖️ Balance Visualization: Color-coded chapter consistency indicators
• 📏 Mini-Bars: Visual progress bars in tables for quick comparison

Badge Generation

• 🏅 Dynamic Badges: Generate beautiful SVG and PNG badges for your manuscript
• 📊 Word Count Badge: Display total words with modern gradient design
• 🏆 Achievement Badge: Show milestone achievements
• 📖 Chapters Badge: Display chapter count
• 📄 Pages Badge: Show estimated reading pages
• 🎨 Professional Design: Modern gradients, shadows, and polished styling
• 💾 Multiple Formats: Export as SVG (scalable) or PNG (raster)
• 📱 Perfect for README: Embed badges in your project documentation

Smart Chapter Detection

Recognizes multiple chapter formats:

• # Chapter Title (Markdown H1)
• ## Chapter Title (Markdown H2)
• Chapter 1: Title
• CHAPTER 1: Title
• Ch. 1: Title

🚀 Installation

From Releases (Recommended)

Download the latest executable for your platform from the Releases page:

• Windows: musestat-windows-x64.exe
• Linux: musestat-linux-x64
• macOS: musestat-macos-x64

No Python installation required!

✨ Interactive Mode: Simply double-click the executable to launch an interactive menu that guides you through:

• File selection
• Analysis type selection
• Beautiful results display
• Perfect for first-time users!

From Source

1. Install Python 3.7+

2. Clone the repository:

git clone https://github.com/Tfc538/MuseStat.git
cd MuseStat

3. Install dependencies:

pip install -r requirements.txt

4. Run MuseStat:

python main.py
# or
python -m musestat.cli.commands

Development Setup

For development and building executables:

# Install development dependencies
pip install -r requirements-dev.txt

# Install in editable mode
pip install -e .

# Run tests (when available)
pytest

# Build executable
pyinstaller --onefile --name musestat --console main.py

📖 Usage

Interactive Mode (Easiest!)

Simply double-click the executable or run without arguments:

# Windows
musestat.exe

# Linux/macOS
./musestat

You'll see a beautiful welcome screen with:

1. List of all manuscript files in the current directory
2. File selection menu
3. Analysis type menu (quick, standard, full, advanced, verify)
4. Results that stay on screen until you press Enter

Command-Line Mode (For Power Users)

# Analyze default file
python main.py

# Analyze specific file
python main.py -f mybook.docx
python main.py --file manuscript.txt

# Quick summary
python main.py --compact
python main.py -c

Note: If you're using the compiled executable, replace python main.py with musestat (or ./musestat on Linux/macOS).

Advanced Features

# Enable all advanced features (language detection, readability, dialogue, pacing)
python main.py --advanced
python main.py -a

# Save snapshot for future comparison
python main.py --save-snapshot
python main.py -s

# Compare with previous analysis
python main.py --compare mybook.stats.json

# Combine options
python main.py -f mybook.docx --advanced --save-snapshot

Badge Generation

# Generate SVG badges for word count and achievement
python main.py -f mybook.md --badges wordcount,achievement

# Generate both SVG and PNG badges (requires cairosvg)
python main.py --badges wordcount,achievement,chapters,reading_time --badge-formats svg,png

# Specify custom output directory
python main.py --badges wordcount --badge-formats svg --badge-dir ./badges

# In interactive mode: multi-select checkboxes for badge types and formats
python main.py  # Then select badges from interactive menu

Available Badge Types:

• wordcount - Display total word count
• achievement - Show writing milestone
• chapters - Display chapter count
• reading_time - Show estimated pages

Output Formats:

• svg - Scalable vector graphics (default, ~1.5 KB)
• png - Raster image format (~2-4 KB, requires cairosvg)

Badges are saved to ./musestat/badges/{manuscript}_{badge_type}.{format}

Display Customization

# Show top 25 most frequent words instead of default 15
python main.py --top-words 25

# Limit chapter display to first 10 chapters
python main.py --max-chapters 10

# Change minimum word length for frequency analysis (default: 3)
python main.py --min-word-length 4

# Customize sparkline width for better visibility
python main.py --sparkline-width 60

# Hide specific sections
python main.py --hide-word-frequency  # Hide word frequency table
python main.py --hide-heat-map        # Hide density heat map
python main.py --hide-chapter-details # Hide chapter breakdown

# Show top 5 longest chapters in summary
python main.py --show-top-chapters 5

# Combine customizations
python main.py --top-words 30 --max-chapters 15 --sparkline-width 50

Discovery & Information

# List all manuscript files in current directory
python main.py --list
python main.py -l

# Show supported formats and features
python main.py --formats

# Show only chapter breakdown
python main.py --chapters-only

# Check version
python main.py --version

Performance

# Skip loading animation for instant results
python main.py --no-animation

# Fast word count check
python main.py -c --no-animation

🎯 CLI Options

Option	Short	Description
--file PATH	-f	Specify file to analyze
--compact	-c	Display compact summary
--advanced	-a	Enable advanced features
--list	-l	List all manuscript files
--formats		Show supported formats
--chapters-only		Show only chapter breakdown
--no-animation		Skip loading animation
--save-snapshot	-s	Save stats for comparison
--compare FILE		Compare with previous stats
--badges BADGES		Generate badges (comma-separated)
--badge-formats FORMATS		Badge output formats (svg,png)
--badge-dir DIR		Badge output directory
--help	-h	Show help message

📊 What You'll See

Full Mode (Default)

📊 MuseStat - Manuscript Analytics
═══════════════════════════════════

┌─────────────────────────────────┐
│  📊 Overview Statistics         │
│  - Total Words: 107,638         │
│  - Characters: 582,576          │
│  - Chapters: 33                 │
│  - Reading Time: 7h 10m         │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│  📖 Chapter Breakdown           │
│  - Individual chapter stats     │
│  - Word counts & percentages    │
│  - Scene counts per chapter     │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│  🔤 Most Frequent Words         │
│  - Top 15 common words          │
│  - Visual bar charts            │
└─────────────────────────────────┘

Advanced Mode (--advanced)

Includes everything from Full Mode plus:

┌─────────────────────────────────┐
│  📖 Readability Metrics         │
│  - Flesch Reading Ease: 72.3    │
│  - Flesch-Kincaid Grade: 7.8    │
│  - Gunning Fog Index: 10.2      │
│  - Coleman-Liau Index: 8.5      │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│  ⚡ Pacing Analysis              │
│  - Avg Sentence Length: 15.2    │
│  - Avg Paragraph Length: 87     │
│  - Long Sentences: 12           │
│  - Long Paragraphs: 8           │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│  💬 Dialogue Statistics         │
│  - Dialogue Lines: 1,247        │
│  - Dialogue Ratio: 32.5%        │
└─────────────────────────────────┘

Comparison Mode (--compare)

┌─────────────────────────────────┐
│  📈 Changes Since Last Analysis │
│  Words: +1,523 ✓                │
│  Characters: +8,234 ✓            │
│  Sentences: +89 ✓                │
│  Paragraphs: +45 ✓               │
│  ⏰ Last analyzed: 2 days ago   │
└─────────────────────────────────┘

💡 Use Cases & Workflows

Daily Writing Progress

# Quick word count after your writing session
python main.py -c --no-animation

Deep Manuscript Analysis

# Full analysis with all advanced features
python main.py -f manuscript.docx --advanced

Track Your Writing Progress

# First analysis - save a snapshot
python main.py --save-snapshot

# Later - compare with previous
python main.py --compare manuscript.stats.json

Editor Review

# Analyze readability and pacing
python main.py --advanced

# Focus on chapter structure
python main.py --chapters-only

# Verify manuscript for publishing
python main.py --verify

Multiple Format Management

# See all manuscript versions
python main.py --list

# Compare different versions
python main.py -f draft.md -c
python main.py -f final.docx -c

📊 Readability Scores Explained

Flesch Reading Ease (0-100)

• 90-100: Very Easy (5th grade)
• 80-90: Easy (6th grade)
• 70-80: Fairly Easy (7th grade)
• 60-70: Standard (8-9th grade) - Most novels
• 50-60: Fairly Difficult (10-12th grade)
• 30-50: Difficult (College)
• 0-30: Very Difficult (Graduate)

Flesch-Kincaid Grade

• Indicates US grade level required to understand the text
• Most popular fiction: Grade 6-8
• Literary fiction: Grade 8-10

Gunning Fog Index

• Estimates years of formal education needed
• Ideal for most writing: 8-10

🎨 Features Comparison

Feature	Basic	With --advanced
Word Count	✓	✓
Character Count	✓	✓
Chapter Breakdown	✓	✓ with scenes
Reading Time	✓	✓
Word Frequency	✓	✓ language-aware
Milestones	✓	✓
Language Detection	✗	✓
Readability Metrics	✗	✓
Dialogue Analysis	✗	✓
Pacing Analysis	✗	✓

📝 Supported File Formats

Format	Extension	Requires	Status
Markdown	.md, .markdown	Built-in	✓
Plain Text	.txt	Built-in	✓
Word Document	.docx	python-docx	✓
Rich Text Format	.rtf	striprtf	✓

🔧 Dependencies

Core (Required)

• rich >= 13.0.0 - Beautiful terminal UI

File Formats (Optional)

• python-docx >= 0.8.11 - Word documents
• striprtf >= 0.0.26 - RTF files

Advanced Features (Optional)

• langdetect >= 1.0.9 - Language detection
• textstat >= 0.7.3 - Readability metrics
• questionary >= 2.0.0 - Interactive TUI

Note: The tool works without optional dependencies but with reduced functionality.

📈 Todo List

✅ Completed Features

• Flexible file input: --file <path> for any manuscript
• Multiple format support: Auto-detect .docx, .txt, .md, .rtf
• Language detection: With language-specific stop words
• Readability metrics: Flesch-Kincaid, Gunning Fog, Coleman-Liau
• Smarter chapter detection: Multiple patterns including ##, scene markers
• Dialogue counting: Lines and ratio analysis
• Pacing detection: Long sentences/paragraphs flagging
• Progress tracking: --compare with previous stats

🚀 Future Enhancements

• Export reports to PDF/HTML
• Word cloud visualization
• Character name frequency tracking
• Time-of-day analysis (morning/evening writing patterns)
• Writing streak tracking
• Sentiment analysis
• Genre-specific benchmarks

🎯 Tips for Fiction Writers

Dialogue Ratio

• Heavy dialogue (50%+): Fast-paced, character-driven
• Moderate dialogue (30-50%): Balanced narrative
• Light dialogue (< 30%): Description/introspection heavy

Sentence Length

• Short (< 15 words): Creates tension, fast pacing
• Medium (15-20 words): Standard, easy reading
• Long (> 25 words): Slower, more literary

Paragraph Length

• Short (< 50 words): Modern, fast-paced
• Medium (50-150 words): Standard
• Long (> 200 words): May lose reader attention

Readability

• Commercial fiction: Aim for Flesch-Kincaid Grade 6-8
• Literary fiction: Grade 8-10 is acceptable
• YA fiction: Grade 5-7

🤝 Contributing

Suggestions and contributions are welcome! This tool is designed for writers, by writers.

See CONTRIBUTING.md for guidelines.

💬 Contact

• Author: Tim Gatzke
• Email: post@tim-gatzke.de
• Website: tim-gatzke.de
• GitHub: @Tfc538

📄 License

MIT License - Use freely for your writing projects!

🙏 Acknowledgments

Built with:

• Rich - Beautiful terminal formatting
• python-docx - Word document support
• textstat - Readability metrics
• langdetect - Language detection

---

Happy Writing! 📚✨

MuseStat - Because every word counts