OpenCode My Custom Audio

Custom audio notifications plugin for OpenCode 2 using my kids' voice recordings.

Requires OpenCode 2.x (opencode2). The V1 implementation was removed in v1.2.0; use v1.1.x with OpenCode 1.x.

Features

• Plays custom voice recordings when OpenCode events occur
• Supports idle, cancelled, error, and tool completion sounds
• Custom sounds directory support for adding your own sounds
• Weighted random selection between default and custom sounds

Events Handled (V2 mapping)

| V2 source | Sound | | --------- | ----- | | session.idle event | Work complete | | session.status event with idle status | Work complete | | session.execution.succeeded event | Work complete | | session.deleted / session.execution.interrupted / session.inbox.cancelled / session.interrupt events | Session cancelled | | session.execution.failed / session.error events, or tool.execute.after hook with status: "error" | Error | | tool.execute.after hook, status: "completed" | Tool execution completed |

Installation

opencode2 plugin add @jinana/opencode-my-custom-audio

Or build from source:

git clone https://github.com/dominikake/opencode-my-custom-audio.git
cd opencode-my-custom-audio
npm install
npm run build

OpenCode Configuration

Add the plugin to your OpenCode 2 config (~/.config/opencode/opencode.json, note the V2 plugins key):

{
  "plugins": [
    {
      "package": "@jinana/opencode-my-custom-audio",
      "options": {
        "soundsDir": "~/.config/opencode/my-custom-audio/sounds",
        "volume": 0.3,
        "enabled": true,
        "voiceWeights": {
          "default": 50,
          "custom": 50
        }
      }
    }
  ]
}

Or reference a local checkout:

{
  "plugins": [
    {
      "package": "/path/to/opencode-my-custom-audio",
      "options": {
        "volume": 0.3
      }
    }
  ]
}

Configuration Options

| Option | Type | Default | Description | | ---------------------- | ------- | ------------------------------------------- | ------------------------------------- | | soundsDir | string | ~/.config/opencode/my-custom-audio/sounds | Custom sounds directory | | volume | number | 0.3 | Volume level (0.0 - 1.0, clamped; subtle by default) | | enabled | boolean | true | Enable/disable the plugin | | showToast | boolean | true | Accepted for V1 config compatibility; ignored in V2 (server plugins have no toast API) | | idleSound | string | - | Custom sound file for idle event | | cancelledSound | string | - | Custom sound file for cancelled event | | errorSound | string | - | Custom sound file for error event | | toolSound | string | - | Custom sound file for tool event | | cancelDedupeMs | number | 1500 | Suppress duplicate cancelled sounds within this window. Also suppresses follow-up idle/error sounds after a cancellation (0 disables) | | errorDedupeMs | number | 1500 | Suppress duplicate error sounds within this window (0 disables) | | idleDedupeMs | number | 3000 | Suppress duplicate idle sounds within this window (0 disables) | | toolDedupeMs | number | 500 | Suppress duplicate tool sounds within this window (0 disables) | | voiceWeights.default | number | 50 | Weight for default sounds (%) | | voiceWeights.custom | number | 50 | Weight for custom sounds (%) |

Custom Sounds

To add custom sounds, create a directory structure in your sounds directory:

~/.config/opencode/my-custom-audio/sounds/
├── idle/
│   └── your_idle_sound.wav
├── cancelled/
│   └── your_cancelled_sound.wav
├── error/
│   └── your_error_sound.wav
└── tool/
    └── your_tool_sound.wav

Supported formats: WAV, MP3, OGG

Default Sounds

The plugin comes bundled with these default sounds:

• Idle: Work complete voice
• Cancelled: Change my mind sound
• Error: Laugh sound
• Tool: Tools call / Orc sound

Requirements

• OpenCode 2.x
• Linux with PulseAudio (paplay) for sound playback
• or macOS (afplay)
• or Windows (not yet implemented)

Development

# Install dependencies
npm install

# Build
npm run build

# Lint
npm run lint

Debugging

Set DEBUG=opencode:audio in your environment to print structured logs about plugin initialization, deduplication decisions, and which sound files are played:

DEBUG=opencode:audio opencode2

Deduplication state is kept in memory and persisted to plugin-scoped storage (ctx.storage), so duplicate sounds stay suppressed across reloads.

License

MIT