🎮 EmulationStation Media Converter

A powerful, automated media processing script designed specifically for EmulationStation frontends like ES-DE. Converts and optimizes video game artwork, screenshots, and videos with intelligent compression while maintaining high visual quality.

Tip

Who is this for? Useful for users that add their own media to frontends or gather media for obscure games that don't have entries on Screen Scraper or the Launchbox Database

✨ Features

• 🖼️ Smart Image Processing: Converts images to standardized PNG format with precise dimensions for each media type
• 🎥 Intelligent Video Compression: Lossless compression for files under 10MB, quality-focused H.265/H.264 encoding for larger files
• 📁 Batch Processing: Handles multiple folders simultaneously with progress tracking
• 🏷️ Custom File Mapping: JSON-based filename mapping for clean, organized media libraries

📋 Requirements

Dependencies

• ImageMagick - Image processing and conversion
• FFmpeg - Video processing and compression
• jq - JSON parsing for filename mappings
• bc - Mathematical calculations (GNU implicit)

Installation (macOS)

brew install imagemagick ffmpeg jq

Installation (Ubuntu/Debian)

sudo apt update
sudo apt install imagemagick ffmpeg jq bc

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/desaianand1/Emulation-Station-Media-Converter.git
cd Emulation-Station-Media-Converter

2. Set Up Directory Structure

├── input/
│   ├── screenshots/     # Game screenshots (→ 1920x1080 PNG)
│   ├── fanart/         # Fan artwork (→ 1920x1080 PNG)  
│   ├── titlescreens/   # Title screens (→ 1920x1080 PNG)
│   ├── covers/         # Box art covers (→ 420x680 PNG)
│   ├── marquees/       # Arcade marquees (→ 600x300 PNG)
│   ├── physicalmedia/  # Cart/disc images (→ 500x500 PNG)
│   └── videos/         # Gameplay videos (→ MP4, <10MB)
├── output/             # Processed files (auto-generated)
├── mappings.json       # Filename mappings
└── media_converter.sh  # Main script

3. Create Filename Mappings

Create a mappings.json file to map short input filenames to the exact ROM names in your EmulationStation (ES-DE) library:

{
  "sonic-1": "Sonic the Hedgehog",
  "mario-64": "Super Mario 64",
  "zelda-oot": "The Legend of Zelda: Ocarina of Time",
  "ff7": "Final Fantasy VII",
  "twewy": "The World Ends with You Final Remix [0100C1500B82E000][v0]",
  "disc-ely": "Disco Elysium - The Final Cut"
}

Tip

Why use mappings? This lets you organize your input files with simple, memorable names like zelda-oot.png while ensuring the output matches your exact ROM filename. No more typing ultra-long game names for every single media file!

4. Run the Converter

# Normal operation
./convert-media.zsh

# Preview what will be processed
./convert-media.sh --dry-run

# Debug mode for troubleshooting
./convert-media.sh --debug

📁 Supported Media Types

Folder	Purpose	Output Format	Dimensions
screenshots	In-game screenshots	PNG	1920×1080
fanart	Background artwork	PNG	1920×1080
titlescreens	Game title screens	PNG	1920×1080
covers	Box art/covers	PNG	420×680
marquees	Clear Logo marquees	PNG	600×300
physicalmedia	Cartridge/disc images	PNG	500×500
videos	Gameplay videos	MP4	<10MB target

🎬 Video Processing Logic

Note

The script uses intelligent compression strategies based on file size:

• Files < 10MB: Attempts lossless compression first
• Files ≥ 10MB: High-quality lossy compression targeting 9.5MB
• Codec Priority: H.265 (preferred) → H.264 (fallback)
• Quality Settings: CRF 28 (H.265) / CRF 26 (H.264)

Example Workflow

Input files (easy to type):

input/screenshots/
├── sonic-1.png
├── mario-64.jpg
├── zelda-oot.png
└── ff7.jpg

Mappings file:

{
  "sonic-1": "Sonic the Hedgehog (USA, Europe)",
  "mario-64": "Super Mario 64 (USA)",
  "zelda-oot": "Legend of Zelda, The - Ocarina of Time (USA) (Rev 1)",
  "ff7": "Final Fantasy VII (USA) (Disc 1)"
}

Output files (match your ROMs exactly):

output/screenshots/
├── Sonic the Hedgehog (USA, Europe).png
├── Super Mario 64 (USA).png  
├── Legend of Zelda, The - Ocarina of Time (USA) (Rev 1).png
└── Final Fantasy VII (USA) (Disc 1).png

Note

Files without mappings will keep their original filename (minus extension), so the system is completely optional but highly recommended for complex ROM collections.

📝 Usage Examples

Basic Processing

# Process all media in input folders
./media_converter.sh

Preview Mode

# See what files would be processed without making changes
./media_converter.sh --dry-run

Debug Mode

# Show detailed processing information and commands
./media_converter.sh --debug

Help

# Show all available options
./media_converter.sh --help

🛠️ Troubleshooting

Common Issues

"ImageMagick not found"

# macOS
brew install imagemagick

# Ubuntu/Debian  
sudo apt install imagemagick

"Invalid JSON in mappings.json"

• Validate your JSON syntax using jsonlint.com
• Ensure proper comma placement and quote matching

Video encoding fails

• Check if input video is corrupted: ffprobe input_file.mp4
• Verify FFmpeg installation: ffmpeg -version

---

Happy Gaming! 🎮