CESP v1.0

Overview

CESP defines a universal format for sound packs that respond to coding events in agentic IDEs. A single pack works across Claude Code, Cursor, Codex, and any tool that implements the specification.

The spec covers three things: a set of event categories that IDEs emit, a manifest format (openpeon.json) that maps categories to audio files, and player behavior requirements for how sounds should be played.

Key words: MUST, SHOULD, and MAY are used per RFC 2119.

Event Categories

CESP defines 9 event categories. Players MUST support the 6 core categories. Extended categories are optional.

Core Categories

Extended Categories

Manifest Format

Every pack MUST include an openpeon.json file at its root.

Required Fields

Recommended Fields

Sound Entry

Each sound in a category has file (relative path), label (human description), and optional sha256 (hex digest, required for registry).

Example

{
  "cesp_version": "1.0",
  "name": "my-pack",
  "display_name": "My Sound Pack",
  "version": "1.0.0",
  "description": "A custom sound pack for my IDE",
  "author": {
    "name": "yourname",
    "github": "yourname"
  },
  "license": "CC-BY-NC-4.0",
  "language": "en",
  "categories": {
    "session.start": {
      "sounds": [
        {
          "file": "sounds/hello.mp3",
          "label": "Hello!",
          "sha256": "abc123..."
        }
      ]
    },
    "task.complete": {
      "sounds": [
        {
          "file": "sounds/done.mp3",
          "label": "Done!",
          "sha256": "def456..."
        }
      ]
    }
  }
}

Directory Structure

my-pack/
  openpeon.json        # Required manifest
  sounds/              # Audio files
    hello.mp3
    done.mp3
    error.mp3
  README.md            # Optional
  LICENSE              # Optional

• Manifest MUST be named openpeon.json at pack root
• Audio paths use forward slashes, relative to manifest
• No ../ traversal above pack root
• Filenames: [a-zA-Z0-9._-]+ only

Audio Constraints

• Individual files: max 1 MB
• Total pack: max 50 MB
• Players MUST validate magic bytes (RIFF, ID3/0xFF, OggS)

IDE Mapping

Each IDE maps its own events to CESP categories. The mapping is defined by the player, not the pack.

Player Behavior

• Players MUST pick a random sound from the category array
• Players SHOULD avoid repeating the last played sound (no-repeat)
• Players MUST support a master volume control (0.0 to 1.0)
• Players MUST allow individual categories to be disabled
• Players SHOULD support a global mute/pause toggle
• If a category has no sounds in the pack, the player MUST silently skip it