spora-plugin-muse

# spora-plugin-muse

Meta Muse vendor home for [Spora](https://github.com/spora-ai/spora) agents. v1 ships two capabilities sharing one Meta Model API key:

- **Muse Voice Transcribe** (`muse-voice-transcribe-1.0`) — speech-to-text via `POST https://api.meta.ai/v1/asr/transcribe`. Browser audio containers (webm/opus, ogg/opus, mp4/AAC) are transcoded to mono 16-bit PCM WAV at 24 kHz via `ffmpeg`.
- **Muse Image** (`muse-image-1.0`) — image generation + editing via Meta's OpenAI-compatible `/v1/images/generations` and `/v1/images/edits` endpoints. Generate (text-to-image) + edit (image-to-image / compose) operations, Media Archive ingest.

Future Muse capabilities (Spark text, Glimmer TTS, Muse Video) slot into this plugin as additional tools/providers — install once, get all Meta Muse capabilities.

> **Pre-release notice (v0.1.0).** The plugin depends on `Spora\Speech\SpeechToTextProviderInterface` (the speech-input contract added in `spora-core` for the speech-input plan). That contract lands on `spora-core`'s `main` as part of an upcoming core release; until the first tagged core that ships the interface is published, `php bin/spora plugin:install spora-ai/spora-plugin-muse` against the released `spora-core` will fail at boot with `Class "Spora\Speech\SpeechToTextProviderInterface" not found`. To run the plugin today, install it against `spora-core`'s `main` (or the `feat/speech-input-core-contract` branch) — see [Local development](#local-development) below. The `v0.1.0` tag will be cut **after** the matching core release ships.

## Installation

```bash
php bin/spora plugin:install spora-plugin-muse
php bin/spora spora:install
```

## Requirements

`ffmpeg` MUST be installed and reachable by either `$PATH` (default) or the `SPORA_FFMPEG_BINARY` env var pointing at an absolute path. The STT provider transcodes browser audio via Symfony Process. Image generation does NOT need ffmpeg.

```bash
# Debian / Ubuntu
sudo apt-get install -y ffmpeg

# macOS
brew install ffmpeg
```

## Configuration

Settings → Tools → Muse. Cascade: agent → principal → global.

| Setting                | Capability | Required | Default  | Notes |
| ---------------------- | ---------- | -------- | -------- | ----- |
| `api_key`              | both       | yes      | —        | Meta Model API key; one key serves all Muse capabilities. Generate at <https://dev.meta.ai> → API Keys. E