Skip to main content
PeonPing uses the Coding Event Sound Pack (CESP) specification — an open standard that any agentic IDE can adopt. You can create custom packs with your favorite game characters, movie quotes, or even your own voice.

​
Pack structure

A sound pack is a directory with audio files and a manifest: 
my-pack/
  openpeon.json        # CESP manifest (required)
  sounds/              # Audio files
    Hello.wav
    Done.mp3
    Error.ogg
    ...
  README.md            # Description (recommended)
  LICENSE              # License (recommended)
Supported formats: WAV, MP3, OGG, FLAC, AAC, M4A, OPUS Size limits:
  • Max 1 MB per file
  • Max 50 MB total per pack
Keep files small — game sound effects are ideal. Long audio files waste bandwidth and slow down playback.

​
CESP manifest format

The openpeon.json file maps your sounds to CESP event categories:
openpeon.json
{
  "cesp_version": "1.0",
  "name": "my_pack",
  "display_name": "My Character",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "github": "yourname"
  },
  "license": "CC-BY-NC-4.0",
  "language": "en",
  "categories": {
    "session.start": {
      "sounds": [
        { "file": "sounds/Hello.wav", "label": "Hello there" },
        { "file": "sounds/Ready.wav", "label": "Ready to work?" }
      ]
    },
    "task.complete": {
      "sounds": [
        { "file": "sounds/Done.mp3", "label": "Done" },
        { "file": "sounds/Finished.mp3", "label": "All finished" }
      ]
    },
    "task.error": {
      "sounds": [
        { "file": "sounds/Error.ogg", "label": "Oops" }
      ]
    },
    "input.required": {
      "sounds": [
        { "file": "sounds/NeedHelp.wav", "label": "Need your help" }
      ]
    }
  }
}

​
Required fields

FieldTypeDescription
cesp_versionstringCESP spec version (use "1.0")
namestringPack ID (lowercase, no spaces, use underscores)
display_namestringHuman-readable name
versionstringSemver (e.g., "1.0.0")
categoriesobjectSound mappings (see below)

​
Optional fields

FieldTypeDescription
authorobject{ "name": "...", "github": "..." }
licensestringLicense (e.g., "CC-BY-NC-4.0", "MIT")
languagestringLanguage code (e.g., "en", "zh", "ja")
descriptionstringShort description
tagsarrayTags like ["game", "sci-fi"]

​
CESP categories

Map your sounds to these event categories:
CategoryWhen it playsRequired?
session.startSession starts✅ Recommended
task.acknowledgeAgent acknowledges task❌ Optional
task.completeAgent finishes and waits✅ Recommended
task.errorError or failure✅ Recommended
input.requiredPermission needed✅ Recommended
resource.limitRate/token limit hit❌ Optional
user.spamRapid prompts (3+ in 10s)❌ Optional
session.endSession ends❌ Optional (not yet triggered)
task.progressProgress update❌ Optional (not yet triggered)
Not every category is required. Include only the ones you have sounds for. At minimum, provide session.start, task.complete, task.error, and input.required.

​
Sound entries

Each category contains an array of sound objects: 
{
  "file": "sounds/Hello.wav",
  "label": "Hello there"
}
FieldTypeDescription
filestringPath relative to pack root (e.g., "sounds/Hello.wav")
labelstringHuman-readable description (shown in previews)
Multiple sounds per category are supported — PeonPing picks one randomly each time, avoiding repeats.

​
Install a local pack

1

Create your pack directory

mkdir -p ~/my-peon-pack/sounds
2

Add audio files

cp ~/Downloads/hello.wav ~/my-peon-pack/sounds/
cp ~/Downloads/done.mp3 ~/my-peon-pack/sounds/
3

Create openpeon.json

Use the template above and save it as ~/my-peon-pack/openpeon.json.
4

Install the pack

peon packs install-local ~/my-peon-pack
This copies the pack to ~/.openpeon/packs/my_pack/.
5

Activate the pack

peon packs use my_pack
6

Test it

peon preview session.start
You should hear your custom greeting sounds.

​
Share your pack

To make your pack available to everyone:
1

Create a GitHub repo

cd ~/my-peon-pack
git init
git add .
git commit -m "Initial pack"
gh repo create yourname/openpeon-mypack --public --source=. --push
2

Tag a release

git tag v1.0.0
git push origin v1.0.0
3

Register in the OpenPeon registry

  1. Fork PeonPing/registry
  2. Add your pack to index.json (keep alphabetical order):
{
  "name": "my_pack",
  "display_name": "My Character",
  "author": "yourname",
  "source_repo": "yourname/openpeon-mypack",
  "source_ref": "v1.0.0",
  "source_path": "",
  "tags": ["custom", "game"]
}
  1. Open a pull request
4

Wait for merge

Once merged, your pack will be installable:
peon packs install my_pack
And listed on openpeon.com/packs.

​
Automate pack creation

If you have a single audio file with all quotes, you can auto-transcribe and split it:
1

Transcribe with timestamps

Option A: Deepgram (cloud, fast)
curl --http1.1 -X POST \
  "https://api.deepgram.com/v1/listen?model=nova-2&smart_format=true&utterances=true&utt_split=0.8" \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @your_audio.mp3 -o transcription.json
Option B: Whisper (local, free)
pip install openai-whisper
whisper your_audio.mp3 --model base --language en \
  --output_format json --word_timestamps True --output_dir .
2

Extract timestamps from JSON

Look for "utterances" (Deepgram) or "segments" (Whisper) with start and end times.
3

Cut individual clips with ffmpeg

ffmpeg -i your_audio.mp3 -ss 0.0 -to 1.5 -c copy sounds/Quote1.mp3
ffmpeg -i your_audio.mp3 -ss 2.0 -to 4.8 -c copy sounds/Quote2.mp3
# Repeat for each quote
4

Map clips to categories

Update openpeon.json with your sound files and labels.

​
Licensing

Sound packs often contain copyrighted audio. Here’s how official packs handle this:
  • Fair use — Personal notification sounds are generally considered fair use
  • Non-commercial — Most packs use CC-BY-NC licenses (no commercial use)
  • Attribution — Always credit the original source in your README
Do NOT sell packs containing copyrighted audio. Keep them free and credit the original creators.
Recommended licenses:
  • CC-BY-NC-4.0 — Attribution, non-commercial
  • MIT — For original recordings
  • CC0 — Public domain

​
Pack validation

Before publishing, validate your pack: 
peon packs install-local ~/my-peon-pack
peon packs use my_pack
peon preview  # Test all categories
Check for:
  • ✅ All audio files exist and play correctly
  • ✅ Manifest is valid JSON
  • ✅ File paths are correct (relative to pack root)
  • ✅ No missing categories (at least 4 recommended ones)
  • ✅ Pack size under 50 MB

​
Advanced: File paths

By default, sounds are in sounds/ subdirectory: 
{ "file": "sounds/Hello.wav" }
You can also use pack-root-relative paths: 
{ "file": "audio/greetings/Hello.wav" }
Or organize by category: 
my-pack/
  openpeon.json
  session/
    start1.wav
    start2.wav
  task/
    complete1.wav
    error1.wav

{
  "categories": {
    "session.start": {
      "sounds": [
        { "file": "session/start1.wav", "label": "Hello" }
      ]
    },
    "task.complete": {
      "sounds": [
        { "file": "task/complete1.wav", "label": "Done" }
      ]
    }
  }
}
Path traversal is blocked. Files must be within the pack directory.

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us