audio-cog

# Audio Cog - AI Audio Generation Powered by CellCog

Create professional audio with AI — voiceovers, music, sound effects, and personalized avatar voices.

## Meta-Skill Entrypoint

Meta-skills should run this skill as `skill_exec` when they need OpenRouter
audio. The entrypoint is a deterministic Python adapter. During MetaSkill
execution it receives a short-lived provider connection from ordinary Provider
Settings in the child process only; the credential and endpoint never enter
`with`, argv, the plan, or persisted run data. It calls the configured
OpenRouter audio model, writes a browser-playable WAV file under the supplied
output directory, and prints either `AUDIO_READY:` or a single failure label.
Do not spawn an LLM sub-agent just to generate audio.

Prefer JSON payload mode when the caller already has a narration script:

```json
{"script": "exact spoken narration text"}
```

In payload mode the adapter asks the audio model to speak exactly that
transcript and not add acknowledgements, titles, or setup text.

## OpenSquilla Compatibility Contract

When invoked from OpenSquilla, this skill is an adapter around the caller's
configured provider. Do not require `CELLCOG_API_KEY`, do not assume the
`cellcog` package is installed, and do not invent provider credentials.

For `AwesomeWebpageMetaSkill`:

- Use the code-owned OpenRouter capability candidate and the volatile provider
  lease resolved from ordinary Provider Settings after explicit approval.
- Use only `config.awesome_webpage.openrouter.models.audio_generation` for
  audio model selection.
- Save generated or processed files only under
  `config.awesome_webpage.output_dir/project/assets/audio`.
- If the OpenRouter key, audio model, or output directory is missing, return a
  concise `AUDIO_CONFIG_NEEDED` report listing the missing config keys.
- If the configured OpenRouter model cannot return a browser-playable audio
  file, return `AUDIO_MODEL_UNSUPPORTED` with the narration/script, desired
  duration, style, and target filename so the webpage can expose a clean
  replacement slot instead of failing the whole project.

### On success: `AUDIO_READY` manifest line (required)

After every successful save, end your reply with one single-line JSON record
per file so `AwesomeWebpageMetaSkill` can collect and bind the assets:

```
AUDIO_READY: {"local_path": "project/assets/audio/<slug>.wav", "mime": "audio/wav", "duration_s": <int_or_null>, "voice": "<voice>", "script_preview": "<first 80 chars>"}
```

- One `AUDIO_READY:` line per audio file. No trailing prose on that line.
- `local_path` MUST be the relative path `project/assets/audio/...`. Do NOT
  emit an absolute path here.
- On failure, emit one of `AUDIO_CONFIG_NEEDED`, `AUDIO_MODEL_UNSUPPORTED`, or
  `AUDIO_GENERATION_FAILED` as a single-line label with the replacement-slot
  path so the page can render a placeholder.

## OpenRouter Audio API Contract (hard rule for `openai/gpt-audio*`)

The default CellCog code-path is **wrong** for OpenSquilla and will fail.
OpenRouter routes `openai/gpt-audio` / `openai/gpt-audio-mini` through OpenAI's
audio-output mode, which has a strict request shape:

- `POST {base_url}/chat/completions` with body:
  ```
  {
    "model": "<audio_generation>",
    "stream": true,
    "modalities": ["text", "audio"],
    "audio": {"voice": "alloy", "format": "pcm16"},
    "messages": [...]
  }
  ```
- `stream: true` is REQUIRED. Non-streaming requests are rejected with
  HTTP 400 "Audio output requires stream: true".
- `audio.format` MUST be `pcm16` when streaming. `mp3`, `opus`, `flac`,
  `wav` are all rejected as "unsupported_value" — there is no alternative
  combo. Sending `format=mp3` (any stream setting) burns ~190 s of
  per-attempt timeout for nothing; do not try it.
- Read the SSE response, base64-decode each `delta.audio.data` chunk,
  concatenate the raw 24kHz mono signed-16-bit-little-endian PCM stream,
  then save it as a browser-playable WAV file.
- Final on-disk asset is `.wav`. Set MIME to `audio/wav` in the manifest.
- If the required MetaSkill provider lease is missing or invalid, emit
  `AUDIO_CONFIG_NEEDED` and exit 78 before any provider submission. Direct
  standalone CLI use may still read `OPENROUTER_API_KEY`; never fall back to
  `CELLCOG_API_KEY` or another provider.
- Provider/model failures after submission remain an exit-0 degradation with a
  structured replacement slot. They are never automatically replayed.

Upstream CellCog instructions are intentionally omitted from the executable
prompt body. OpenSquilla meta-skills use the entrypoint above; provenance is
kept in frontmatter for registry/audit purposes.