888wing/8bit-music-generator

Chipgen

Use the bundled Node script to generate deterministic 8-bit music and SFX locally. Require Node.js 16 or newer.

The script is at scripts/chipgen.js relative to this skill folder. Run it with node and capture stdout as JSON. Errors are written to stderr.

Use English-first wording for new feature work, generated manifests, and user-facing summaries. Preserve Traditional Chinese support as a secondary locale when editing the browser UI.

Workflow

1. Resolve the output directory. If the user does not specify one, use generated-audio/ in the current project.
2. Choose parameters from the user request using the brief-to-parameters rules below. If a seed is not provided, choose one and report it so the result can be reproduced.
3. Run node <skill-dir>/scripts/chipgen.js list when you need valid moods, keys, or SFX categories.
4. Generate the requested assets. Use music-pack when the user asks for a soundtrack pack, scene set, or "different scenes but same style".
5. Read the JSON manifest from stdout and report the generated file paths, seed, mood/category, BPM, and any MIDI/stem/tres outputs.

Brief-to-Parameters

Infer parameters from natural-language game audio briefs. Prefer a reasonable first pass over asking questions unless the request has incompatible constraints.

Music mood selection

• Use adventure for overworld, journey, opening, exploration, heroic, hopeful, bright, title-screen, map, discovery, forest, sky, sea, or general platformer BGM.
• Use battle for regular combat, chase, danger, action, timed challenge, enemy waves, fast arcade intensity, or tense gameplay that is not a boss fight.
• Use boss for boss, final boss, rival battle, climactic, oppressive, demonic, high-stakes, late-game, raid, or "make it more intense than battle".
• Use town for town, village, shop, inn, home base, safe zone, cozy, friendly NPC, crafting, farm, light menu BGM, or everyday scenes.
• Use dungeon for cave, ruins, mystery, stealth, maze, night, sewer, laboratory, alien, haunted, underwater, snow/ice when the brief says lonely/cold/mysterious rather than tragic.
• Use sad for loss, game over, memory, ending, ruined home, farewell, death, loneliness, melancholy, emotional cutscene, or snow/ice when the brief is explicitly sorrowful.

When a brief mixes moods, choose the gameplay function first, then emotion. Example: "sad boss battle" should be boss; "lonely snow level but not too slow" should usually be dungeon with an upper-range BPM, not sad.

Music key, bars, and BPM

• Use explicit key requests directly. Map "minor" briefs to A, D, or E when no exact key is specified. Map bright/heroic/cozy briefs to C, F, or G. Use random when the user wants surprise or gives no tonal direction.
• Use 8 bars for quick previews, short loops, stingers, or many candidates. Use 16 bars for normal looping BGM. Use 32 bars for longer ambient/background requests.
• If BPM is unspecified, let the generator choose within the mood range. If the user asks for faster/slower, set BPM near the top/bottom of the selected mood range. If the user says "not too slow", avoid sad unless the emotion demands it, or set sad near 92 BPM.
• For final or production-ready BGM, include --midi --stems. For exploration, include --variants 5 unless the user asks for a single result.

Music pack selection

Use music-pack when the request asks for a complete small soundtrack, a scene pack, a set of cues, or music for multiple game scenes in one coherent style.

music-pack generates six cues from one seed family and one resolved key:

• Theme: adventure, 16 bars
• Town: town, 16 bars
• Dungeon: dungeon, 16 bars
• Battle: battle, 8 bars
• Boss: boss, 16 bars
• Ending: sad, 8 bars

This is not the same as --variants. Variants keep one scene fixed and change only derived seeds. A music pack changes the scene function while keeping the tonal center and seed family coherent.

SFX category selection

