Rename files based on their metadata. Automatically extracts titles, dates, and descriptions from your files to give them meaningful names.

Available Tools:

• 🖥️ CLI - Command-line tool for automation and scripting (Windows, macOS, Linux)
• 🎨 GUI - Visual dual-pane interface (Midnight Commander style) for all platforms

Transforms meaningless filenames into descriptive ones using embedded metadata:

IMG_2847.jpg           → 2024-03-15_sunset.jpg
document.pdf           → Annual_Report_2024.pdf
screenshot_20241015.png → 輸入_姓名.png (Chinese OCR)
VID_20241015.mp4       → Product_Demo_Video.mp4 (frame OCR)
IMG_3847.heic          → Family_Reunion_2024.heic

brew tap h4x0r/nameback
brew install nameback

Automatically installs all dependencies (exiftool, tesseract, ffmpeg, imagemagick).

Download and install nameback-x86_64-pc-windows-msvc.msi from releases

What you get:

• CLI: Type nameback in any terminal (automatically added to PATH)
• GUI: Launch from Start Menu → nameback

Alternative: Portable Executables

For portable use without installation, download individual executables from releases:

• CLI: nameback-x86_64-pc-windows-msvc.exe
• GUI: nameback-gui-x86_64-pc-windows-msvc.exe

Then install dependencies:

nameback --install-deps

cargo install nameback
nameback --install-deps

See all installation options

# Preview what will change (safe, no modifications)
nameback ~/Pictures --dry-run

# Rename the files
nameback ~/Pictures

Windows: Launch nameback from Start Menu macOS/Linux: Run ./nameback-gui (download from releases)

1. Click "📁 Select Directory" to choose a folder
2. Review proposed renames in the right pane (original names on left)
3. Check/uncheck files to rename
4. Click "✅ Rename X Files" to apply changes

Features:

• 📂 Visual dual-pane interface (Midnight Commander style)
• ✅ Checkbox selection for individual files
• 🔄 Real-time preview before renaming
• ✔️ Color-coded status (pending, success, error)

# Organize recovered files from data recovery
nameback /tmp/photorec --dry-run

# Process screenshots folder with OCR
nameback ~/Desktop/Screenshots --verbose

# Clean up iPhone photo exports (HEIC support)
nameback ~/Desktop/iPhone_Export

# Organize downloaded documents
nameback ~/Downloads --dry-run

• Intelligent Naming Heuristics - Quality scoring system to choose the best name from multiple sources
• Smart Photo Renaming - Uses EXIF data (date, description, GPS location) from JPEG, PNG, HEIC/HEIF
• PDF Intelligence - Extracts titles from metadata or document content, with OCR for scanned PDFs
• Enhanced Text Extraction - Markdown frontmatter, CSV semantic columns, nested JSON/YAML fields
• Context-Aware Naming - Leverages directory structure and filename analysis for better names
• Multi-Frame Video Analysis - Extracts multiple frames (1s, 5s, 10s) and picks the best OCR result
• Series Detection - Automatically detects and maintains file series numbering (e.g., vacation_001.jpg, vacation_002.jpg)
• Format-Specific Handlers - Email files (.eml), web archives (.html), archives (.zip, .tar), source code docstrings
• Location & Timestamp Enrichment - Optional GPS coordinates and formatted timestamps in filenames
• Multi-Language OCR - Supports Traditional Chinese, Simplified Chinese, English (and 160+ more languages)
• Advanced Filtering - Automatically rejects low-quality names (errors, device names, generic placeholders)
• HEIC Support - Native support for Apple's High Efficiency Image Format
• Safe & Secure - Preview mode, no overwrites, blocks root execution, same-directory only

nameback <directory>                        # Rename files
nameback <directory> --dry-run              # Preview changes only
nameback <directory> --verbose              # Show detailed progress
nameback <directory> --skip-hidden          # Skip hidden files
nameback <directory> --include-location     # Add GPS coordinates to photo/video names
nameback <directory> --include-timestamp    # Add formatted timestamps to names
nameback <directory> --multiframe-video     # Use multi-frame video analysis (slower but better)
nameback --check-deps                       # Check dependencies
nameback --install-deps                     # Install dependencies

This project uses a Cargo workspace with 3 crates:

• nameback-core - Shared library with core rename logic
• nameback-cli - Command-line tool
• nameback-gui - GUI application (egui-based)

# Build everything
cargo build --release

# Binaries:
# target/release/nameback (CLI)
# target/release/nameback-gui (GUI)

# CLI only
cargo build --release -p nameback

# GUI only
cargo build --release -p nameback-gui

# Core library only
cargo build --release -p nameback-core

cargo test --workspace