sonicgrid-sdk

v1.0.2

Published

2 months ago

Live SFX Generator SDK for HTML5 games - Let players generate AI-powered sound effects during gameplay

SonicGrid SDK

Live SFX Generator SDK for HTML5 games. Let players generate AI-powered sound effects during gameplay via a hotkey-triggered dialog.

Features

Hotkey-triggered sound generation dialog (default: *)
Automatic game pause/resume integration
Multiple audio library adapters: Pixi.js, Three.js, Howler.js, Web Audio API
Auto-detection of your game's audio system
Sound caching and management
Cross-origin message protocol for iframe integration

Installation

Load from SonicGrid (Recommended)

The easiest way to get started is to load the SDK directly from the SonicGrid website:

<script src="https://sonicgrid.org/sdk/sonicgrid-sdk.umd.js"></script>

Alternative mirror:

<script src="https://soundgrid.replit.app/sdk/sonicgrid-sdk.umd.js"></script>

npm Package

For bundled projects, install via npm:

npm install sonicgrid-sdk

Other CDN Options

You can also use unpkg or jsdelivr:

<!-- unpkg -->
<script src="https://unpkg.com/sonicgrid-sdk@latest/sonicgrid-sdk.umd.js"></script>

<!-- jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/sonicgrid-sdk@latest/sonicgrid-sdk.umd.js"></script>

Quick Start

Script Tag (UMD)

When loading from sonicgrid.org via script tag, SonicGridSDK is available as a global:

<!DOCTYPE html>
<html>
<head>
  <script src="https://sonicgrid.org/sdk/sonicgrid-sdk.umd.js"></script>
</head>
<body>
  <script>
    const sdk = SonicGridSDK.init({
      hotkey: '*',
      adapter: 'auto',
      onPause: () => game.pause(),
      onResume: () => game.resume(),
      onSoundReady: ({ id, prompt, duration, play }) => {
        console.log(`Sound "${prompt}" ready (${duration}s)`);
        play();
      },
    });
  </script>
</body>
</html>

ES Module

For bundled projects using npm:

import { SonicGridSDK } from 'sonicgrid-sdk';

const sdk = SonicGridSDK.init({
  hotkey: '*',
  adapter: 'auto', // or 'pixi', 'three', 'howler', 'native'
  onPause: () => {
    game.pause();
  },
  onResume: () => {
    game.resume();
  },
  onSoundReady: ({ id, prompt, duration, play }) => {
    console.log(`Sound "${prompt}" ready (${duration}s)`);
    // Optionally play immediately
    play();
  },
});

// Later: clean up
sdk.destroy();

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | hotkey | string | '*' | Key to trigger the dialog | | adapter | string | 'auto' | Audio adapter: 'pixi', 'three', 'howler', 'native', or 'auto' | | adapterContext | object | {} | Engine-specific context (e.g., PIXI.sound, THREE.AudioListener) | | onPause | function | - | Called when dialog opens (pause your game) | | onResume | function | - | Called when dialog closes (resume your game) | | onSoundReady | function | - | Called when a sound is generated and ready | | originAllowlist | string[] | [] | Additional allowed origins for cross-origin communication | | dialogUrl | string | - | Custom dialog URL (for self-hosted setups) |

API Reference

Dialog Control

sdk.openDialog();     // Open the dialog programmatically
sdk.closeDialog();    // Close the dialog
sdk.toggleDialog();   // Toggle dialog open/closed
sdk.isDialogOpen();   // Check if dialog is open

Sound Management

sdk.playSound(id);              // Play a registered sound
sdk.stopSound(id);              // Stop a specific sound
sdk.stopAllSounds();            // Stop all sounds
sdk.getSounds();                // Get Map of all registered sounds
sdk.hasSound(id);               // Check if sound exists
sdk.registerSound(id, buffer);  // Register sound manually
sdk.unregisterSound(id);        // Remove a sound

SDK Control

sdk.setHotkey('`');   // Change the hotkey
sdk.enable();         // Enable hotkey listener
sdk.disable();        // Disable hotkey listener
sdk.isGamePaused();   // Check if game is paused by SDK
sdk.getVersion();     // Get SDK version
sdk.destroy();        // Clean up all resources

Adapter Examples

Pixi.js

import { SonicGridSDK } from 'sonicgrid-sdk';
import { sound } from '@pixi/sound';

const sdk = SonicGridSDK.init({
  adapter: 'pixi',
  adapterContext: { sound },
  onPause: () => app.ticker.stop(),
  onResume: () => app.ticker.start(),
});

Three.js

import { SonicGridSDK } from 'sonicgrid-sdk';

const listener = new THREE.AudioListener();
camera.add(listener);

const sdk = SonicGridSDK.init({
  adapter: 'three',
  adapterContext: { listener },
  onPause: () => clock.stop(),
  onResume: () => clock.start(),
});

Howler.js

import { SonicGridSDK } from 'sonicgrid-sdk';

const sdk = SonicGridSDK.init({
  adapter: 'howler',
  onPause: () => Howler.mute(true),
  onResume: () => Howler.mute(false),
});

Web Audio API (Native)

import { SonicGridSDK } from 'sonicgrid-sdk';

const audioContext = new AudioContext();

const sdk = SonicGridSDK.init({
  adapter: 'native',
  adapterContext: { audioContext },
  onPause: () => audioContext.suspend(),
  onResume: () => audioContext.resume(),
});

Browser Support

Chrome 80+
Firefox 78+
Safari 14+
Edge 80+

Requires Web Audio API support.

Changelog

v1.0.3

Fixed Three.js adapter audio cleanup (memory leak in onEnded callback)
Fixed Pixi.js adapter base64 conversion for large audio files
Improved WebAudio adapter initialization with null safety
Added null checks to isDialogOpen() for destroyed SDK instances
Fixed hotkey normalization for edge cases with undefined keys
Added error handling for dialog creation failures

v1.0.2

Initial stable release
Support for Pixi.js, Three.js, Howler.js, and Web Audio API
Hotkey-triggered dialog with pause/resume hooks
Cross-origin message protocol for iframe isolation

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

SonicGrid SDK

Features

Installation

Load from SonicGrid (Recommended)

npm Package

Other CDN Options

Quick Start

Script Tag (UMD)

ES Module

Configuration Options

API Reference

Dialog Control

Sound Management

SDK Control

Adapter Examples

Pixi.js

Three.js

Howler.js

Web Audio API (Native)

Browser Support

Changelog

v1.0.3

v1.0.2

License