# forge

Event-driven stream automation with multi-engine TTS - a single Rust desktop app for Linux, Windows, and macOS.

[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](./LICENSE)
[![Rust 1.97.1+](https://img.shields.io/badge/rust-1.97.1%2B-orange)](https://www.rust-lang.org/)
[![Platforms](https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20macOS-green)](#installing-releases)

[![Latest Release](https://img.shields.io/github/v/release/IceSqueez/forge?include_prereleases&logo=github&label=Latest&cacheSeconds=600)](https://github.com/IceSqueez/forge/releases)
[![Release Date](https://img.shields.io/github/release-date-pre/IceSqueez/forge?logo=github&label=Released&cacheSeconds=600)](https://github.com/IceSqueez/forge/releases)
[![Release Workflow](https://github.com/IceSqueez/forge/actions/workflows/release.yml/badge.svg)](https://github.com/IceSqueez/forge/actions/workflows/release.yml)
[![Nightly Workflow](https://github.com/IceSqueez/forge/actions/workflows/nightly.yml/badge.svg)](https://github.com/IceSqueez/forge/actions/workflows/nightly.yml)

[![Commits Since Latest Release](https://img.shields.io/github/commits-since/IceSqueez/forge/latest?include_prereleases&logo=github&label=Commits%20since&cacheSeconds=600)](https://github.com/IceSqueez/forge/commits/main)
[![Open Issues](https://img.shields.io/github/issues/IceSqueez/forge?logo=github&label=Issues&cacheSeconds=600)](https://github.com/IceSqueez/forge/issues)
[![Commit Activity](https://img.shields.io/github/commit-activity/m/IceSqueez/forge?logo=github&label=Activity&cacheSeconds=600)](https://github.com/IceSqueez/forge/pulse)
[![Total Downloads](https://img.shields.io/github/downloads/IceSqueez/forge/total?logo=github&label=Downloads&cacheSeconds=600)](https://github.com/IceSqueez/forge/releases)

Connect to Twitch, YouTube, and Kick simultaneously. React to chat events with action chains that control OBS, send messages, run scripts, play sounds, and speak text through configurable TTS engines.

## Features

### Chat platforms
- **Twitch**
  - EventSub triggers: chat (commands, messages, cheers), shared-chat, subs/resubs/gift-subs, follows, raids (received & sent), channel-point redemptions (custom & automatic) & reward CRUD, polls, predictions, hype train, charity, goals, moderation (ban/timeout/unban, mod add/remove, shield mode, suspicious users, warning acknowledged), shoutouts (sent & received), guest-star, ad break, automod, stream on/off, channel & chat-settings updates
  - Sub-actions: send chat/reply/announcement/whisper, ban/timeout/unban/warn, mod & VIP management, shoutout, start/cancel raid, run/snooze ad, poll & prediction lifecycle, reward CRUD & redemption fulfillment, automod approve/deny/terms, update title/category/tags, stream marker, get current goal, guest-star & shield-mode control, chat clear & message delete
- **YouTube** (live-chat polling)
  - Triggers: chat message, chat command, Super Chat, Super Sticker, message deleted, new member, member milestone, membership gift (mass) & gift received, stream online/offline, stream title changed, user banned/timed-out
  - Sub-actions: send/delete chat message, ban/timeout/unban user, add/remove moderator, update stream title/description/category/privacy
- **Kick** (official API for writes & polled reads; chat receive over a community WebSocket)
  - Triggers: chat message, chat command, message deleted, new subscriber, subscription gift, host received, ban, livestream status, livestream metadata, reward redeemed
  - Sub-actions: send/delete chat message, ban/timeout/unban user, update channel title/category/tags, reward create/update/delete, redemption accept/reject

### Actions & automation
- Action editor with trigger configuration and nested sub-action chain authoring
- **Nested flow control:** if/then/else branches, loops (count / foreach-array / while), switch/case, break/continue, stop chain, delay (fixed duration or wait-until-condition) - each flow-control step contains its own sub-chain authored via drill-in
- **Built-in sub-action library grouped by area:**
  - **Action & trigger control** - run another action, cancel action, enable/disable/toggle action or trigger instance
  - **Globals & variables** - set, get, increment, decrement, toggle (bool), array append/remove on named globals; per-user get/set/increment; local execution-scoped args
  - **Strings** - concat, substring, replace, case conversion, trim, split, regex match, format template
  - **Math & random** - expression evaluation; random int, float, bool, and weighted pick
  - **Date & time** - get current time, format, diff, arithmetic, parse
  - **File (sandboxed)** - read, write/append, delete, list directory
  - **HTTP** - GET, POST, PUT, PATCH, DELETE with headers, query params, body, and JSON/text response parsing
  - **Queue control** - pause, resume, clear action queue
  - **Desktop** - OS notification, clipboard read/write, open URL in browser
  - **TTS** - speak text, stop, pause/resume/skip/clear queue, set/switch voice alias
  - **Soundboard** - play clip, stop clip, stop all, set master volume
  - **Script** - run inline rhai snippet, run named script, emit custom event to bus
  - **Server** - broadcast event payload to connected WebSocket clients (dashboards, companion apps)
  - **Overlay** - send content to a registered overlay by name, with an optional per-send duration override
- Platform sub-actions (Twitch, YouTube, Kick, OBS, VTube, Discord, MIDI) selectable in the same editor
- Command parser for chat-triggered actions
- Queue scheduling: Sequential or RandomPick execution

### Integrations
- **OBS WebSocket v5** - switch scene, source visibility, input mute, start/stop stream/record; scene-changed trigger
- **VTube Studio** - model load/move, expression set, parameter set/reset
- **Discord** - post text, embed, edit message
- **MIDI** - note-on/off triggers, CC triggers
- **System hotkeys** - global key-combination triggers
- **Soundboard** - clip grid with per-clip output device and volume; `PlaySound` sub-action

### TTS pipeline
- Local engines: Piper (ONNX), eSpeak-NG, SAPI (Windows), NSpeech (macOS)
- Cloud engines: Azure, OpenAI, ElevenLabs, Amazon Polly
- Voice aliases with text-replacement preprocessing filters
- Speak queue with pause, resume, and skip controls

### Scripting & storage
- Rhai sandbox: op-count and time limits, `ForgeApi` access, hot-reload
- Named globals with `%variable%` interpolation; JSON export
- SQLite backend with AES-GCM encrypted credentials; 7-day event log

### Overlays & server
- Overlay Designer: a registry of typed browser-source overlays (Alert, Frame, Ticker, Chat, Goal) with a generated page per overlay, a properties panel, a native preview, and a source-code escape hatch per file
- Overlays are driven entirely by actions - a "Send to Overlay" sub-action pushes content to one overlay by name; there is no separate event-subscription setup
- Each overlay serves at a stable URL (`http://<host>:<port>/overlays/<id>/`) to paste into an OBS browser source; renaming an overlay never changes that URL
- WebSocket server at `/ws/v1/` - 14+ methods, bearer-token auth, per-client subscriptions, Origin-checked handshake
- HTTP overlay host with path-traversal sandbox and configurable CORS
- Live server screen: connected-client list, bandwidth metrics, lifecycle controls

### UI
- Event Feed with filter chips, pause/resume, per-event payload inspector, and one-click event replay
- Live Chat screen across all connected platforms; Viewers screen with per-platform filter
- Settings: appearance (density + font pickers), language (English / Ukrainian), keyboard shortcuts editor, audio device test

## Installing releases

Binary releases for Linux, Windows, and macOS are on [GitHub Releases](https://github.com/IceSqueez/forge/releases).

- **Linux:** AppImage, `.deb` (Debian/Ubuntu), `.rpm` (Fedora/openSUSE) - x86_64
- **Windows:** portable `.exe` + MSI installer
- **macOS:** universal `.dmg` (Apple Silicon + Intel)

## Building from source

**Requires Rust 1.97.1 or later** - [install via rustup](https://rustup.rs/).

Linux also needs: `sudo apt-get install build-essential pkg-config libssl-dev` (Debian/Ubuntu).

```bash
git clone https://github.com/IceSqueez/forge.git
cd forge
cargo build --release
./target/release/forge
```

On first run, forge creates its data directory (XDG on Linux, AppData on Windows, Application Support on macOS) and opens to the dashboard.

## Contributing

Open an issue or pull request on [GitHub](https://github.com/IceSqueez/forge).

## License

Licensed under either of [MIT](./LICENSE-MIT) or [Apache 2.0](./LICENSE-APACHE) at your option.
