Artie is a powerful art scraper designed for Anbernic devices running MuOS. It helps you download and manage artwork for your ROMs, enhancing your gaming experience with beautiful visuals and a highly optimized, responsive interface.
- Modern dark UI with amber accent theme, system logos, status badges, and progress bars
- System logos displayed inline in the emulator list (configurable via
show_logos) - ROM detail view - press Y to preview scraped box art, preview images, and synopsis text
- Scraping interruption - press B to cancel batch scraping at any time with instant response
- Visual progress bar with ETA during batch scraping
- Optimized rendering with pre-allocated frame buffers, image caching, and double-buffered output
- Advanced caching system for ROM data, media thumbnails, logos, and API responses
- Enhanced navigation with page jumping capabilities (R1/R2, L1/L2)
- Fully configurable color theme via
config.json - Scrape per system or individual ROM
- Integrates seamlessly with MuOS
- Support for Box Art, Preview and Text (Synopsis)
- Image mask processing for custom box art and preview image enhancement
- Option to delete all media for a selected system or individual ROM
- Works on other OSs with minimal adaptation
- Supported media includes
["box-2D", "box-3D", "mixrbv1", "mixrbv2", "ss", "marquee"]
- Press Y on any ROM to see a full detail screen with box art, preview, and synopsis
- Cached media thumbnails for instant re-rendering
- Scrape directly from the detail view with A, view updates automatically
- Status badges (BOX/PRV/TXT) show what has been scraped at a glance
- Press B during batch scraping to cancel immediately
- Persistent input file descriptor ensures no button presses are lost
- Worker threads check cancellation between each API call for fast response
- "Cancelling..." feedback shown while active threads finish
- Pre-allocated frame buffer — reuses a single image buffer instead of allocating ~1.2MB per frame
- Image cache for ROM detail media — disk I/O and decoding only happens once per image
- Logo cache prevents repeated disk reads for system logos
- Unbuffered, non-blocking input using raw
os.readwithO_NONBLOCKfor reliable event handling - Persistent evdev file descriptor during scraping so kernel-queued events are never lost
- Double-buffered rendering eliminates screen flash on transitions
- Connection pooling for HTTP requests
- Dark theme with amber/gold accent and configurable color palette
- System logos rendered inline in the emulator list with aligned columns
- Color-coded status badges (B/P/T) showing which media each ROM has
- Progress bar overlay with percentage and ETA during batch scraping
- Pill-shaped control buttons, page indicators, and visual separators
- Page jumping with L1/R1 (by page) and L2/R2 (by 100)
- Separate position tracking for emulator and ROM lists
Artie supports intuitive navigation controls optimized for handheld gaming devices:
| Button | Action |
|---|---|
| D-pad | Navigate through systems |
| A | Select system |
| X | Delete all media for system |
| L1/R1 | Jump by page |
| L2/R2 | Jump by 100 |
| MENU | Exit application |
| Button | Action |
|---|---|
| D-pad | Navigate through ROMs |
| A | Scrape selected ROM |
| X | Delete media for selected ROM |
| Y | View ROM detail (box art, preview, synopsis) |
| B | Back to systems |
| START | Scrape all ROMs |
| L1/R1 | Jump by page |
| L2/R2 | Jump by 100 |
| MENU | Exit application |
| Button | Action |
|---|---|
| A | Scrape this ROM |
| B | Back to ROM list |
Artie includes image mask processing that applies custom PNG overlays to your downloaded artwork. This is useful for adding consistent borders, frames, or visual effects across all your box art and preview images.
To enable mask processing, configure the mask settings within each content type in your config.json:
{
"screenscraper": {
"content": {
"box": {
"enabled": true,
"type": "mixrbv2",
"height": 240,
"width": 320,
"apply_mask": true,
"mask_path": "assets/masks/box_mask.png",
"resize_mask": true
},
"preview": {
"enabled": true,
"type": "ss",
"height": 275,
"width": 515,
"apply_mask": true,
"mask_path": "assets/masks/preview_mask.png",
"resize_mask": true
}
}
}
}- PNG format with alpha channel for transparency
- Masks should match or exceed the dimensions of target artwork
- Different masks can be applied to different media types
- Set
resize_masktotrueto auto-fit mask dimensions - Disable with
apply_mask: falseif not needed for faster scraping
Follow these steps to install Artie:
-
Download the Latest Release:
- Visit the releases page and download the latest version of Artie.
-
Unzip the Downloaded File:
- Extract the contents of the downloaded zip file.
-
Configure Artie:
In
Artie/.artie/config.jsonensure:a)
romsis correctly configured to the path your roms are located.b) Add your Screenscraper credentials.
c) For the systems you are interested to scrape ensure the paths are correct.
d) Optional: Configure mask processing settings if you want to apply custom overlays to artwork.
{
"roms": "/mnt/sdcard/ROMS",
"logos": "assets/logos",
"show_logos": true,
"log_level": "info",
"colors": {
"primary": "#d4881c",
"primary_dark": "#a06210",
"secondary": "#1e1e2e",
"secondary_light": "#2a2a3c",
"secondary_dark": "#14141e"
},
"screenscraper": {
"username": "your_username",
"password": "your_password",
"devid": "base64_encoded_dev_id",
"devpassword": "base64_encoded_dev_password",
"threads": 10,
"show_scraped_roms": true,
"content": {
"synopsis": {
"enabled": true,
"lang": "en"
},
"box": {
"enabled": true,
"type": "mixrbv2",
"height": 240,
"width": 320,
"apply_mask": false,
"mask_path": "assets/masks/box_mask.png",
"resize_mask": true
},
"preview": {
"enabled": true,
"type": "ss",
"height": 275,
"width": 515,
"apply_mask": false,
"mask_path": "assets/masks/preview_mask.png",
"resize_mask": true
},
"regions": ["us", "eu", "jp", "wor"]
},
"systems": [
{
"dir": "SNES",
"id": "4",
"name": "Super Nintendo (SNES)",
"box": "/mnt/mmc/MUOS/info/catalogue/Nintendo SNES-SFC/box/",
"preview": "/mnt/mmc/MUOS/info/catalogue/Nintendo SNES-SFC/preview/",
"synopsis": "/mnt/mmc/MUOS/info/catalogue/Nintendo SNES-SFC/text/"
}
]
}
}See Configuration Options below for details on all settings.
-
Copy Files to MuOS:
- Copy the
Artiedirectory to/mnt/mmc/MUOS/application/.
This could be done via CLI with:
scp -r Artie/ root@<your IP>:/mnt/mmc/MUOS/application/ - Copy the
-
Launch Artie Scraper:
- Open MuOS and launch Artie Scraper from your applications menu.
roms: Path to your ROMs directory on the devicelogos: Path to system logo assetsshow_logos: Show system logos in the emulator list (true/false, defaulttrue)log_level: Logging verbosity ("info","debug", etc.)colors: UI color theme customizationscreenscraper.username/password: Your Screenscraper account credentialsscreenscraper.devid/devpassword: Base64-encoded developer API credentialsscreenscraper.threads: Number of concurrent scraping threadsscreenscraper.show_scraped_roms: Whether to display already-scraped ROMs in the listcontent.box.type: Box art media type (e.g."mixrbv2","box-2D","box-3D")content.preview.type: Preview media type (e.g."ss","marquee")content.*.apply_mask: Enable mask overlay for that media typecontent.*.mask_path: Path to the mask PNG filecontent.*.resize_mask: Whether to resize the mask to match the image dimensionscontent.regions: Preferred region priority for artwork lookupsystems: Array of system entries with ROMdir, Screenscraperid, and output paths forbox,preview, andsynopsis
Always check the log file first: Before reporting any errors or issues, please check the log file located at:
/mnt/mmc/MUOS/application/Artie/.artie/log.txt
This file contains detailed information about any errors, performance issues, or unexpected behavior that can help diagnose problems quickly.
- Check that all files are properly copied to
/mnt/mmc/MUOS/application/Artie/ - Verify that
config.jsonis properly formatted - Check the log file for specific error messages
- The caching system should improve performance after initial use
- Check available storage space on your device
- Review the log file for any caching issues
- Verify your Screenscraper credentials in
config.json - Check your internet connection
- Review API rate limiting messages in the log file
- Ensure ROM file paths are correctly configured
- Check that media files were successfully downloaded
- Verify file permissions and storage space
- Review the log file for download errors
- Masks not applying: Verify that
apply_maskis set totruefor the relevant content type inconfig.json - Mask files not found: Check that mask files exist at the specified
mask_path - Poor mask quality: Ensure mask files are PNG format with proper alpha channels
- Incorrect positioning: Enable
resize_maskor ensure mask dimensions match target artwork dimensions
If you continue to experience issues after checking the log file and trying the solutions above:
- Include relevant portions of your
log.txtfile when reporting issues - Provide your device model and MuOS version
- Describe the steps that led to the problem
- Open an issue on the GitHub issues page
- Atomic state transitions: Ensures UI consistency and prevents race conditions
- Pre-allocated frame buffer: Reuses a single image buffer across frames to avoid per-frame allocation
- Multi-level caching: Logos, media thumbnails, ROM data, and API responses are all cached
- Persistent evdev file descriptor: Keeps input device open during scraping for reliable event capture
- Modular design: Clean separation between UI, data management, and API layers
- Error recovery: Comprehensive error handling with graceful degradation
- Zero-allocation rendering: Frame buffer reused each cycle, cleared in-place
- Image cache: ROM detail media loaded and resized once, served from memory on subsequent views
- Non-blocking input: Raw
os.readwithO_NONBLOCKfor reliable, low-latency polling - Thread-safe cancellation:
threading.Eventchecked between API calls in worker threads - Connection pooling: Reused HTTP sessions for scraping requests
We welcome contributions! Feel free to open issues or submit pull requests (PRs) to help improve Artie.
-
Fork the Repository:
- Click the "Fork" button at the top right of the repository page.
-
Clone Your Fork:
- Clone your forked repository to your local machine using
git clone.
- Clone your forked repository to your local machine using
-
Create a Branch:
- Create a new branch for your feature or bug fix.
-
Make Changes:
- Implement your changes and commit them with clear and concise messages.
-
Submit a Pull Request:
- Push your changes to your fork and submit a pull request to the main repository. Be sure to mention what feature you are implementing or which bug you are fixing.
If you encounter any bugs, please:
- Check the log file first at
/mnt/mmc/MUOS/application/Artie/.artie/log.txt - Open an issue on the GitHub issues page with:
- Detailed information about the problem
- Relevant log file excerpts
- Steps to reproduce the issue
- Your device and MuOS version information
This project is licensed under the MIT License. See the LICENSE file for details.
Thank you for using Artie! This enhanced version provides a significantly improved experience with better performance, reliability, and user experience on your Anbernic device.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
