https://github.com/heavygee/openacp-openai-tts-plugin
OpenACP plugin — TTS via any OpenAI-compatible /v1/audio/speech endpoint (Kokoro, Chatterbox, AllTalk, F5-TTS)
https://github.com/heavygee/openacp-openai-tts-plugin
Last synced: about 2 months ago
JSON representation
OpenACP plugin — TTS via any OpenAI-compatible /v1/audio/speech endpoint (Kokoro, Chatterbox, AllTalk, F5-TTS)
- Host: GitHub
- URL: https://github.com/heavygee/openacp-openai-tts-plugin
- Owner: heavygee
- License: mit
- Created: 2026-06-11T13:40:47.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-11T17:45:02.000Z (about 2 months ago)
- Last Synced: 2026-06-11T19:20:41.215Z (about 2 months ago)
- Language: TypeScript
- Size: 778 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# openacp-openai-tts-plugin
[](https://github.com/heavygee/openacp-openai-tts-plugin/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/openacp-openai-tts-plugin)
[](LICENSE)
[](package.json)
OpenACP plugin - TTS via any OpenAI-compatible `/v1/audio/speech` endpoint.
Works out of the box with **Kokoro**, **AllTalk**, **F5-TTS**, **StyleTTS2**, and any other server that implements the OpenAI audio speech API. Includes an optional **Chatterbox voice-cloning mode** that uses the `/audio/speech/upload` multipart endpoint for servers that need a reference WAV.
Links: [Contributing](CONTRIBUTING.md) - [Security](SECURITY.md) - [Support](SUPPORT.md) - [Changelog](CHANGELOG.md)
---
## Install
```bash
openacp plugin install openacp-openai-tts-plugin
```
## Configure
During install you will be prompted for:
- **Server URL** - base URL of your TTS server (default: `http://localhost:8880` for Kokoro)
- **Model** - model name to pass to the server (default: `kokoro`)
- **Voice** - voice identifier (default: `af_bella`); used by the standard `/v1/audio/speech` endpoint
- **API key** - optional; sent as `Authorization: Bearer ` if provided
- **Voice file path** - optional; absolute path to a reference WAV >5s; enables Chatterbox mode (see below)
Reconfigure at any time:
```bash
openacp plugin configure openacp-openai-tts-plugin
```
Then point `@openacp/speech` at this provider:
```json
// plugins/data/@openacp/speech/settings.json
{ "ttsProvider": "openai-compatible" }
```
---
## Server quick-reference
Popular local TTS servers and their default ports:
- **Kokoro** - `http://localhost:8880` - model: `kokoro`, voices: `af_bella`, `bm_george`, etc.
- **AllTalk** - `http://localhost:7851` - model: depends on loaded model
- **F5-TTS** - `http://localhost:7860` - model: `F5-TTS`
- **Chatterbox** - `http://localhost:18002` - model: `chatterbox-turbo` (see Chatterbox mode below)
---
## Chatterbox mode
Chatterbox's standard `/v1/audio/speech` endpoint ignores the `voice` field and uses a server-side configured sample — which is often <5s on a default install, causing a `"Audio prompt must be longer than 5 seconds!"` error.
Set `voiceFilePath` to an absolute path pointing at a WAV file longer than 5 seconds. The plugin will switch to the `/audio/speech/upload` multipart endpoint, sending your reference WAV on every request for voice cloning.
When running OpenACP in Docker, mount your voices directory and use the container path:
```yaml
# compose.yml
services:
openacp:
...
volumes:
- /path/to/voices:/voices:ro
extra_hosts:
- host.docker.internal:host-gateway
```
Then set:
- endpoint: `http://host.docker.internal:18002`
- voiceFilePath: `/voices/your-voice.wav`
---
## Paralinguistic tags (Chatterbox)
Embed these directly in text for expressive output:
`[laugh]` `[chuckle]` `[cough]` `[sigh]` `[gasp]` `[clear throat]`
---
## Updating
`npx` caches the resolved package for ~24h; if you run via `openacp` and want
the latest plugin without reinstalling:
```bash
openacp plugin update openacp-openai-tts-plugin
```
Or pin to the latest tagged release:
```bash
openacp plugin install openacp-openai-tts-plugin@latest
```
---
## Development
```bash
git clone https://github.com/heavygee/openacp-openai-tts-plugin.git
cd openacp-openai-tts-plugin
npm install
npm run build && npm test
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor flow
(issue-first workflow, conventional commits, PR checklist, release
automation via release-please).
---
## License
MIT - see [LICENSE](LICENSE).