pingthings 0.1.0 → 0.2.1

package/LICENSE

@@ -6,6 +6,25 @@
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
-Audio assets are from Seven Kingdoms: Ancient Adversaries
-Copyright 1997,1998 Enlight Software Ltd.
-Licensed under GPL v2.
+This project is licensed under GPL v2. Audio assets are sourced from
+multiple open source projects under compatible licenses:
+
+7kaa-soldiers: Seven Kingdoms: Ancient Adversaries
+  Copyright 1997,1998 Enlight Software Ltd. — GPL v2
+
+wesnoth-combat: Battle for Wesnoth
+  Copyright Wesnoth contributors — GPL v2+
+
+openarena-announcer: OpenArena
+  Copyright OpenArena contributors — GPL v2
+
+freedoom-arsenal: Freedoom
+  Copyright Freedoom contributors — BSD-3-Clause
+
+warzone2100-command: Warzone 2100
+  Copyright Warzone 2100 Project — GPL v2
+
+0ad-civilizations: 0 A.D.
+  Copyright Wildfire Games — CC-BY-SA 3.0
+  Distributed as part of this aggregate work alongside GPL v2 code.
+  See packs/0ad-civilizations/manifest.json for full attribution.

package/README.md

@@ -126,10 +126,15 @@ For different sounds based on what Claude is doing, set up multiple hooks:
 |---------|-------------|
 | `pingthings play [sound] [--event type]` | Play a sound (random, specific, or event-based) |
 | `pingthings list` | Show available sound packs |
+| `pingthings select` | Interactive pack selector |
 | `pingthings use <pack>` | Set the active sound pack |
 | `pingthings preview <pack>` | Preview a random sound from a pack |
+| `pingthings test-events [pack]` | Play all event sounds to hear each one |
+| `pingthings theme [name]` | Apply a sound theme |
 | `pingthings config [key] [val]` | Show or update configuration |
-| `pingthings install <pack>` | Install a sound pack (coming soon) |
+| `pingthings init` | Set up Claude Code hooks automatically |
+| `pingthings create <dir>` | Create a pack from audio files |
+| `pingthings install <source>` | Install a pack from GitHub or local path |
 
 ## Configuration
 
@@ -139,13 +144,17 @@ Config lives at `~/.config/pingthings/config.json`:
 {
   "activePack": "7kaa-soldiers",
   "mode": "random",
-  "specificSound": null
+  "specificSound": null,
+  "volume": 100,
+  "eventPacks": {}
 }
 ```
 
 - **activePack** — which sound pack to use
 - **mode** — `"random"` (default), `"specific"`, or `"informational"`
 - **specificSound** — sound name to always play when mode is `"specific"`
+- **volume** — playback volume, 0-100 (default: 100)
+- **eventPacks** — per-event pack overrides (e.g. `{"error": "freedoom-arsenal"}`)
 
 Set values via CLI:
 
@@ -252,11 +261,87 @@ To support informational mode, add an `events` field mapping event types to soun
 }
 ```
 
