Scraping
“Scraping” is how Cocoon fills your library with beautiful box art, game logos, background images, and info like release dates and descriptions. Instead of hunting down images yourself, Cocoon can grab them automatically from online game databases.
This is probably the first thing you’ll want to do after setup — it turns a plain list of filenames into a gorgeous, visual game library.
Where Does the Art Come From?
Cocoon pulls from two sources. You can use one or both:
SteamGridDB
A community-run collection of game artwork. It’s especially great for:
- Box art and cover images
- Wide “hero” banner images
- Clean transparent game logos
- Square icons
To set it up:
- Create a free account at steamgriddb.com.
- Grab your API key from your profile page.
- In Cocoon, go to Settings → Integrations → SteamGridDB and paste your key.
ScreenScraper
A massive retro gaming database with deep metadata. Great for:
- Box art (2D and 3D renders)
- Game descriptions, genres, developers, and release dates
- Screenshots and fan art
- Logo/wheel art
To set it up:
- Register for free at screenscraper.fr.
- In Cocoon, go to Settings → Integrations → ScreenScraper and enter your username and password.
You don’t need both sources, but having both gives Cocoon more places to search and usually gets better results.
Scraping Your Whole Library
Once you’ve set up at least one source:
- Go to Settings → Library & Data → Scrape.
- Choose your settings (more on that below).
- Tap Start Scraping.
Cocoon will work through your entire library, game by game. You’ll see a progress notification at the top of the screen showing which game it’s currently working on and how far along it is.
The best part? Scraping runs in the background. You can go back to your grid, browse around, even launch games — it’ll keep downloading art behind the scenes.
Scraping Settings
Before you start, you can tweak a few things:
What to Download
- Artwork — Box art, logos, and hero images. Toggle on or off.
- Metadata — Game titles, descriptions, release dates, genres, etc. Toggle on or off.
- RetroAchievements Hash — Links your ROMs to RetroAchievements for tracking achievements. Toggle on if you use RA.
Source Priority
You can drag to reorder which source Cocoon tries first. For example, you might prefer SteamGridDB art but ScreenScraper metadata.
Scrape Mode
| Mode | When to use it |
|---|---|
| Missing Only | The default — only grabs stuff for games that don’t have it yet. Fast! |
| Force Art Refresh | Re-downloads all artwork, even if you already have images. Good if you changed your source priority. |
| Force Metadata Refresh | Re-fetches all game info. |
| Force Full Refresh | Nuclear option — re-scrapes everything from scratch. |
Scraping One Game at a Time
Want to hand-pick artwork for a specific game? You can!
- Highlight the game on your grid.
- Press Y → Edit.
- Select Icon, Logo, or Hero.
- A media picker opens with two panes:
- Left side: Choose your source (SteamGridDB or ScreenScraper).
- Right side: Browse the available images.
- Pick the one you like and it downloads instantly.
Pro tips for the media picker:
- Press Y to change the search term if Cocoon didn’t find the right game.
- You can also upload your own image from your device instead.
- Navigate between the source list and image grid with the D-pad.
What Gets Downloaded
Cocoon grabs three types of images for each game:
| Type | What it looks like | Where you’ll see it |
|---|---|---|
| Icon | Box art / cover art (square-ish) | The main game tile on your grid |
| Logo | Transparent game title text/art | Overlaid on the hero view |
| Hero | Wide cinematic artwork | Background of the hero/info area |
All images are saved on your device, so they load instantly and work offline.
How Does Cocoon Find the Right Game?
Cocoon uses a few tricks to match your games to the right entry in the database:
- File fingerprint — It checks a unique digital signature of your ROM file. This is the most accurate method.
- Previous matches — If a game was matched before, Cocoon remembers it.
- Name search — If fingerprinting doesn’t work, it searches by the game’s name.
Most games match automatically, but for tricky titles you can always use the manual media picker.
ES-DE Compatibility
If you’ve used EmulationStation (ES-DE) before, good news — Cocoon stores its media in a compatible folder structure. You can:
- Export your Cocoon metadata in ES-DE format via Settings → Library & Data → Export Metadata.
- Import from an existing ES-DE setup via Settings → Library & Data → ES-DE Migration. Check out ES-DE Migration for the full walkthrough.