rom-scout - Interactive Demo & Documentation

Interactive Demo

This page demonstrates the rom-scout library with interactive examples. Each example includes runnable code that you can test with the included ROM files: Pac-Man (Arcade) and Sonic the Hedgehog (Master System).

Installation: npm install rom-scout

1. Calculate ROM Hashes

Calculate MD5, SHA-1, and CRC32 hashes for any ROM file. This works entirely client-side without any API calls.

JavaScript

import { RomScout } from 'rom-scout';

// Create a scout instance (no API needed for hashing)
const scout = new RomScout();

// Load a ROM file (in browser from file input)
const fileInput = document.getElementById('rom-file');
const file = fileInput.files[0];

// Calculate hashes
const hashes = await scout.hash(file);

console.log('MD5:', hashes.md5);
console.log('SHA-1:', hashes.sha1);
console.log('CRC32:', hashes.crc32);

Select ROM:

2. Hasheous API - Hash-based Lookup

Fetch metadata from a Hasheous server using ROM hashes. Hasheous is an open-source ROM metadata server.

JavaScript

import { RomScout } from 'rom-scout';

// Create a scout instance with Hasheous
const scout = new RomScout({
  provider: 'hasheous',
  hasheousUrl: 'https://your-hasheous-instance.com'
});

// Load a ROM file
const file = document.getElementById('rom-file').files[0];

// Identify the ROM and fetch metadata
const metadata = await scout.identify(file);

if (metadata) {
  console.log('Title:', metadata.title);
  console.log('Platform:', metadata.platform);
  console.log('Publisher:', metadata.publisher);

  // Display cover art if available
  if (metadata.images && metadata.images.length > 0) {
    console.log('Cover:', metadata.images[0].url);
  }
}

Hasheous URL:

Note: Using the free public instance at hasheous.org. You can also self-host your own instance.
On GitHub Pages, a CORS proxy is automatically used to bypass browser restrictions.

Select ROM:

3. Extensibility Hooks

The lookupMultiple helper is available for future multi-provider setups. Today it simply wraps the Hasheous lookup so you can plug in your own providers later.

JavaScript

import { RomScout } from 'rom-scout';

// Configure Hasheous (additional providers can be added in the future)
const scout = new RomScout({
  hasheousUrl: 'https://your-hasheous-instance.com'
});

// Load a ROM file
const file = document.getElementById('rom-file').files[0];

// Calculate hashes first
const hashes = await scout.hash(file);

// Create lookup request
const request = {
  md5: hashes.md5,
  sha1: hashes.sha1,
  crc32: hashes.crc32,
  filename: file.name
};

// Try providers in order (currently only Hasheous)
const metadata = await scout.lookupMultiple(
  request,
  ['hasheous']
);

if (metadata) {
  console.log('Found in:', metadata.source);
  console.log('Title:', metadata.title);
}

Installation & Usage

Node.js / npm

npm install rom-scout

import { RomScout } from 'rom-scout';
import { readFileSync } from 'fs';

const scout = new RomScout({
  provider: 'hasheous',
  hasheousUrl: 'https://your-hasheous-instance.com'
});

const romData = readFileSync('pacman.zip');
const metadata = await scout.identify(romData, 'pacman.zip');
console.log(metadata);

Browser / CDN

<script type="module">
  import { RomScout } from 'https://unpkg.com/rom-scout/dist/bundles/rom-scout.esm.js';

  const scout = new RomScout();
  // Use scout...
</script>