A beautiful word definition image generator that turns vocabulary learning into art

Wallnary automatically generates stunning word definition images and sets them as your wallpaper. Perfect for expanding your vocabulary while keeping your desktop beautiful and educational!

• 🤖 AI-Powered Word Generation - Uses OpenRouter API with configurable AI models
• 🎨 Beautiful Typography - Professional design with Inter font family
• 🌈 Customizable Colors - Full color scheme customization via config
• 📱 Cross-Platform - Works on Windows, macOS, and Linux
• 🖼️ Auto Wallpaper Setting - Multiple wallpaper modes (center, crop, fit, span, stretch, tile)
• ⚙️ Flexible Configuration - TOML-based configuration with sensible defaults
• 📐 Custom Dimensions - Support for any resolution and aspect ratio
• 💾 Multiple Formats - PNG and other image formats
• 🎯 Advanced Vocabulary - Focuses on educational, intermediate-to-advanced words

• Rust 1.70+ installed
• OpenRouter API key (get one here)

1. Clone the repository:

   git clone https://github.com/yourusername/wallnary.git
   cd wallnary

2. Build the project:

   cargo build --release

3. Run wallnary:

   ./target/release/wallnary

On first run, wallnary will create a default configuration file and prompt you to add your OpenRouter API key.

1. Add your API key to the generated config file:

   • Windows: %APPDATA%\wallnary\word_config.toml
   • macOS: ~/Library/Application Support/wallnary/word_config.toml
   • Linux: ~/.config/wallnary/word_config.toml

2. Edit the config file:

   openrouter_api_key = "your-api-key-here"

3. Run wallnary:

   wallnary

Each generated image includes:

• Word - The vocabulary word in large, bold text
• Definition - Clear, educational definition
• Example - Practical usage example in context
• Pronunciation - IPA phonetic pronunciation guide

Wallnary uses a TOML configuration file with extensive customization options:

# Image dimensions
width = 1920
height = 1080

# Output settings
format = "png"
output = "word_definition"
output_path = "/path/to/custom/directory"  # Optional

# Wallpaper mode: "center", "crop", "fit", "span", "stretch", "tile"
wallpaper_mode = "crop"

# AI model configuration
model = "google/gemini-2.5-flash-lite-preview-06-17"
openrouter_api_key = "your-api-key-here"

# Color scheme
[colors]
bg_color = "#F5F7FA"           # Background color
word_color = "#1E3A8A"         # Main word color
heading_color = "#6366F1"      # Section headers (DEFINITION, EXAMPLE, etc.)
text_color = "#374151"         # Definition text
example_color = "#4B5563"      # Example sentence color
special_color = "#8B4513"      # Pronunciation color
border_color = "#E5E7EB"       # Optional border (remove for no border)

You can use any OpenRouter-compatible model:

• google/gemini-2.5-flash-lite-preview-06-17 (default - free tier)
• openai/gpt-4
• anthropic/claude-3-sonnet
• google/gemini-pro
• And many more!

# Generate with default config
wallnary

# Use custom config file
wallnary --config /path/to/custom/config.toml
wallnary -c custom_config.toml

wallnary --help

Options:

• -c, --config <FILE>: Path to custom config file
• -h, --help: Show help information
• -V, --version: Show version information

Wallnary supports full color customization. Colors are specified in hex format:

[colors]
bg_color = "#2D3748"      # Dark background
word_color = "#F7FAFC"    # Light word color
heading_color = "#4299E1" # Blue headers
text_color = "#E2E8F0"    # Light gray text
example_color = "#CBD5E0" # Muted example text
special_color = "#F56565" # Red pronunciation
border_color = "#4A5568"  # Gray border

[colors]
bg_color = "#1A202C"
word_color = "#F7FAFC"
heading_color = "#4299E1"
text_color = "#E2E8F0"
example_color = "#CBD5E0"
special_color = "#F56565"
border_color = "#2D3748"

[colors]
bg_color = "#F0FDF4"
word_color = "#14532D"
heading_color = "#16A34A"
text_color = "#166534"
example_color = "#15803D"
special_color = "#CA8A04"
border_color = "#BBF7D0"

[colors]
bg_color = "#F0F9FF"
word_color = "#0C4A6E"
heading_color = "#0284C7"
text_color = "#0369A1"
example_color = "#0EA5E9"
special_color = "#7C3AED"
border_color = "#BAE6FD"

Optional, default files are stored in temp dir for easy cleanup

output_path = "/Users/username/Pictures/Wallpapers"  # macOS
output_path = "C:\\Users\\username\\Pictures"        # Windows
output_path = "/home/username/Pictures"              # Linux

• center: Centers the image on the desktop
• crop: Crops the image to fit the desktop (default)
• fit: Scales the image to fit within the desktop
• span: Spans the image across multiple monitors
• stretch: Stretches the image to fill the desktop
• tile: Tiles the image across the desktop

# 4K Ultra HD
width = 3840
height = 2160

# 1440p
width = 2560
height = 1440

# 1080p (default)
width = 1920
height = 1080

# Mobile/Tablet
width = 1080
height = 1920

git clone https://github.com/yourusername/wallnary.git
cd wallnary
cargo build --release

• ab_glyph - Font rendering
• image - Image processing
• imageproc - Image drawing operations
• clap - Command line parsing
• serde - Serialization
• toml - Configuration parsing
• reqwest - HTTP client for API calls
• tokio - Async runtime
• wallpaper - Cross-platform wallpaper setting
• tempfile - Temporary file management
• dirs - Cross-platform directory paths

wallnary/
├── src/
│   └── main.rs          # Main application logic
├── fonts/
│   ├── Inter.ttf        # Regular font
│   └── Inter-i.ttf      # Italic font
├── Cargo.toml           # Dependencies and metadata
├── Cargo.lock           # Dependency lock file
└── README.md            # This file

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: cargo test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Inter Font Family - Beautiful typography
• OpenRouter - AI model access
• Rust Community - Amazing ecosystem

API Key Issues:

• Ensure your OpenRouter API key is valid and has sufficient credits
• Check that the key is properly set in your config file

Wallpaper Not Setting:

• Try running as administrator (Windows) or with proper permissions
• Check if your desktop environment supports wallpaper changes

Font Issues:

• Fonts are embedded in the binary, so this should be rare
• Try rebuilding the project if you encounter font problems

Config File Location:

• The app will tell you where your config file is located
• Use --config flag to specify a custom location

If you encounter any issues:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include your config file (remove API key!) and error messages