scrapyard-cogworks/README.md

# Scrapyard Cogworks

**A collection of custom Red-DiscordBot cogs by Scrapyard Cogworks**

Homepage: https://homepage.kingstons-scrapyard.net/

---

## Table of Contents

**Deadman**
- [Deadman](#deadman)

**AutoRoom**
- [Installation](#installation)
- [AutoRoom](#autoroom)
- [AutoRoom User Commands](#user-commands)
- [AutoRoom Admin Commands](#admin-commands)
- [How It Works](#how-it-works)
- [Permissions Required](#permissions-required)
- [Scrapyard Cogworks Modifications](#scrapyard-cogworks-modifications)

**Assistant**
- [Assistant](#assistant)
- [Assistant Installation](#assistant-installation)
- [Assistant User Commands](#assistant-user-commands)
- [Assistant Admin/Owner Commands](#assistant-adminowner-commands)
- [Assistant Behavior](#assistant-behavior)

**TtsToy**
- [TtsToy](#ttstoy)
- [TtsToy User Commands](#user-commands-1)
- [Chatterbox Commands](#chatterbox-commands)
- [Owner/Admin Commands](#owneradmin-commands)
- [Emoji Sound Effects](#emoji-sound-effects)
- [Inline Voice Switching](#inline-voice-switching)
- [DECTalk Voice Commands](#dectalk-voice-commands)
- [Chatterbox Special Tokens](#chatterbox-special-tokens)
- [VOX Engine](#vox-engine)
- [MorshuTalk Engine](#morshutalk-engine)
- [TTS Queue System](#tts-queue-system)
- [Web UI](#web-ui)
- [MiniMax Voices (Presets)](#minimax-voices-presets)

---

## Installation

```
[p]repo add scrapyard http://192.168.0.200:3000/kingston/scrapyard-cogworks.git
[p]cog install scrapyard autoroom
[p]load autoroom
```

Deadman (bot owner only):

```
[p]cog install scrapyard deadman
[p]load deadman
```

---

## Deadman

A member of the Scrapyard Cogworks package. A deadman switch that alerts listed users if not disabled before it expires.

- **Owner only**: Only the bot owner can arm, disable, or check status.
- **Arm**: `[p]deadman arm <duration> @user1 @user2 [channel]`
- **Disable**: `[p]deadman disable`
- **Status**: `[p]deadman status`

**Duration format** (flexible string):
- `30s` = 30 seconds
- `6h` = 6 hours
- `2h30m` = 2 hours 30 minutes
- `1d` = 1 day
- `1d12h` = 1 day 12 hours

Supported units: `s`, `m`, `h`, `d`, `w` (and their full names).

When the switch is armed, the bot stores the expiry time and alerts users by DM. If an optional channel is provided, it also posts the alert there. If `[p]deadman disable` is not run before expiry, the listed users are DM'd and pinged that "the deadman switch has been TRIGGERED".

---

## AutoRoom

Automatic voice channel management. When a member joins an AutoRoom Source (voice channel), a brand new AutoRoom is created that they have control over. Once everyone leaves the AutoRoom, it is automatically deleted.

### Requirements

- Python 3.11+
- Red-DiscordBot 3.5.0+
- Dependencies: `func-timeout`, `jinja2`

---

## User Commands

All user commands are under the `[p]autoroom` group (alias: `[p]vc`).

---

### `[p]autoroom settings`

**Aliases:** `about`, `info`

Display current settings for the AutoRoom you are currently in. Shows:

- **Owner** - The current owner of the AutoRoom (or "Server Managed" if no owner)
- **Access** - Whether the room is public, locked, or private
- **Member Roles** - Roles that are allowed to access the room (if applicable)
- **Bitrate** - Current bitrate in kbps
- **Channel Age** - How long the AutoRoom has existed
- **Allowed Members** - Members explicitly allowed into the room
- **Allowed Roles** - Roles explicitly allowed into the room
- **Denied Members** - Members explicitly denied from the room
- **Denied Roles** - Roles explicitly denied from the room

You do not need to be the owner of the AutoRoom to use this command.

---

### `[p]autoroom name <name>`

Change the name of your AutoRoom.

- Maximum channel name length: 100 characters (truncated if longer)
- Rate limited to prevent abuse. If you hit the rate limit, you will be told how long to wait.
- Alternatively, you can rename the channel directly through Discord (right-click on desktop, long-press on mobile). Note: if the server has 2FA enabled, your account needs 2FA to do this.

**Example:**
```
[p]autoroom name Chill Zone
```

---

### `[p]autoroom bitrate <kbps>`

**Aliases:** `kbps`

Change the bitrate of your AutoRoom.

- Minimum: 8 kbps
- Maximum: Server's bitrate limit (depends on server boost level)

**Example:**
```
[p]autoroom bitrate 96
```

---

### `[p]autoroom users <limit>`

**Aliases:** `userlimit`

Change the user limit of your AutoRoom.

- Minimum: 0 (unlimited)
- Maximum: 99

**Example:**
```
[p]autoroom users 5
```

---

### `[p]autoroom claim`

Claim ownership of an AutoRoom.

- You must be in the AutoRoom to claim it.
- You can only claim an AutoRoom if the current owner has left the channel.
- There is a cooldown after the owner leaves before you can claim, in case they come back.
- Moderators, admins, and the server owner can claim at any time regardless of the above restrictions.
- When you claim, the previous owner loses their owner permissions and you gain them.

---

### `[p]autoroom public`

Make your AutoRoom public.

- The room becomes visible and joinable by everyone (or by all member roles if configured).
- All member roles (or @everyone) will be granted connect permissions.

---

### `[p]autoroom locked`

Lock your AutoRoom.

- The room remains visible to everyone but no one can join without being explicitly allowed.
- Users already in the room will remain.
- Use `[p]autoroom allow` to let specific users in.

---

### `[p]autoroom private`

Make your AutoRoom private.

- The room becomes invisible and unjoinable by other users.
- Users already in the room will remain.
- Use `[p]autoroom allow` to let specific users in.

---

### `[p]autoroom allow <members_or_roles...>`

**Aliases:** `add`

Allow one or more users (or roles) into your AutoRoom.

**Scrapyard Cogworks Enhancement:** You can specify multiple users/roles separated by spaces to allow them all at once.

**Accepts:**
- @mentions
- User IDs
- Usernames
- Role mentions
- Role names

**Restrictions:**
- The user/role must be allowed to connect to the original AutoRoom Source channel. If they can't connect to the source, they can't be allowed into the AutoRoom.
- If the AutoRoom uses member roles, you cannot allow a role that is lower in hierarchy than the lowest member role.
- Bot roles can always be allowed.

**Examples:**
```
[p]autoroom allow @User1
[p]autoroom allow @User1 @User2 @User3
[p]autoroom allow 123456789012345678 987654321098765432
[p]autoroom allow @User1 123456789012345678 @SomeRole
```

---

### `[p]autoroom deny <member_or_role>`

**Aliases:** `ban`, `block`

Deny a user (or role) from accessing your AutoRoom.

- If the user is currently in your AutoRoom, they will be disconnected.
- If a role is denied and any members in the room no longer have connect permission as a result, they will be disconnected.
- If the server uses member roles, denying roles may not work as expected.

**Cannot deny:**
- The bot itself
- Yourself (the AutoRoom owner)
- The server owner
- Server admins or admin roles
- Server moderators or moderator roles

**Example:**
```
[p]autoroom deny @TroubleMaker
[p]autoroom deny 123456789012345678
```

---

## Admin Commands

All admin commands are under the `[p]autoroomset` group. Requires the **Manage Server** permission or an admin role.

---

### `[p]autoroomset settings`

Display all current AutoRoom settings for the server, including:

- Admin access to all AutoRooms (on/off)
- Moderator access to all AutoRooms (on/off)
- Bot roles allowed in all AutoRooms
- Per-source settings: room type, destination category, legacy text channel, send messages permission, owner manage channel permission, member roles, room name format, text channel hint, and text channel topic

Also displays warnings if the bot is missing required or optional permissions.

---

### `[p]autoroomset permissions`

**Aliases:** `perms`

Check that the bot has all needed permissions for all configured AutoRoom Sources.

Displays a detailed breakdown per AutoRoom Source showing:
- Required permissions (the cog won't function without these)
- Optional permissions (extra features that won't work without these)
- Where permissions need to be granted (source channel, destination category, or server-wide)

---

### `[p]autoroomset create <source_voice_channel> <dest_category>`

**Aliases:** `enable`, `add`

Create a new AutoRoom Source through an interactive setup wizard.

**Parameters:**
- `source_voice_channel` - The voice channel that users will join to trigger AutoRoom creation
- `dest_category` - The category where new AutoRooms will be created

**The wizard will ask you to configure:**

1. **Room Type:**
   - `public` - Visible and joinable by all. Owner can kick/ban users.
   - `locked` - Visible but not joinable. Owner must allow users in.
   - `private` - Hidden and not joinable. Owner must allow users in.
   - `server` - Public but with no owner. Cannot be modified by users.

2. **Channel Name Format:**
   - `username` - Shows as "Username's Room"
   - `game` - Shows the owner's current game, falls back to username format

**Example:**
```
[p]autoroomset create #create-a-room "Auto Rooms"
```

---

### `[p]autoroomset remove <autoroom_source>`

**Aliases:** `disable`, `delete`, `del`

Remove an AutoRoom Source. The voice channel will remain but will no longer trigger AutoRoom creation.

**Example:**
```
[p]autoroomset remove #create-a-room
```

---

### `[p]autoroomset access`

Control access to all AutoRooms for admin/moderator roles.

---

### `[p]autoroomset access admin`

Toggle whether admins can join locked/private AutoRooms. This is a toggle - run again to disable.

---

### `[p]autoroomset access mod`

Toggle whether moderators can join locked/private AutoRooms. This is a toggle - run again to disable.

---

### `[p]autoroomset access bot add <role>`

Allow a bot role to automatically be granted access to every AutoRoom. The AutoRoom Owner can still manually deny these roles if they choose.

**Example:**
```
[p]autoroomset access bot add @MusicBot
```

---

### `[p]autoroomset access bot remove <role>`

**Aliases:** `delete`, `del`

Remove a bot role from being automatically allowed into every AutoRoom.

**Example:**
```
[p]autoroomset access bot remove @MusicBot
```

---

### `[p]autoroomset modify`

**Aliases:** `edit`

Group command for modifying an existing AutoRoom Source's settings.

---

### `[p]autoroomset modify category <autoroom_source> <dest_category>`

Change the destination category where AutoRooms will be created for a given source.

**Example:**
```
[p]autoroomset modify category #create-a-room "New Category"
```

---

### `[p]autoroomset modify type public <autoroom_source>`

Set the AutoRoom Source to create public rooms (visible and joinable, owner has control).

---

### `[p]autoroomset modify type locked <autoroom_source>`

Set the AutoRoom Source to create locked rooms (visible but not joinable, owner must allow users).

---

### `[p]autoroomset modify type private <autoroom_source>`

Set the AutoRoom Source to create private rooms (hidden, owner must allow users).

---

### `[p]autoroomset modify type server <autoroom_source>`

Set the AutoRoom Source to create server-managed rooms (public, no owner, cannot be modified).

---

### `[p]autoroomset modify name username <autoroom_source>`

Set the channel name format to the username style.

**Format:** `{{username}}'s Room{% if dupenum > 1 %} ({{dupenum}}){% endif %}`

**Example output:** `Kingston's Room`, `Kingston's Room (2)`

---

### `[p]autoroomset modify name game <autoroom_source>`

Set the channel name format to the game style. Shows the owner's currently playing game, or falls back to the username format.

**Format:** `{{game}}{% if not game %}{{username}}'s Room{% endif %}{% if dupenum > 1 %} ({{dupenum}}){% endif %}`

**Example output:** `Minecraft`, `Kingston's Room`

---

### `[p]autoroomset modify name custom <autoroom_source> <template>`

Set a custom channel name format using Jinja2-like template syntax.

**Available variables:**
| Variable | Description |
|----------|-------------|
| `username` | AutoRoom Owner's display name |
| `game` | AutoRoom Owner's current game (empty string if not playing) |
| `dupenum` | Incrementing number starting at 1, for de-duplicating names |

**Statements supported:**
- `{% if %}` / `{% elif %}` / `{% else %}` / `{% endif %}`

**Examples:**
```
[p]autoroomset modify name custom #create-a-room {{username}}'s Chill Zone
[p]autoroomset modify name custom #create-a-room {% if game %}Playing {{game}}{% else %}{{username}}'s Room{% endif %}
```

---

### `[p]autoroomset modify text set <autoroom_source> <hint_text>`

Set a message that will be sent in the AutoRoom's built-in text channel when it is created.

Supports the same template variables as channel names, plus:
| Variable | Description |
|----------|-------------|
| `mention` | The AutoRoom Owner's @mention (pings them) |

**Example:**
```
[p]autoroomset modify text set #create-a-room Hello {{mention}}! Welcome to your AutoRoom. Use `[p]autoroom` to manage it.
```

---

### `[p]autoroomset modify text disable <autoroom_source>`

Disable sending a message to newly created AutoRoom text channels.

---

### `[p]autoroomset modify specialperms ownermodify <autoroom_source>`

Toggle whether AutoRoom Owners get the **Manage Channels** permission on their AutoRoom. This allows them to modify the channel using native Discord controls (name, bitrate, user limit, etc.).

This is a toggle - run again to disable.

---

### `[p]autoroomset modify specialperms sendmessage <autoroom_source>`

Toggle whether users can send messages in the AutoRoom's built-in text channel.

This is a toggle - run again to disable.

---

### `[p]autoroomset modify legacytextchannel enable <autoroom_source>`

Enable the creation of a separate legacy text channel alongside the AutoRoom voice channel. This text channel will be visible only to members in the voice channel and will be deleted when the AutoRoom is deleted.

---

### `[p]autoroomset modify legacytextchannel disable <autoroom_source>`

Disable the creation of a legacy text channel with new AutoRooms.

---

### `[p]autoroomset modify legacytextchannel topic set <autoroom_source> <topic_text>`

Set the topic for the legacy text channel. Supports template variables.

**Example:**
```
[p]autoroomset modify legacytextchannel topic set #create-a-room This channel is for {{username}}'s room. It will be deleted when everyone leaves.
```

---

### `[p]autoroomset modify legacytextchannel topic disable <autoroom_source>`

Disable setting a topic on the legacy text channel.

---

### `[p]autoroomset modify defaults`

**Aliases:** `bitrate`, `memberrole`, `other`, `perms`, `users`

Displays information about how AutoRoom defaults are configured:

- **Bitrate/User Limit** - Copied from the AutoRoom Source channel to the created AutoRoom.
- **Member Roles** - To restrict who can use AutoRooms, deny @everyone from viewing/connecting to the AutoRoom Source and allow only specific roles.
- **Permissions** - All permission overwrites (except Manage Roles) are copied from the AutoRoom Source to the AutoRoom. The bot must have each permission allowed in the destination category or server-wide for it to be copied.

---

## How It Works

1. An admin creates an **AutoRoom Source** - a voice channel that acts as a trigger.
2. When a user joins the AutoRoom Source, the bot:
   - Creates a new voice channel (AutoRoom) in the configured destination category
   - Moves the user into the new channel
   - Grants the user ownership permissions over the channel
3. The AutoRoom Owner can then:
   - Rename the channel
   - Change bitrate and user limits
   - Make it public, locked, or private
   - Allow or deny specific users and roles
4. When all users leave the AutoRoom, it is automatically deleted.

---

## Permissions Required

The bot needs the following permissions:

**Required (server-wide or on source + destination category):**
- Manage Channels
- Manage Roles
- Move Members
- Connect
- View Channel

**Optional (for full feature support):**
- Any permission overwrite on the AutoRoom Source that you want copied to AutoRooms must be allowed for the bot in the destination category.

---

## Scrapyard Cogworks Modifications

This fork includes the following enhancements over the original PhasecoreX version:

### Multi-Allow Support
The `[p]autoroom allow` command now accepts multiple users/roles in a single command. Instead of running the command multiple times, you can whitelist everyone at once:

```
[p]autoroom allow @User1 @User2 @User3 123456789012345678
```

---

## Credits

- Originally developed by [PhasecoreX](https://github.com/PhasecoreX/PCXCogs)
- Modified and maintained by Scrapyard Cogworks

---

---
---

# Assistant

AI chatbot cog that responds in a dedicated channel or when the bot is @mentioned. Uses an OpenAI-compatible API backend. Designed for fun, unpredictable responses — crank the temperature and give it a wild system prompt.

### Features

- **Chat channel mode** — set a channel where the bot responds to every message
- **Ping mode** — responds when @mentioned in any channel
- **Custom system prompt** — control the bot's personality
- **Temperature control** — turn it up for chaotic/funny responses
- **Question mode** — optionally restrict responses to messages ending with `?`
- **Conversation history** — remembers the last 20 messages per channel (in memory only)
- **Long response handling** — automatically chunks replies over 2000 characters

### Requirements

- Python 3.11+
- Red-DiscordBot 3.5.0+
- Dependencies: `aiohttp`

---

## Assistant Installation

```
[p]cog install scrapyard assistant
[p]load assistant
```

---

## Assistant User Commands

The assistant responds automatically in the configured chat channel or when pinged. There are no user-invoked "chat" commands — just talk to it.

**In the chat channel:** Send any message and the bot replies.

**Anywhere else:** @mention the bot with your message.

```
@Bot what's the meaning of life?
```

If **question mode** is on, messages must end with `?` or they'll be ignored.

---

## Assistant Admin/Owner Commands

All commands are under the `[p]assistant` group.

---

### `[p]assistant setkey`

**Requires:** Bot Owner

Set the API key via a private modal dialog. The key is stored globally (shared across all servers the bot is in).

---

### `[p]assistant toggle`

Toggle the assistant on or off for the current server. Enabled by default.

---

### `[p]assistant channel [#channel]`

Set the dedicated chat channel where the bot responds to all messages.

- With a channel: sets that channel as the chat channel.
- Without a channel: clears the setting (bot only responds to @mentions).

**Examples:**
```
[p]assistant channel #bot-chat
[p]assistant channel
```

---

### `[p]assistant model <model>`

Set the AI model to use.

**Examples:**
```
[p]assistant model gemma4
[p]assistant model green-l
[p]assistant model green-r
```

---

### `[p]assistant temp <temperature>`

Set the response temperature.

- Range: `0.0` to `2.0`
- Lower values (0.1–0.5) = focused, predictable responses
- Higher values (1.2–2.0) = creative, chaotic, funny responses

**Examples:**
```
[p]assistant temp 0.3
[p]assistant temp 1.8
```

---

### `[p]assistant system <prompt>`

Set the system prompt that defines the bot's personality and behavior.

**Examples:**
```
[p]assistant system You are a helpful assistant.
[p]assistant system You are an unhinged gremlin who gives terrible life advice in the style of a 90s infomercial host. Everything is an emergency.
[p]assistant system You are a pirate who only speaks in nautical metaphors and refuses to acknowledge anything invented after 1750.
```

---

### `[p]assistant question`

Toggle question mode. When ON, the bot only responds to messages that end with `?`. Everything else is ignored.

This is a toggle — run again to disable.

---

### `[p]assistant clear`

Clear the conversation history for the current channel. The bot will forget all previous context.

---

### `[p]assistant settings`

Display the current configuration as an embed:

- Enabled (yes/no)
- Chat Channel
- API Key (set/not set)
- Model
- Temperature
- Question Mode (on/off)
- System Prompt (first 200 chars)

---

## Assistant Behavior

- **History:** The bot keeps the last 20 messages (user + assistant) per channel in memory. History is lost on cog reload/bot restart.
- **Typing indicator:** The bot shows "typing..." while waiting for the API response.
- **Long responses:** Replies over 2000 characters are split into multiple messages.
- **Error handling:** If the API is down or returns an error, the bot replies with the error info.
- **No response to bots:** The assistant ignores messages from other bots.
- **Per-guild settings:** Model, temperature, system prompt, channel, and question mode are all configured per server.
- **Global API key:** The API key is set once by the bot owner and applies to all servers.

---

---
---

# TtsToy

Multi-engine text-to-speech cog with voice cloning, emoji-triggered sound effects, inline voice switching, a TTS queue system, and a companion web UI. Plays audio in voice channels and uploads MP3 files to chat.

### Engines

| Engine | Description | Requirements |
|--------|-------------|--------------|
| MiniMax | Cloud API with high-quality AI voices | MiniMax API key |
| Chatterbox | Local AI voice cloning server | Chatterbox TTS server running |
| DECTalk | Classic robotic synthesizer (1980s style) | DECTalk server (bundled) |
| Morshu | Speech from Morshu's voice lines (CD-i Zelda) | g2p_en, numpy, pydub |
| VOX | Black Mesa/Half-Life announcer system | VOX word packs (bundled) |

### Requirements

- Python 3.11+
- Red-DiscordBot 3.5.0+
- Dependencies: `requests`, `g2p_en`, `numpy`, `pydub`
- `ffmpeg` installed and on PATH
- Red's Audio cog loaded (for voice channel playback)

### Installation

```
[p]cog install scrapyard ttstoy
[p]load ttstoy
```

---

## User Commands

---

### `[p]tts <text>`

Generate TTS audio and play it in your voice channel. Also uploads the MP3 to chat.

- You must be in a voice channel (except in Chatterbox mode, which can generate audio without VC).
- The bot will auto-join your voice channel if not already connected.
- Supports emoji SFX triggers inline with text.
- Supports inline voice/engine switching with `[mode|voice]` tags.
- Multiple TTS requests in the same guild are queued and played sequentially.
- If music is playing, it is paused during TTS and resumed after.

**Inline voice switching:**
```
[p]tts [minimax|Robotnik] Pingas [dectalk] [:nh]Deep voice [chatterbox|Emily] Hello!
```

Valid mode tags: `minimax`, `chatterbox`, `dectalk`, `morshu`, `vox`

**Emoji SFX example:**
```
[p]tts Hello everyone! 🎉 Welcome to the party 😂
```

---

### `[p]ttstoy`

Top-level configuration group. Running without a subcommand shows help.

---

### `[p]ttstoy myvoice [voice_name]`

Show or set your personal voice.

- With no argument: displays your current voice and lists available voices for the active engine.
- With a voice name: sets your active voice.
- In Chatterbox mode, matches against your uploaded voice clips by display name.
- In DECTalk mode, voice selection is not used (use `[:np]`, `[:nb]`, etc. inline instead).
- In Morshu/VOX mode, no voice selection is available.

**Example:**
```
[p]ttstoy myvoice Robotnik
[p]ttstoy myvoice Emily
```

---

### `[p]ttstoy info`

DMs you detailed usage instructions for TTS Toy, including setup steps (for owners) and end-user instructions.

---

### `[p]ttstoy sfx`

List all available emoji sound effects and their triggers.

Shows each emoji/trigger mapped to its SFX folder, whether audio files are present, and usage examples.

---

### `[p]ttstoy voxwords`

List all available words in the current VOX pack. Only these words will be spoken in VOX mode; unknown words are skipped.

---

### `[p]login`

Shortcut for `[p]ttstoy login`. Gets a one-time login key for Kingston's Scrapyard web sites. The key is DM'd to you.

---

### `[p]ttstoy login`

Get a one-time login key for the TtsToy web UI and Kingston's Scrapyard homepage. Must be used in a server (the key is tied to your guild context). The key is DM'd to you and valid for 5 minutes.

---

### `[p]ttstoy webui`

Get the link to the TtsToy web UI.

---

## Chatterbox Commands

All under the `[p]chatterbox` group.

---

### `[p]chatterbox guide`

Full guide to Chatterbox TTS features, voice cloning workflow, special tokens, and per-voice tuning.

---

### `[p]chatterbox addvoice <name> [url]`

Upload a voice clip for Chatterbox voice cloning.

- Attach a `.wav` or `.mp3` file to the message, OR provide a direct URL to one.
- Recommended: 5-15 seconds of clear speech, one speaker, no background noise.
- `.wav` works best; `.mp3` accepted.
- Short clips are automatically looped to meet the minimum 5-second requirement.
- The voice is automatically set as your active voice after upload.

**Examples:**
```
[p]chatterbox addvoice CoolVoice
(with a .wav attached)

[p]chatterbox addvoice CoolVoice https://example.com/clip.wav
```

---

### `[p]chatterbox removevoice <name>`

Remove a voice from your personal voice list and delete it from the Chatterbox server (if you are the original uploader). Shared copies remain for other users.

If the removed voice was your active voice, it switches to another voice in your list or the default.

---

### `[p]chatterbox myvoices`

List all your uploaded Chatterbox voices. Shows which one is currently active. Provides quick-reference commands for switching, adding, and removing voices.

---

### `[p]chatterbox sharevoice <name> @User`

Share one of your Chatterbox voices with another user. Adds the voice to their library so they can use it with `[p]ttstoy myvoice`.

---

### `[p]chatterbox temp [value]`

Show or set the Chatterbox temperature for your current active voice.

- Range: 0.0 - 1.5
- Lower = more consistent speech, higher = more varied/random.
- Saved per voice per user (each voice remembers its own setting).
- Use `[p]chatterbox temp reset` to clear and use the server default.

---

### `[p]chatterbox exag [value]`

Show or set the Chatterbox exaggeration for your current active voice.

- Range: 0.25 - 2.0
- Higher = more expressive/dramatic delivery.
- Saved per voice per user.
- Use `[p]chatterbox exag reset` to clear.

---

### `[p]chatterbox volume [value]`

Show or set a volume offset (in dB) for your current Chatterbox voice.

- Range: -20.0 to +20.0 dB
- Allows normalizing volume across different voice clips.
- Saved per voice per user.
- Use `[p]chatterbox volume reset` to clear.

---

### `[p]chatterbox speed [value]`

Show or set the playback speed for your current Chatterbox voice.

- Range: 0.25 - 4.0
- 1.0 = normal speed. Higher = faster, lower = slower.
- Saved per voice per user.
- Use `[p]chatterbox speed reset` to clear.

---

### `[p]chatterbox reset`

Reset all per-voice parameters (temperature, exaggeration, volume, speed) for your current active voice to server defaults.

---

## Owner/Admin Commands

---

### `[p]ttstoy mode [mode]`

Show or set the global TTS engine mode.

- `minimax` - MiniMax cloud API (requires API key)
- `chatterbox` - Local Chatterbox TTS server (AI voice cloning)
- `dectalk` - DECTalk classic robotic synthesizer
- `morshu` - MorshuTalk (Morshu's CD-i voice)
- `vox` - Black Mesa VOX announcer

With no argument, shows the current mode and available modes with status info.

---

### `[p]ttstoy key`

Opens a button + modal dialog to securely enter the MiniMax API key.

---

### `[p]ttstoy model [model_name]`

Show or set the MiniMax TTS model.

Available models:
- `speech-01-turbo` - fast and cheap
- `speech-01-hd` - higher quality, slower
- `speech-02-turbo` - newer fast model
- `speech-02-hd` - newer high quality

With no argument, lists known models and the current setting.

---

### `[p]ttstoy voice [voice_name]`

Set or show the global default voice.

- In MiniMax mode: choose from preset voices (BigMan, BlueGnome, Dracafow, Gaben, Grigori, Gnome, King, Peppa, Robotnik) or pass a raw voice ID.
- In Chatterbox mode: set a filename as the global default.
- DECTalk/Morshu/VOX modes do not use voice selection.

---

### `[p]ttstoy sfxvolume [0-100]`

Show or set the volume for emoji-triggered sound effects. Default is 100.

---

### `[p]ttstoy voxpack [pack]`

Show or set the VOX voice pack.

Available packs:
- `vox` - Original Half-Life VOX
- `vox2` - Black Mesa military announcements

---

### `[p]ttstoy accessibility`

Toggle accessibility mode.

When enabled:
- Forces DECTalk engine regardless of mode setting.
- Disables emoji SFX (emojis are stripped instead of triggering sound effects).

---

### `[p]chatterbox url [url]`

Show or set the Chatterbox TTS server URL. Default: `http://127.0.0.1:8099`

Tests connectivity when showing or setting.

---

### `[p]chatterbox model [turbo|original]`

Show or switch the Chatterbox model (hot-swap).

- `turbo` - Fast (350M params), supports special tokens like `[laugh]`, `[cough]`, etc.
- `original` - Better voice cloning (0.5B params), stronger emotion control.

---

### `[p]ttstoy dectalkurl [url]`

Show or set the DECTalk API server URL. Tests connectivity.

---

### `[p]ttstoy dectalkinstall`

Install the bundled DECTalk server (runs `npm install` in the dectalk-server directory). Requires Node.js and npm.

---

### `[p]ttstoy dectalkstart`

Manually start the bundled DECTalk server process.

---

### `[p]ttstoy dectalkstop`

Stop the bundled DECTalk server process.

---

### `[p]ttstoy dectalkstatus`

Show DECTalk server status: installed, process running, API responding, auto-start setting, and URL.

---

### `[p]ttstoy dectalkautotoggle`

Toggle auto-start for the bundled DECTalk server. When enabled, the server starts automatically when switching to DECTalk mode or on cog load.

---

### `[p]ttstoy webuistatus`

Check the status of the TtsToy web UI subprocess (running, reachable, URL, PID).

---

### `[p]ttstoy webuirestart`

Restart the TtsToy web UI subprocess.

---

### `[p]ttstoy webuichannel [#channel]`

Set or show the channel where web UI TTS audio is posted in the current server. If not set, falls back to any channel named `tts`, `ttstoy`, or `tts-toy`.

---

## Emoji Sound Effects

Include supported emoji in your TTS text to trigger sound effects. SFX are spliced inline between TTS segments.

**Default emoji mappings:**

| Emoji | Sound | Emoji | Sound |
|-------|-------|-------|-------|
| 🎉 | party | 😂 | laugh |
| 🥖 | spy | 👏 | clap |
| 🔥 | fire | 💀 | skull |
| ✅ | check | ❌ | error |
| 📢 | airhorn | 🚢 | boathorn |
| 😶 | drum | 👼 | angel |
| 🥜 | cashew | 💪 | physical |
| 🧠 | intelligence | 👁 | psychic |
| ✍️ | motor | | |

Custom Discord emoji are also supported if their `:name:` is mapped in the emoji map.

The emoji-to-SFX mapping is stored in `sfx/emoji_map.json` and can be edited via the web UI.

---

## Inline Voice Switching

You can switch engines and voices mid-sentence using `[mode|voice]` tags:

```
[p]tts [minimax|Robotnik] I am the Eggman! [dectalk] [:nh]Now in DECTalk [chatterbox|Emily] And now Chatterbox
```

- `[mode]` - switch engine only, keep current voice
- `[mode|voice]` - switch engine and voice
- Valid modes: `minimax`, `chatterbox`, `dectalk`, `morshu`, `vox`

---

## DECTalk Voice Commands

When in DECTalk mode, control voices inline in your text:

| Command | Voice |
|---------|-------|
| `[:np]` | Perfect Paul (default, male) |
| `[:nb]` | Beautiful Betty (female) |
| `[:nh]` | Huge Harry (male) |
| `[:nf]` | Frail Frank (male) |
| `[:nd]` | Doctor Dennis (male) |
| `[:nk]` | Kit the Kid (child) |
| `[:nu]` | Uppity Ursula (female) |
| `[:nr]` | Rough Rita (female) |
| `[:nw]` | Whispering Wendy (female) |

You can switch voices mid-sentence: `[p]tts [:nh]Deep voice [:nb]Now female`

DECTalk also supports phoneme commands and singing.

---

## Chatterbox Special Tokens

When using the Chatterbox Turbo model, these tokens produce non-speech vocalizations:

`[laugh]` `[chuckle]` `[sigh]` `[gasp]` `[cough]` `[clear throat]` `[sniff]` `[groan]` `[shush]`

**Example:**
```
[p]tts Hey [chuckle] thanks for calling back [laugh]
```

---

## VOX Engine

The VOX engine concatenates pre-recorded word WAV files from the Black Mesa/Half-Life announcement system. Only words that exist in the VOX dictionary are spoken; unknown words are silently skipped.

Two packs are available:
- `vox` - Original Half-Life VOX (500+ words)
- `vox2` - Black Mesa military announcements (250+ words)

Use `[p]ttstoy voxwords` to see all available words for the current pack.

---

## MorshuTalk Engine

Generates speech by matching phonemes from input text to Morshu's voice samples from the CD-i Zelda games. Uses grapheme-to-phoneme conversion (g2p_en) to break text into phonemes, then concatenates matching audio snippets.

No voice selection needed. All text is always spoken in Morshu's voice.

---

## TTS Queue System

- Each guild has its own TTS queue.
- Multiple `[p]tts` requests are queued and played in order.
- If music is playing, it is paused before TTS and resumed after all queued TTS finishes.
- Queue position is shown when multiple items are queued.

---

## Web UI

TtsToy includes a companion Flask web UI for managing voices, generating TTS, and controlling settings from a browser.

- Login via `[p]ttstoy login` (DMs you a one-time key)
- Access at the configured URL (default: `https://ttstoy.kingstons-scrapyard.net`)
- Features: voice management, TTS generation, parameter tuning, SFX mapping editor
- TTS generated from the web UI is played in the user's current voice channel and posted to the configured Discord channel

---

## Health Endpoint

TtsToy exposes a health check HTTP endpoint at port 8097:
- `GET /health` returns `{"status": "ok", "service": "ttstoy"}`

---

## MiniMax Voices (Presets)

| Label | Description |
|-------|-------------|
| BigMan | - |
| BlueGnome | - |
| Dracafow | - |
| Gaben | - |
| Grigori | - |
| Gnome | Default voice |
| King | - |
| Peppa | - |
| Robotnik | - |

Custom voice IDs can also be passed directly.

---

## Credits

- MiniMax TTS API: https://www.minimaxi.com/
- Chatterbox TTS: https://github.com/resemble-ai/chatterbox
- DECTalk: Classic DEC speech synthesizer
- MorshuTalk engine by jalenluorion: https://github.com/jalenluorion/MorshuTalk
- VOX engine based on VOXGen by wphillips: https://github.com/wphillips/VOXGen
- Maintained by Scrapyard Cogworks

---

## Support

Visit us at https://homepage.kingstons-scrapyard.net/