• Use coin for pickup, collect, reward, gem, item acquired, score, or confirm-positive.
• Use confirm for menu OK, accept, positive UI click, small success, or dialogue continue.
• Use cancel for back, deny, invalid, UI error, closed menu, or negative feedback.
• Use jump for jump, hop, bounce, spring, UI upward motion, or character lift.
• Use dash for dash, dodge, quick movement, speed burst, or air step.
• Use land for landing, stomp, heavy footstep, ground touch, or small body impact.
• Use laser for shoot, projectile, zap, ray, spell cast, blaster, or quick magic attack.
• Use slash for sword, blade, claw, swipe, cut, melee attack, or fast whoosh-hit.
• Use hit for damage, punch, impact, hurt, enemy struck, or body contact.
• Use block for shield, parry, guard, armor hit, deflect, or metal/stone impact.
• Use explosion for explosion, break, crash, blast, destruction, barrel, bomb, or big impact.
• Use powerup for upgrade, level up, unlock, buff, heal, rare item, success flourish, or transformation.
• Use heal for healing, restore, potion, revive, magic sparkle, or gentle positive effect.
• Use teleport for teleport, vanish, warp, portal, respawn, or phase shift.
• Use door for door, switch, lever, gate, mechanism, lock, or heavy UI panel.
• Use chest for treasure chest, reward reveal, item fanfare, loot open, or rare pickup.
• Use blip for UI cursor, menu move, small select, typing, notification, low-key beep, or neutral interface feedback.
• Use alert for warning, alarm, detection, exclamation, low health, or timed danger.
• Use fall for falling, fail, drop, lose, wrong answer, down transition, or game-over sting.
• Use defeat for death, player lost, game over, enemy defeated, or dramatic failure.
• Use whoosh for air movement, swing prep, transition, fast pass-by, or abstract movement.

For repeated gameplay SFX, generate --variants 5. For UI sounds, generate 3-5 candidates and keep durations short by choosing blip, coin, or hit rather than random.

Commands

List supported values:

node <skill-dir>/scripts/chipgen.js list

Generate BGM:

node <skill-dir>/scripts/chipgen.js music \
  --mood battle \
  --key A \
  --bars 16 \
  --seed 42 \
  --stems \
  --midi \
  --out generated-audio/bgm

Generate BGM candidates from one seed family:

node <skill-dir>/scripts/chipgen.js music \
  --mood boss \
  --key A \
  --bars 16 \
  --seed 42 \
  --variants 5 \
  --midi \
  --out generated-audio/bgm

Generate a six-cue music pack:

node <skill-dir>/scripts/chipgen.js music-pack \
  --key C \
  --seed 42 \
  --stems \
  --midi \
  --out generated-audio/bgm-pack

Generate one SFX:

node <skill-dir>/scripts/chipgen.js sfx \
  --cat coin \
  --seed 123 \
  --out generated-audio/sfx

Generate an SFX variation pool for Godot:

node <skill-dir>/scripts/chipgen.js sfx \
  --cat hit \
  --seed 88 \
  --variants 5 \
  --tres generated-audio/sfx/hit_pool.tres \
  --res-prefix res://assets/audio/sfx/ \
  --out generated-audio/sfx

Parameters

Supported moods are adventure, battle, town, dungeon, sad, and boss.

Supported SFX categories are coin, confirm, cancel, jump, dash, land, laser, slash, hit, block, explosion, powerup, heal, teleport, door, chest, blip, alert, fall, defeat, whoosh, and random.

Useful options:

• --bpm N: Override generated BPM.
• --bars N: Music length. Use 8, 16, or 32 unless the user asks otherwise.
• --sr N: Sample rate. Default is 44100.
• --midi: Export MIDI for music.
• --stems: Export separate music stems.
• --variants N: Generate a seed family. For music, keep mood, resolved key, bars, and BPM fixed while deriving new seeds. For SFX, keep category fixed.
• --no-mix: Skip mixed WAV.
• --no-normalize: Disable SFX normalization.
• --tres PATH: Write a Godot AudioStreamRandomizer resource.
• --res-prefix PREFIX: Resource prefix used inside the generated Godot .tres.

Defaults

For game-ready BGM, prefer --stems --midi unless the user only wants a quick preview.

For music exploration, generate 5-10 candidates from one base seed. In CLI output, variantIndex: 0 is the base seed and later items use variantSeed = (baseSeed + 0x9E3779B9 * index) >>> 0 with index starting at 1. Keep mood, resolved key, bars, and bpm fixed so the candidates feel related rather than random.

For a compact game soundtrack, prefer music-pack --stems --midi. It produces Theme, Town, Dungeon, Battle, Boss, and Ending cues from one seed family.

For SFX meant for repeated in-game playback, prefer --variants 5 and keep the same category with different seeded variants.

For Godot projects, use assets/audio/bgm and assets/audio/sfx when those directories exist. Remind the user that Godot WAV imports may need loop mode enabled for looping BGM.