+## Themes
+
+Apply a pre-built theme that maps events to packs with one command:
+
+```bash
+pingthings theme              # list available themes
+pingthings theme sci-fi       # apply a theme
+pingthings theme reset        # back to defaults
+```
+
+| Theme | Description |
+|-------|-------------|
+| `retro` | Classic retro gaming — Freedoom weapons + 7kaa soldiers |
+| `sci-fi` | Sci-fi command center — Warzone 2100 commander voice |
+| `arena` | Arena announcer with FPS weapons for errors |
+| `fantasy` | Medieval fantasy — Wesnoth + 0 A.D. civilizations |
+| `ancient` | Ancient world — 7kaa soldiers + 0 A.D. voices |
+| `chaos` | Different pack for every event — maximum variety |
+
+## Tools
+
+### Create a pack
+```bash
+pingthings create ./my-sounds my-pack
+```
+Scaffolds a new pack from a folder of audio files with an auto-generated manifest.
+
+### Install from GitHub
+```bash
+pingthings install user/repo
+pingthings install https://github.com/user/pack-name
+```
+
+### Auto-setup Claude Code hooks
+```bash
+pingthings init                  # interactive wizard
+pingthings init --basic          # random sounds, no prompts
+pingthings init --informational  # event-based sounds, no prompts
+```
+
+## Use with other tools
+
+pingthings works anywhere you can run a shell command.
+
+### Git hooks
+```bash
+# .git/hooks/post-commit
+#!/bin/sh
+pingthings play --event done
+```
+
+### CI notifications (GitHub Actions)
+```yaml
+- name: Notify on failure
+  if: failure()
+  run: npx pingthings play --event error
+```
+
+### Shell aliases
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+alias done='pingthings play --event complete'
+alias oops='pingthings play --event error'
+```
+
+### Pomodoro timer
+```bash
+sleep 1500 && pingthings play --event complete  # 25 minute focus
+```
+
 ## Requirements
 
 - Node.js >= 18
-- macOS (`afplay`) or Linux (`paplay` / `aplay`)
+- macOS (`afplay`), Linux (`paplay` / `aplay`), or Windows (PowerShell)
 
 ## License
 
-GPL v2 — includes audio from [Seven Kingdoms: Ancient Adversaries](https://github.com/the3dfxdude/7kaa) (GPL v2).
+GPL v2 — includes audio from open source games:
+- [Seven Kingdoms: Ancient Adversaries](https://github.com/the3dfxdude/7kaa) (GPL v2)
+- [Battle for Wesnoth](https://github.com/wesnoth/wesnoth) (GPL v2+)
+- [OpenArena](http://openarena.ws) (GPL v2)
+- [Freedoom](https://github.com/freedoom/freedoom) (BSD-3-Clause)
+- [Warzone 2100](https://github.com/Warzone2100/warzone2100) (GPL v2)
+- [0 A.D.](https://github.com/0ad/0ad) (CC-BY-SA 3.0)

package/bin/pingthings.js

@@ -14,9 +14,14 @@ const commands = {
   play: () => import('../src/cli/play.js'),
   list: () => import('../src/cli/list.js'),
   use: () => import('../src/cli/use.js'),
+  select: () => import('../src/cli/select.js'),
   preview: () => import('../src/cli/preview.js'),
   config: () => import('../src/cli/config.js'),
   install: () => import('../src/cli/install.js'),
+  init: () => import('../src/cli/init.js'),
+  create: () => import('../src/cli/create.js'),
+  theme: () => import('../src/cli/theme.js'),
+  'test-events': () => import('../src/cli/test-events.js'),
 };
 
 function showHelp() {
@@ -28,10 +33,15 @@ Usage: pingthings <command> [options]
 Commands:
   play [sound]       Play a sound from the active pack (random by default)
   list               Show available sound packs
+  select             Interactive pack selector
   use <pack>         Set the active sound pack
   preview <pack>     Preview a random sound from a pack
+  test-events [pack] Play all event sounds to hear what each one sounds like
+  theme [name]       Apply a sound theme (maps events across packs)
   config [key] [val] Show or update configuration
-  install <pack>     Install a sound pack (coming soon)
+  init               Set up Claude Code hooks automatically
+  create <dir>       Create a new pack from a folder of audio files
+  install <source>   Install a pack from GitHub or URL
 
 Options:
   --help, -h         Show this help message
@@ -47,9 +57,11 @@ Examples:
   pingthings play 00083-READY     Play a specific sound
   pingthings play --event done    Play a "task done" sound
   pingthings play -e error        Play an "error" sound
-  pingthings list                  List all available packs
-  pingthings use 7kaa-soldiers    Switch to a pack
-  pingthings config mode informational   Enable event-based sounds
+  pingthings select               Choose a pack interactively
+  pingthings test-events           Hear all event sounds
+  pingthings theme retro           Apply the retro theme
+  pingthings init                  Set up Claude Code hooks
+  pingthings config volume 50     Set volume to 50%
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pingthings",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Notification sounds for Claude Code and other CLI tools",
   "type": "module",
   "license": "GPL-2.0",

package/src/cli/config.js

@@ -1,8 +1,39 @@
-import { readConfig, writeConfig, VALID_MODES } from '../config.js';
+import { readConfig, writeConfig, VALID_MODES, VALID_EVENTS } from '../config.js';
 
-const VALID_KEYS = ['activePack', 'mode', 'specificSound'];
+const VALID_KEYS = ['activePack', 'mode', 'specificSound', 'volume', 'eventPacks'];
+
+function showHelp() {
+  console.log(`
+Usage: pingthings config [key] [value]
+
+Show or update configuration.
+
+With no arguments, shows the full config.
+With one argument, shows that key's value.
+With two arguments, sets the key to the value.
+
+Keys:
+  activePack      Which sound pack to use
+  mode            random, specific, or informational
+  specificSound   Sound name for specific mode
+  volume          Playback volume (0-100)
+  eventPacks      Per-event pack overrides (use "pingthings config eventPacks.<event> <pack>")
+
+Examples:
+  pingthings config                          Show full config
+  pingthings config volume                   Show current volume
+  pingthings config volume 50               Set volume to 50%
+  pingthings config mode informational      Enable event-based sounds
+  pingthings config eventPacks.error openarena-announcer
+`);
+}
 
 export default function config(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
   const [key, ...rest] = args;
   const value = rest.join(' ') || undefined;
 
@@ -13,6 +44,31 @@ export default function config(args) {
     return;
   }
 
+  // Handle eventPacks.event syntax
+  if (key.startsWith('eventPacks.')) {
+    const event = key.split('.')[1];
+    if (!VALID_EVENTS.includes(event)) {
+      console.error(`Unknown event: ${event}`);
+      console.error(`Valid events: ${VALID_EVENTS.join(', ')}`);
+      process.exit(1);
+    }
+    if (value === undefined) {
+      const cfg = readConfig();
+      console.log(cfg.eventPacks?.[event] ?? '(not set — uses active pack)');
+      return;
+    }
+    const cfg = readConfig();
+    if (!cfg.eventPacks) cfg.eventPacks = {};
+    if (value === 'null' || value === 'reset') {
+      delete cfg.eventPacks[event];
+    } else {
+      cfg.eventPacks[event] = value;
+    }
+    writeConfig(cfg);
+    console.log(`${event} pack set to: ${value === 'null' || value === 'reset' ? '(active pack)' : value}`);
+    return;
+  }
+
   // Validate key
   if (!VALID_KEYS.includes(key)) {
     console.error(`Unknown config key: ${key}`);
@@ -23,7 +79,12 @@ export default function config(args) {
   // One arg: show value
   if (value === undefined) {
     const cfg = readConfig();
-    console.log(cfg[key] ?? '(not set)');
+    const val = cfg[key];
+    if (typeof val === 'object' && val !== null) {
+      console.log(JSON.stringify(val, null, 2));
+    } else {
+      console.log(val ?? '(not set)');
+    }
     return;
   }
 
@@ -34,6 +95,20 @@ export default function config(args) {
     process.exit(1);
   }
 
+  // Validate volume
+  if (key === 'volume') {
+    const vol = parseInt(value, 10);
+    if (isNaN(vol) || vol < 0 || vol > 100) {
+      console.error('Volume must be a number between 0 and 100.');
+      process.exit(1);
+    }
+    const cfg = readConfig();
+    cfg.volume = vol;
+    writeConfig(cfg);
+    console.log(`volume set to: ${vol}`);
+    return;
+  }
+
   // Two args: set value
   const cfg = readConfig();
   cfg[key] = value === 'null' ? null : value;

package/src/cli/create.js

@@ -0,0 +1,109 @@
+import { existsSync, readdirSync, mkdirSync, copyFileSync, writeFileSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { getConfigDir } from '../config.js';
+
+const AUDIO_EXTENSIONS = new Set(['.wav', '.mp3', '.ogg', '.flac']);
+
+function showHelp() {
+  console.log(`
+Usage: pingthings create <source-dir> [pack-name]
+
+Create a new sound pack from a folder of audio files.
+
+Arguments:
+  source-dir    Directory containing audio files (.wav, .mp3, .ogg, .flac)
+  pack-name     Name for the pack (defaults to directory name)
+
+The pack will be installed to ~/.config/pingthings/packs/<pack-name>/
+with an auto-generated manifest.json.
+
+Examples:
+  pingthings create ./my-sounds
+  pingthings create ./my-sounds custom-pack
+`);
+}
+
+export default async function create(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const sourceDir = args[0];
+  if (!sourceDir) {
+    showHelp();
+    process.exit(1);
+  }
+
+  if (!existsSync(sourceDir)) {
+    console.error(`Directory not found: ${sourceDir}`);
+    process.exit(1);
+  }
+
+  // Find audio files
+  const audioFiles = readdirSync(sourceDir)
+    .filter(f => AUDIO_EXTENSIONS.has(extname(f).toLowerCase()))
+    .sort();
+
+  if (audioFiles.length === 0) {
+    console.error(`No audio files found in ${sourceDir}`);
+    console.error('Supported formats: .wav, .mp3, .ogg, .flac');
+    process.exit(1);
+  }
+
+  const packName = args[1] || basename(sourceDir);
+  const packsDir = join(getConfigDir(), 'packs');
+  const packDir = join(packsDir, packName);
+  const soundsDir = join(packDir, 'sounds');
+
+  if (existsSync(packDir)) {
+    console.error(`Pack already exists: ${packDir}`);
+    console.error('Delete it first or choose a different name.');
+    process.exit(1);
+  }
+
+  // Create pack directory structure
+  mkdirSync(soundsDir, { recursive: true });
+
+  // Copy audio files
+  console.log(`\nCreating pack "${packName}" with ${audioFiles.length} sounds...\n`);
+
+  const soundPaths = [];
+  for (const file of audioFiles) {
+    const dest = join(soundsDir, file);
+    copyFileSync(join(sourceDir, file), dest);
+    soundPaths.push(`sounds/${file}`);
+    console.log(`  + ${file}`);
+  }
+
+  // Generate manifest
+  const manifest = {
+    name: packName,
+    description: '',
+    version: '1.0.0',
+    license: '',
+    credits: '',
+    sounds: soundPaths,
+    events: {
+      done: [],
+      permission: [],
+      complete: [],
+      error: [],
+      blocked: [],
+    },
+  };
+
+  writeFileSync(
+    join(packDir, 'manifest.json'),
+    JSON.stringify(manifest, null, 2) + '\n',
+    'utf8'
+  );
+
+  console.log(`\nPack created at: ${packDir}`);
+  console.log(`Manifest: ${join(packDir, 'manifest.json')}`);
+  console.log('\nNext steps:');
+  console.log('  1. Edit manifest.json to add description, license, and credits');
+  console.log('  2. Map sounds to events in the "events" field');
+  console.log(`  3. Run: pingthings use ${packName}`);
+}

package/src/cli/init.js

@@ -0,0 +1,125 @@
+import { createInterface } from 'node:readline';
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings init
+
+Interactive setup wizard that configures Claude Code hooks
+in ~/.claude/settings.json automatically.
+
+Options:
+  --basic          Set up basic random sounds (no prompts)
+  --informational  Set up event-based sounds (no prompts)
+  --help, -h       Show this help message
+`);
+}
+
+const BASIC_HOOKS = {
+  Notification: [{
+    matcher: '',
+    hooks: [{ type: 'command', command: 'pingthings play' }],
+  }],
+};
+
+const INFORMATIONAL_HOOKS = {
+  Notification: [{
+    matcher: '',
+    hooks: [{ type: 'command', command: 'pingthings play --event permission' }],
+  }],
+  Stop: [{
+    matcher: '',
+    hooks: [{ type: 'command', command: 'pingthings play --event complete' }],
+  }],
+  PostToolUseFailure: [{
+    matcher: '',
+    hooks: [{ type: 'command', command: 'pingthings play --event error' }],
+  }],
+  StopFailure: [{
+    matcher: '',
+    hooks: [{ type: 'command', command: 'pingthings play --event blocked' }],
+  }],
+};
+
+function getSettingsPath() {
+  return join(homedir(), '.claude', 'settings.json');
+}
+
+function readSettings() {
+  const path = getSettingsPath();
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(settings) {
+  const path = getSettingsPath();
+  const tmpPath = path + '.tmp';
+  writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  renameSync(tmpPath, path);
+}
+
+function applyHooks(mode) {
+  const settings = readSettings();
+  const hooks = mode === 'informational' ? INFORMATIONAL_HOOKS : BASIC_HOOKS;
+  settings.hooks = { ...settings.hooks, ...hooks };
+  writeSettings(settings);
+
+  console.log(`\nClaude Code hooks configured (${mode} mode).`);
+  console.log(`Settings written to: ${getSettingsPath()}`);
+
+  if (mode === 'informational') {
+    console.log('\nHook mapping:');
+    console.log('  Notification     → permission sound');
+    console.log('  Stop             → complete sound');
+    console.log('  PostToolUseFailure → error sound');
+    console.log('  StopFailure      → blocked sound');
+  } else {
+    console.log('\nA random sound will play on every Claude Code notification.');
+  }
+
+  console.log('\nRestart Claude Code for hooks to take effect.');
+}
+
+export default async function init(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  if (args.includes('--basic')) {
+    applyHooks('basic');
+    return;
+  }
+
+  if (args.includes('--informational')) {
+    applyHooks('informational');
+    return;
+  }
+
+  console.log('\npingthings — Claude Code hook setup\n');
+  console.log('How would you like sounds to work?\n');
+  console.log('  1. Basic — random sound on every notification');
+  console.log('  2. Informational — different sounds for different events');
+  console.log('     (done, permission, error, blocked)\n');
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  rl.question('Choose (1 or 2): ', (answer) => {
+    const choice = answer.trim();
+    if (choice === '2') {
+      applyHooks('informational');
+    } else {
+      applyHooks('basic');
+    }
+    rl.close();
+  });
+}

package/src/cli/install.js

@@ -1,8 +1,121 @@
-export default function install() {
-  console.log('Remote pack installation is coming in a future version.');
-  console.log('');
-  console.log('For now, you can manually install packs by placing them in:');
-  console.log('  ~/.config/pingthings/packs/<pack-name>/');
-  console.log('');
-  console.log('Each pack needs a manifest.json and a sounds/ directory.');
+import { existsSync, mkdirSync, cpSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { getConfigDir } from '../config.js';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings install <source>
+
+Install a sound pack from a GitHub repository or local path.
+
+Arguments:
+  source    GitHub URL, GitHub shorthand (user/repo), or local path
+
+The pack will be installed to ~/.config/pingthings/packs/
+
+Examples:
+  pingthings install user/repo
+  pingthings install https://github.com/user/pingthings-pack-name
+  pingthings install ./path/to/local/pack
+`);
+}
+
+function installFromGit(source) {
+  const packsDir = join(getConfigDir(), 'packs');
+  mkdirSync(packsDir, { recursive: true });
+
+  // Convert shorthand to full URL
+  let url = source;
+  if (!source.startsWith('http') && !source.startsWith('git@') && source.includes('/')) {
+    url = `https://github.com/${source}.git`;
+  }
+
+  const repoName = basename(url, '.git');
+  const destDir = join(packsDir, repoName);
+
+  if (existsSync(destDir)) {
+    console.error(`Pack already exists: ${repoName}`);
+    console.error(`Delete ${destDir} first to reinstall.`);
+    process.exit(1);
+  }
+
+  console.log(`Cloning ${url}...`);
+
+  try {
+    execFileSync('git', ['clone', '--depth', '1', url, destDir], {
+      stdio: 'inherit',
+    });
+  } catch {
+    console.error('Failed to clone repository. Check the URL and try again.');
+    process.exit(1);
+  }
+
+  // Check for manifest
+  if (!existsSync(join(destDir, 'manifest.json'))) {
+    console.log('\nNote: No manifest.json found. The pack may need one to work properly.');
+    console.log('Run "pingthings create" to generate a manifest from audio files.');
+  }
+
+  console.log(`\nInstalled: ${repoName}`);
+  console.log(`Location: ${destDir}`);
+  console.log(`\nTo use: pingthings use ${repoName}`);
+}
+
+function installFromLocal(source) {
+  if (!existsSync(source)) {
+    console.error(`Path not found: ${source}`);
+    process.exit(1);
+  }
+
+  if (!existsSync(join(source, 'manifest.json'))) {
+    console.error('No manifest.json found in the source directory.');
+    console.error('Run "pingthings create <dir>" to create a pack from audio files.');
+    process.exit(1);
+  }
+
+  const packName = basename(source);
+  if (!packName) {
+    console.error('Could not determine pack name from path.');
+    process.exit(1);
+  }
+  const packsDir = join(getConfigDir(), 'packs');
+  const destDir = join(packsDir, packName);
+
+  if (existsSync(destDir)) {
+    console.error(`Pack already exists: ${packName}`);
+    console.error(`Delete ${destDir} first to reinstall.`);
+    process.exit(1);
+  }
+
+  mkdirSync(packsDir, { recursive: true });
+
+  try {
+    cpSync(source, destDir, { recursive: true });
+  } catch {
+    console.error('Failed to copy pack.');
+    process.exit(1);
+  }
+
+  console.log(`Installed: ${packName}`);
+  console.log(`Location: ${destDir}`);
+  console.log(`\nTo use: pingthings use ${packName}`);
+}
+
+export default function install(args) {
+  const source = args[0];
+
+  if (!source || source === '--help' || source === '-h') {
+    showHelp();
+    if (!source) process.exit(1);
+    return;
+  }
+
+  // Determine if it's a git URL, shorthand, or local path
+  if (source.startsWith('http') || source.startsWith('git@') ||
+      (source.includes('/') && !source.startsWith('.') && !source.startsWith('/'))) {
+    installFromGit(source);
+  } else {
+    installFromLocal(source);
+  }
 }

package/src/cli/list.js

@@ -1,7 +1,21 @@
 import { readConfig } from '../config.js';
 import { listPacks } from '../packs.js';
 
-export default function list() {
+function showHelp() {
+  console.log(`
+Usage: pingthings list
+
+Show all available sound packs with their sound count and source.
+The active pack is marked with *.
+`);
+}
+
+export default function list(args) {
+  if (args?.includes('--help') || args?.includes('-h')) {
+    showHelp();
+    return;
+  }
+
   const config = readConfig();
   const packs = listPacks();
 

package/src/cli/play.js

@@ -78,10 +78,15 @@ export default function play(args) {
 
   // If --event flag is provided, use event mapping
   if (parsed.event) {
-    const eventSounds = getEventSounds(packName, parsed.event);
+    // Pack mixing: check if there's a per-event pack override
+    const eventPackName = config.eventPacks?.[parsed.event] || packName;
+    const eventPack = resolvePack(eventPackName);
+    const resolvedPack = eventPack ? eventPackName : packName;
+
+    const eventSounds = getEventSounds(resolvedPack, parsed.event);
     if (eventSounds.length === 0) {
       // Fall back to random if pack has no mapping for this event
-      const allSounds = getPackSounds(packName);
+      const allSounds = getPackSounds(resolvedPack);
       soundFile = pickRandom(allSounds);
     } else {
       soundFile = pickRandom(eventSounds);
@@ -123,5 +128,10 @@ export default function play(args) {
     soundFile = pickRandom(sounds);
   }
 
-  playSound(soundFile);
+  if (!soundFile) {
+    console.error(`No sounds available in pack: ${packName}`);
+    process.exit(1);
+  }
+
+  playSound(soundFile, config.volume);
 }

package/src/cli/preview.js

@@ -1,14 +1,26 @@
+import { readConfig } from '../config.js';
 import { getPackSounds, pickRandom, resolvePack } from '../packs.js';
 import { playSound } from '../player.js';
 import { basename } from 'node:path';
 
+function showHelp() {
+  console.log(`
+Usage: pingthings preview <pack>
+
+Play a random sound from a pack to hear what it sounds like.
+
+Arguments:
+  pack    Name of the pack to preview
+`);
+}
+
 export default function preview(args) {
   const packName = args[0];
 
-  if (!packName) {
-    console.error('Usage: pingthings preview <pack>');
-    console.error('Run "pingthings list" to see available packs.');
-    process.exit(1);
+  if (!packName || packName === '--help' || packName === '-h') {
+    showHelp();
+    if (!packName) process.exit(1);
+    return;
   }
 
   const pack = resolvePack(packName);
@@ -24,7 +36,8 @@ export default function preview(args) {
     process.exit(1);
   }
 
+  const config = readConfig();
   const sound = pickRandom(sounds);
   console.log(`Playing: ${basename(sound)} from "${packName}"`);
-  playSound(sound);
+  playSound(sound, config.volume);
 }

package/src/cli/select.js

@@ -0,0 +1,81 @@
+import { createInterface } from 'node:readline';
+import { readConfig, writeConfig } from '../config.js';
+import { listPacks, getPackSounds } from '../packs.js';
+import { playSound } from '../player.js';
+import { basename } from 'node:path';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings select
+
+Interactive menu for choosing your active sound pack.
+Displays a numbered list — type a number to preview and select.
+`);
+}
+
+export default async function select(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const config = readConfig();
+  const packs = listPacks();
+
+  if (packs.length === 0) {
+    console.error('No sound packs found.');
+    process.exit(1);
+  }
+
+  console.log('\nChoose a sound pack:\n');
+
+  for (let i = 0; i < packs.length; i++) {
+    const active = packs[i].name === config.activePack ? ' *' : '  ';
+    console.log(`${active} ${i + 1}. ${packs[i].name}  (${packs[i].soundCount} sounds)`);
+    if (packs[i].description) {
+      console.log(`      ${packs[i].description}`);
+    }
+  }
+
+  console.log('\n  * = current pack');
+  console.log('  Enter a number to preview & select, or q to quit.\n');
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const ask = () => {
+    rl.question('> ', (answer) => {
+      const trimmed = answer.trim().toLowerCase();
+
+      if (trimmed === 'q' || trimmed === 'quit' || trimmed === '') {
+        rl.close();
+        return;
+      }
+
+      const num = parseInt(trimmed, 10);
+      if (isNaN(num) || num < 1 || num > packs.length) {
+        console.log(`Enter 1-${packs.length} or q to quit.`);
+        ask();
+        return;
+      }
+
+      const chosen = packs[num - 1];
+      config.activePack = chosen.name;
+      writeConfig(config);
+
+      // Preview a sound from the chosen pack
+      const sounds = getPackSounds(chosen.name);
+      if (sounds.length > 0) {
+        const sample = sounds[Math.floor(Math.random() * sounds.length)];
+        playSound(sample, config.volume);
+      }
+
+      console.log(`\nActive pack set to: ${chosen.name}`);
+      rl.close();
+    });
+  };
+
+  ask();
+}

package/src/cli/test-events.js

@@ -0,0 +1,51 @@
+import { readConfig, VALID_EVENTS } from '../config.js';
+import { getEventSounds, getPackSounds, pickRandom, resolvePack } from '../packs.js';
+import { playSoundSync } from '../player.js';
+import { basename } from 'node:path';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings test-events [pack]
+
+Play one sound for each event type from a pack so you can hear
+what each event sounds like. Defaults to the active pack.
+
+Arguments:
+  pack    Pack to test (optional, defaults to active pack)
+
+Events played: done, permission, complete, error, blocked
+`);
+}
+
+export default async function testEvents(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const config = readConfig();
+  const packName = args[0] || config.activePack;
+  const pack = resolvePack(packName);
+
+  if (!pack) {
+    console.error(`Pack not found: ${packName}`);
+    console.error('Run "pingthings list" to see available packs.');
+    process.exit(1);
+  }
+
+  console.log(`\nTesting events for: ${packName}\n`);
+
+  for (const event of VALID_EVENTS) {
+    const sounds = getEventSounds(packName, event);
+    if (sounds.length === 0) {
+      console.log(`  ${event.padEnd(12)} (no sounds mapped)`);
+      continue;
+    }
+
+    const sound = pickRandom(sounds);
+    console.log(`  ${event.padEnd(12)} ${basename(sound)}`);
+    playSoundSync(sound, config.volume);
+  }
+
+  console.log('\nDone.\n');
+}

package/src/cli/theme.js

@@ -0,0 +1,132 @@
+import { readConfig, writeConfig } from '../config.js';
+import { resolvePack } from '../packs.js';
+
+const THEMES = {
+  'retro': {
+    description: 'Classic retro gaming — Freedoom weapons and 7kaa soldiers',
+    activePack: '7kaa-soldiers',
+    eventPacks: {
+      done: '7kaa-soldiers',
+      permission: '7kaa-soldiers',
+      complete: 'freedoom-arsenal',
+      error: 'freedoom-arsenal',
+      blocked: 'freedoom-arsenal',
+    },
+  },
+  'sci-fi': {
+    description: 'Sci-fi command center — Warzone 2100 commander voice',
+    activePack: 'warzone2100-command',
+    eventPacks: {
+      done: 'warzone2100-command',
+      permission: 'warzone2100-command',
+      complete: 'warzone2100-command',
+      error: 'warzone2100-command',
+      blocked: 'warzone2100-command',
+    },
+  },
+  'arena': {
+    description: 'Arena announcer with FPS weapons for errors',
+    activePack: 'openarena-announcer',
+    eventPacks: {
+      done: 'openarena-announcer',
+      permission: 'openarena-announcer',
+      complete: 'openarena-announcer',
+      error: 'freedoom-arsenal',
+      blocked: 'freedoom-arsenal',
+    },
+  },
+  'fantasy': {
+    description: 'Medieval fantasy — Wesnoth combat and 0 A.D. civilizations',
+    activePack: 'wesnoth-combat',
+    eventPacks: {
+      done: 'wesnoth-combat',
+      permission: '0ad-civilizations',
+      complete: 'wesnoth-combat',
+      error: 'wesnoth-combat',
+      blocked: '0ad-civilizations',
+    },
+  },
+  'ancient': {
+    description: 'Ancient world — 7kaa soldiers and 0 A.D. civilizations',
+    activePack: '7kaa-soldiers',
+    eventPacks: {
+      done: '7kaa-soldiers',
+      permission: '0ad-civilizations',
+      complete: '0ad-civilizations',
+      error: '7kaa-soldiers',
+      blocked: '0ad-civilizations',
+    },
+  },
+  'chaos': {
+    description: 'Random pack for every event — maximum variety',
+    activePack: '7kaa-soldiers',
+    eventPacks: {
+      done: '7kaa-soldiers',
+      permission: 'openarena-announcer',
+      complete: 'warzone2100-command',
+      error: 'freedoom-arsenal',
+      blocked: 'wesnoth-combat',
+    },
+  },
+};
+
+function showHelp() {
+  console.log(`
+Usage: pingthings theme [name]
+
+Apply a sound theme that maps events to packs.
+
+With no arguments, lists available themes.
+
+Available themes:`);
+
+  for (const [name, theme] of Object.entries(THEMES)) {
+    console.log(`  ${name.padEnd(12)} ${theme.description}`);
+  }
+
+  console.log(`
+Examples:
+  pingthings theme             List themes
+  pingthings theme sci-fi      Apply the sci-fi theme
+  pingthings theme reset       Reset to defaults
+`);
+}
+
+export default function theme(args) {
+  const name = args[0];
+
+  if (!name || name === '--help' || name === '-h') {
+    showHelp();
+    return;
+  }
+
+  if (name === 'reset') {
+    const config = readConfig();
+    config.eventPacks = {};
+    config.mode = 'random';
+    writeConfig(config);
+    console.log('Theme reset. Using default random mode.');
+    return;
+  }
+
+  const selected = THEMES[name];
+  if (!selected) {
+    console.error(`Unknown theme: ${name}`);
+    console.error(`Available themes: ${Object.keys(THEMES).join(', ')}`);
+    process.exit(1);
+  }
+
+  const config = readConfig();
+  config.activePack = selected.activePack;
+  config.mode = 'informational';
+  config.eventPacks = { ...selected.eventPacks };
+  writeConfig(config);
+
+  console.log(`\nTheme applied: ${name}`);
+  console.log(`${selected.description}\n`);
+  console.log('Event mapping:');
+  for (const [event, pack] of Object.entries(selected.eventPacks)) {
+    console.log(`  ${event.padEnd(12)} → ${pack}`);
+  }
+  console.log(`\nMode set to: informational`);
+}

package/src/cli/use.js

@@ -1,13 +1,27 @@
 import { readConfig, writeConfig } from '../config.js';
 import { resolvePack } from '../packs.js';
 
+function showHelp() {
+  console.log(`
+Usage: pingthings use <pack>
+
+Set the active sound pack.
+
+Arguments:
+  pack    Name of the pack to activate
+
+Run "pingthings list" to see available packs.
+Run "pingthings select" for an interactive picker.
+`);
+}
+
 export default function use(args) {
   const packName = args[0];
 
-  if (!packName) {
-    console.error('Usage: pingthings use <pack>');
-    console.error('Run "pingthings list" to see available packs.');
-    process.exit(1);
+  if (!packName || packName === '--help' || packName === '-h') {
+    showHelp();
+    if (!packName) process.exit(1);
+    return;
   }
 
   const pack = resolvePack(packName);

package/src/config.js

@@ -6,6 +6,8 @@ const DEFAULTS = {
   activePack: '7kaa-soldiers',
   mode: 'random',
   specificSound: null,
+  volume: 100,
+  eventPacks: {},
 };
 
 export function getConfigDir() {

package/src/packs.js

@@ -48,6 +48,7 @@ function scanDirectory(dir, isBuiltIn) {
 
       return {
         name: manifest?.name || d.name,
+        version: manifest?.version || '0.0.0',
         description: manifest?.description || '',
         license: manifest?.license || 'Unknown',
         credits: manifest?.credits || '',

package/src/player.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { platform } from 'node:os';
 
@@ -7,33 +7,82 @@ function getPlayerCommand() {
     case 'darwin':
       return 'afplay';
     case 'linux': {
-      // Prefer PulseAudio/PipeWire, fall back to ALSA
       try {
-        const result = spawn('which', ['paplay'], { stdio: 'pipe' });
+        execFileSync('which', ['paplay'], { stdio: 'pipe' });
         return 'paplay';
       } catch {
         return 'aplay';
       }
     }
+    case 'win32':
+      return 'powershell';
     default:
       return null;
   }
 }
 
-export function playSound(filePath) {
+function buildArgs(cmd, filePath, volume) {
+  const vol = Math.max(0, Math.min(100, volume ?? 100));
+
+  switch (cmd) {
+    case 'afplay': {
+      // afplay volume: 0.0 to 1.0
+      const afplayVol = (vol / 100).toFixed(2);
+      return ['-v', afplayVol, filePath];
+    }
+    case 'paplay': {
+      // paplay volume: 0 to 65536 (100% = 65536)
+      const paplayVol = Math.round((vol / 100) * 65536).toString();
+      return ['--volume', paplayVol, filePath];
+    }
+    case 'aplay':
+      // aplay doesn't support volume natively
+      return [filePath];
+    case 'powershell': {
+      // PowerShell SoundPlayer doesn't support volume, but it plays the file
+      const script = `(New-Object System.Media.SoundPlayer '${filePath.replace(/'/g, "''")}').PlaySync()`;
+      return ['-NoProfile', '-Command', script];
+    }
+    default:
+      return [filePath];
+  }
+}
+
+export function playSound(filePath, volume) {
   if (!existsSync(filePath)) {
     throw new Error(`Sound file not found: ${filePath}`);
   }
 
   const cmd = getPlayerCommand();
   if (!cmd) {
-    throw new Error(`Unsupported platform: ${platform()}. Supported: macOS, Linux.`);
+    throw new Error(`Unsupported platform: ${platform()}. Supported: macOS, Linux, Windows.`);
   }
 
-  const child = spawn(cmd, [filePath], {
+  const args = buildArgs(cmd, filePath, volume);
+
+  const child = spawn(cmd, args, {
     detached: true,
     stdio: 'ignore',
   });
 
   child.unref();
 }
+
+export function playSoundSync(filePath, volume) {
+  if (!existsSync(filePath)) {
+    throw new Error(`Sound file not found: ${filePath}`);
+  }
+
+  const cmd = getPlayerCommand();
+  if (!cmd) {
+    throw new Error(`Unsupported platform: ${platform()}. Supported: macOS, Linux, Windows.`);
+  }
+
+  const args = buildArgs(cmd, filePath, volume);
+
+  try {
+    execFileSync(cmd, args, { stdio: 'ignore', timeout: 10000 });
+  } catch {
+    // Timeout or error — don't crash
+  }
+}