Ambora

Atmospheric music manager for tabletop RPG sessions with phone remote control.

---

Features

• Campaign-based organization — Group climates and tracks by campaign for easy session prep
• One-tap climate switching — Switch between combat, tavern, forest, and more from your phone
• Smooth crossfading — Configurable crossfade between climates for seamless transitions
• YouTube + local files — Mix YouTube tracks and local audio files (MP3, WAV, OGG, FLAC)
• Campaign soundboard — Trigger one-shot effects from the desktop, keyboard, or phone remote
• Phone remote control — Control playback from any phone on your local WiFi via QR code
• Fully offline — No internet required for local file playback (YouTube needs connectivity)
• Cross-platform — macOS, Windows, and Linux

Install

Download the installer for your platform from the latest release.

macOS

Download the .dmg for your Mac: arm64 for Apple Silicon, x64 for Intel. macOS builds are signed with an Apple Developer ID and notarized, so they open normally after you drag Ambora.app to Applications.

Windows

Windows SmartScreen may warn that the app is from an unknown publisher. Click More info → Run anyway.

Updates

From 0.10.0, Ambora checks GitHub Releases for a new version when it starts and every few hours. A new version downloads in the background and installs the next time you quit. Ambora never restarts on its own, and the sidebar offers Restart now if you'd rather not wait. Versions before 0.10.0 need one last manual install.

This works on macOS, on Windows with the installer, and on Linux with the AppImage. A .deb install updates through your package manager. The check is a plain request to GitHub and sends no telemetry; offline, it fails silently.

Quick Start

Prerequisites

• Node.js 20.x or later
• npm 10.x or later

Development

# Clone the repository
git clone https://github.com/xetorthio/ambora.git
cd ambora

# Install dependencies
npm install

# Start in development mode
npm run dev

Build

# Production build
npm run build

# Build installer for your platform
npm run dist

Usage

1. Create a campaign — Set up a campaign for your adventure
2. Add climates — Create moods like "Tavern", "Combat", "Forest" with colors and icons
3. Add tracks — Paste YouTube URLs or pick local audio files for each climate
4. Add sound effects — Import one-shot sounds and optionally assign letter shortcuts
5. Start a session — Click the QR code icon, scan from your phone
6. Play — Tap climates and sound effects from your phone

See the Soundboard Guide for file import, shortcuts, playback modes, icons, and remote usage.

Tech Stack

• Desktop: Electron + React + TypeScript
• Styling: Tailwind CSS v4 + shadcn/ui
• Audio: Web Audio API + YouTube IFrame API
• State: Zustand
• Remote: Express + WebSocket over local WiFi
• Build: electron-vite + electron-builder

Contributing

Contributions are welcome! Please read our Contributing Guide and Code of Conduct before submitting a PR.

License

MIT — Jonathan Leibiusky (@xetorthio)

Bundled FFmpeg binaries are separate subprocesses with their own licenses — see THIRD_PARTY_NOTICES.md.

Acknowledgments

• shadcn/ui for the component library
• Lucide for the icon set
• electron-vite for the build tooling
• FFmpeg for loudness analysis and audio probing