ESRB Rating Slate Generator

A Node.js-based tool for generating broadcast-compliant ESRB Rating Slates. This application can scrape the official ESRB website for game data or generate slates from manual input, rendering high-resolution PNG images suitable for video trailers.

It can be used as a Command Line Interface (CLI) or imported as a TypeScript/Node.js Library.

Example generation for Borderlands 4

Web Interface

Check out the ESRB Slate Generator Web UI — A modern, responsive web interface for generating broadcast-ready ESRB rating slates. This tool serves as a frontend for the esrb-slate-gen library.

Features

• Dual Mode: Works as a CLI tool and an importable Library.
• Automated Scraping: Fetches rating category and content descriptors directly from ESRB.org.
• Manual Mode: Generate slates by manually specifying rating, descriptors, and interactive elements.
• Platform Filtering: Optional filtering to target specific game versions (e.g., PS5 vs Xbox).
• High-Quality Rendering: Generates 1920x1080 (Full HD) images with correct layout and standard icons.
• Docker Support: Fully containerized environment ensuring consistent font and graphics rendering.
• Caching: Caches scraped data locally to reduce network requests.
• TypeScript: Type-safe codebase.

Prerequisites

• Docker (Recommended for CLI)
• OR Node.js v20, v22, or v24 with system dependencies for node-canvas (libcairo, libpango) installed (for Library/Local usage).

1. CLI Usage

Using Docker

1. Build the image:

   docker build -t esrb-gen .

2. Run the generator: Mount the current directory to /output inside the container to save the file locally.

   docker run --rm \
     -v $(pwd)/output:/output \
     -v $(pwd)/.esrb-cache:/app/.esrb-cache \
     esrb-gen \
     --game "Borderlands 4" \
     --platform "PC" \
     --output "/output/my-slate.png"

   [!NOTE] To make caching work across Docker runs (which are ephemeral), you must mount the .esrb-cache directory to /app/.esrb-cache inside the container as shown above.

Using NPM (Node.js)

You can use the tool directly via npx or by installing it globally.

Quick Run (npx): Since the package name (esrb-slate-gen) differs from the binary command (esrb-gen), use the -p flag:

npx -p esrb-slate-gen esrb-gen --game "God of War"

Global Installation:

npm install -g esrb-slate-gen

# Usage
esrb-gen --url "https://www.esrb.org/ratings/40649/borderlands-4/"

# By ID
esrb-gen --esrb-id 40649

Manual Generation Example:

# If installed globally:
esrb-gen -r "M" -d "Blood, Violence" -i "In-Game Purchases"

# Or via npx:
npx -p esrb-slate-gen esrb-gen -r "M" -d "Blood, Violence" -i "In-Game Purchases"

2. Library Usage

You can use esrb-slate-gen typically as a dependency in your own Node.js project.

Installation

npm install esrb-slate-gen

Example Code

import { ScraperService, RenderService, ESRBData } from 'esrb-slate-gen';
import path from 'path';

async function generateSlate() {
  // 1. Get Data (scrape or create manually)
  const scraper = new ScraperService();
  const data = await scraper.getGameData('Hades', 'PC');

  // OR Manual Data:
  /*
  const data: ESRBData = {
    title: 'My Game',
    ratingCategory: 'T',
    descriptors: ['Fantasy Violence'],
    interactiveElements: []
  };
  */

  // 2. Render Image
  // You can optionally pass specific assets directory if needed
  const renderer = new RenderService();

  await renderer.generate(
    data,
    path.join(__dirname, 'output.png'),
    0, // margin (0 = variable width/fullscreen)
    false, // is4k
    9 / 16, // heightFactor (or pass 0 for auto-calculation)
  );
}

generateSlate();

CLI Options

| Option                 | Alias | Description | Required            | Default | | :----------------------------------------------------------------------------------------------------- | :---- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :------------------ | | --game | -g | Game title to search for | Yes (or -u/-r/-e) | - | | --platform | -p | Specific platform (e.g., "Xbox", "PS5"). Used in addition to --game. | No | - | | --url | -u | Direct ESRB URL (e.g., https://www.esrb.org/ratings/...) | Yes (or -g/-r/-e) | - | | --esrb-id | -e | ESRB Game ID (e.g., 40649) | Yes (or -g/-r/-u) | - | | --rating | -r | Manual Rating Category. Valid values: E, E10plus, T, M, AO, RP | Yes (if no -g/-u/-e) | - | | --descriptors | -d | Manual Content Descriptors (comma-separated) | No | - | | --interactive | -i | Manual Interactive Elements (comma-separated) | No | - | | --output | -o | Output file path. Extensions .png, .jpg, .jpeg supported. Defaults to .png if missing/invalid. | No | output/output.png | | --margin | -m | Horizontal margin (white box indentation) | No | 0 (Full Screen) | | --aspect-ratio | -a | Content box aspect ratio. Default 0 margin expands resolution (Variable Width). Margin > 0 uses fixed 1920x1080 (Letterboxed). | No | auto | | --4k | | Generate in 4K resolution (3840x2160) | No | false | | --force | | Ignore cache and force re-download of game data | No | false |

Development

Setup

1. Install Dependencies:

   npm install

2. Download Assets: This script downloads necessary fonts and icons to the assets/ directory.

   npm run download-assets

Code Quality

This project uses Prettier for formatting and ESLint for linting. These checks are enforced in CI.

• Check Formatting: npm run format:check
• Fix Formatting: npm run format
• Lint: npm run lint
• Fix Lint: npm run lint:fix

Testing

Run the test suite using Jest:

npm test

License

This project is released under the MIT License.