https://github.com/rollberrystudios/bardberry

Local-first music, ambience, and SFX cockpit for tabletop RPG sessions.
https://github.com/rollberrystudios/bardberry

ambience electron react soundboard tabletop-rpg typescript vtt

Last synced: 28 days ago
JSON representation

Local-first music, ambience, and SFX cockpit for tabletop RPG sessions.

• Host: GitHub
• URL: https://github.com/rollberrystudios/bardberry
• Owner: RollBerryStudios
• License: mit
• Created: 2026-05-05T09:20:30.000Z (about 2 months ago)
• Default Branch: main
• Last Pushed: 2026-05-26T07:36:58.000Z (about 1 month ago)
• Last Synced: 2026-05-26T09:30:00.609Z (about 1 month ago)
• Topics: ambience, electron, react, soundboard, tabletop-rpg, typescript, vtt
• Language: TypeScript
• Size: 7.76 MB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  



BardBerry




  Lokales Audio-Cockpit für Pen-&-Paper-Runden


  Local-first music, ambience, and SFX cockpit for tabletop RPG sessions





  

  

  

  

  

  





  Deutsch  |  English



---

## Deutsch

BardBerry ist eine **kostenlose, quelloffene Desktop-App für lokale Musik,

Ambience und Soundeffekte am Spieltisch**. Sie ist für Game Master gebaut,

die ihre virtuelle oder hybride Runde atmosphärisch steuern wollen, ohne

Cloud-Konto, Browser-Tab, Abo oder Streaming-Abhängigkeit.

Die App ist aus dem Audio-Workflow von BoltBerry herausgelöst und als

eigenständiges Electron-Projekt neu verpackt: ein fokussiertes Live-Cockpit

für Musik, Ambiente, Kampfmusik und schnelle SFX-Boards.

- **Lokal-first** - deine Audio-Dateien und Soundboards bleiben auf deinem Rechner

- **Live-Mixer** - drei Kanäle für Music, Ambience und Combat

- **Combat Mode** - friert Musik/Ambience ein, blendet sie aus und stellt Zeitstempel danach wieder her

- **Scene Deck** - komplette Soundscapes aus Music, Ambience, Combat und aktivem SFX-Board speichern

- **SFX-Boards** - zehn Slots pro Board, Hotkeys `1` bis `0`, eigene Icons und Loop-Optionen

- **Bibliothek** - Dateien oder ganze Ordner importieren, suchen, filtern und Kanälen zuweisen

- **Portable Presets** - JSON-Import/-Export für Bibliotheken und Soundboards

- **Einheitliche Navigation** - kompakte BoltBerry-App-Chrome mit Wordmark, Kontext-Breadcrumb und separater Aktionsleiste

Gebaut mit Electron, React, TypeScript, Vite und Zustand. Läuft auf macOS,

Windows und Linux.

### Aktueller Release

Aktuelle Version: **0.1.15**

- [Neueste Release herunterladen](https://github.com/RollBerryStudios/BardBerry/releases/latest)

- [Alle Releases anzeigen](https://github.com/RollBerryStudios/BardBerry/releases)

- Direkter Tag: [v0.1.15](https://github.com/RollBerryStudios/BardBerry/releases/tag/v0.1.15)

| Plattform | Artefakt in der Release |

|---|---|

| Windows x64 | `BardBerry.Setup.0.1.15.exe` |

| Linux x64 | `BardBerry-0.1.15.AppImage`, `bardberry_0.1.15_amd64.deb` |

| macOS x64 | `BardBerry-0.1.15.dmg`, `BardBerry-0.1.15-mac.zip` |

| macOS Apple Silicon | `BardBerry-0.1.15-arm64.dmg`, `BardBerry-0.1.15-arm64-mac.zip` |

### Features

| Kategorie | Funktion |

|---|---|

| **Live Mixer** | Drei Kanäle: Music, Ambience und Combat mit Play/Pause, Stop, Loop, Seek und separater Lautstärke |

| **Master Control** | Globale Master-Lautstärke plus separate SFX-Lautstärke |

| **Combat Mode** | Music und Ambience werden pausiert bzw. heruntergeblendet; beim Beenden werden Positionen und Lautstärken wiederhergestellt |

| **Scene Deck** | Aktuelle Music-, Ambience-, Combat- und Board-Auswahl als wiederverwendbare Szene speichern, benennen, beschreiben und wieder anwenden |

| **Themen & Tracks** | Import einzelner Audiodateien oder rekursiver Ordner-Import |

| **Themen** | Tracks nach Spielsituationen wie Stadt, Taverne, Dungeon oder Mystisch sortieren; Ordnerimporte werden automatisch als Thema uebernommen |

| **Channel Assignment** | Tracks per Chip Music, Ambience oder Combat zuweisen; Rechtsklick spielt direkt auf dem jeweiligen Kanal |

| **SFX Boards** | Mehrere Boards mit jeweils zehn Slots für schnelle Sounds und Loops |

| **Hotkeys** | SFX-Slots direkt über `1` bis `9` und `0` triggern |

| **Slot Editor** | Titel, Emoji, eigenes Icon, Sound-Datei, Lautstärke und Loop pro Slot |

| **Local Assets** | Importierte Audios und Icons werden in den lokalen BardBerry-App-Daten abgelegt |

| **Import/Export** | Bibliothek inklusive Boards als JSON exportieren und wieder importieren |

| **Offline Betrieb** | Keine Server, keine Accounts, keine Telemetrie, keine Internetverbindung erforderlich |

| **App-Chrome** | Kompakte BoltBerry-inspirierte Titelleiste mit einheitlicher Navigation und DPI-sicherem Fensterkontroll-Abstand |

### Bedienung

1. **Audio importieren** - lade einzelne Dateien oder ganze Ordner in die Bibliothek und filtere sie nach Thema.

2. **Themen pflegen** - erstelle eigene Spielsituationen wie Stadt, Taverne oder Dungeon und weise Tracks direkt in der Liste zu.

3. **Kanäle füllen** - weise Tracks Music, Ambience oder Combat zu und steuere Lautstärke, Loop, Play/Pause und Seek pro Kanal.

4. **Szenen speichern** - sichere komplette Soundscapes aus Kanälen und aktivem SFX-Board im Scene Deck.

5. **SFX nutzen** - belege Board-Slots mit Sounds, Icons und Loop-Optionen; Slots lassen sich per Mausklick oder `1` bis `0` auslösen.

6. **Shortcuts nachschlagen** - öffne die Hilfe über den Info-Button, `?` oder `F1`; `Escape` schließt Hilfe, Einstellungen und Editoren.

### Unterstützte Dateien

| Typ | Formate |

|---|---|

| Audio | `.mp3`, `.ogg`, `.wav`, `.m4a` |

| Slot-Icons | `.png`, `.jpg`, `.jpeg`, `.webp` |

| Bibliothek | `.json` |

### Schnellstart

**Voraussetzungen:** Node.js 20+ und npm 10+

```bash

git clone https://github.com/RollBerryStudios/BardBerry.git

cd BardBerry

npm install

npm run dev

```

### Builds erstellen

```bash

npm run build      # TypeScript + Preload + Renderer kompilieren

npm run pack       # Entpacktes App-Verzeichnis für die aktuelle Plattform

npm run dist       # Installer/Distributionspakete für die aktuelle Plattform

```

Die Build-Konfiguration liegt in `electron-builder.yml`.

| Plattform | Ziel |

|---|---|

| macOS | `.dmg` und `.zip` für x64/arm64 |

| Windows | NSIS Installer für x64 |

| Linux | `.AppImage` und `.deb` für x64 |

> Hinweis: Das Repository ist für lokale, unsigned Builds vorbereitet.

> Für notarized macOS-Releases oder signierte Windows-Installer müssen

> eigene Zertifikate und CI-Secrets konfiguriert werden.

Fertige Builds liegen als [GitHub Releases](https://github.com/RollBerryStudios/BardBerry/releases)

bereit. Die Release-Seite enthält Windows-, Linux- und macOS-Artefakte.

### Qualitätssicherung

```bash

npm run test:e2e          # Build + Playwright/Electron E2E-Suite

npm run test:e2e:headed   # Gleiche Suite mit sichtbarem Fenster

npm run test:e2e:update   # Screenshot-Baselines nach absichtlichen UI-Änderungen aktualisieren

```

Die E2E-Suite startet BardBerry mit isolierten Testdaten, erzeugt lokale

WAV-/PNG-Fixtures, prüft Mixer-, Scene-Deck-, Bibliotheks-, Combat-, SFX-,

Hotkey- und Persistenz-Flows und validiert Desktop- sowie responsive

Screenshots.

### Lokale Daten

BardBerry speichert seine Daten im Betriebssystem-AppData-Verzeichnis der

Electron-App. Dort liegen:

- `data/bardberry-library.json` - Bibliothek, Themen, Szenen, Boards, Lautstärken und Zuweisungen

- `assets/audio/` - importierte Audiodateien

- `assets/icons/` - importierte Slot-Icons

Die App validiert Dateitypen anhand von Erweiterung und Magic Bytes und

beschränkt einzelne Assets auf 300 MB.

### Projektstruktur

```text

src/

  main/          Electron Main-Prozess, IPC, Dateidialoge, Asset-Import

  preload/       Sichere Context Bridge für die Renderer-API

  renderer/      React-App, Mixer UI, Track Library, SFX Boards

resources/

  logo.png       BardBerry Logo

  icon.png       PNG-App-Icon

  icon.icns      macOS-App-Icon

scripts/

  build-preload.mjs

```

### Tech-Stack

| Technologie | Verwendung |

|---|---|

| Electron 41 | Desktop-Shell und native Dialoge |

| React 18 | Benutzeroberfläche |

| TypeScript 5.9 | Typisierte App-Logik |

| Vite 6 | Renderer-Bundling |

| Zustand 5 | Audio- und UI-State |

| HTMLAudioElement | Lokale Wiedergabe von Tracks und SFX |

| electron-builder | Packaging für macOS, Windows und Linux |

### Mitwirken

Issues, Feature-Ideen und Pull Requests sind willkommen. Bitte halte Änderungen

fokussiert, teste lokale Builds vor dem PR und beschreibe kurz, welche

Audio-/UI-Flows betroffen sind.

### Lizenz

App-Code: [MIT](LICENSE) (c) 2026 RollBerry Studios.

---

## English

BardBerry is a **free, open-source desktop app for local tabletop music,

ambience, and sound effects**. It is built for game masters who want a focused

audio cockpit for virtual or hybrid sessions without cloud accounts, browser

tabs, subscriptions, or streaming dependencies.

The app takes the audio workflow from BoltBerry and turns it into a standalone

Electron project: a dedicated live mixer for music, ambience, combat music, and

fast SFX boards.

- **Local-first** - your audio files and boards stay on your machine

- **Live mixer** - three channels for Music, Ambience, and Combat

- **Combat mode** - freezes Music/Ambience, fades them down, then restores timestamps afterwards

- **Scene Deck** - save complete soundscapes from Music, Ambience, Combat, and the active SFX board

- **SFX boards** - ten slots per board, hotkeys `1` to `0`, custom icons, and loop options

- **Library workflow** - import files or folders, search, filter, and assign tracks to channels

- **Portable presets** - JSON import/export for libraries and soundboards

- **Unified navigation** - compact BoltBerry-style app chrome with wordmark, context breadcrumb, and separate action bar

Built with Electron, React, TypeScript, Vite, and Zustand. Runs on macOS,

Windows, and Linux.

### Current Release

Current version: **0.1.15**

- [Download the latest release](https://github.com/RollBerryStudios/BardBerry/releases/latest)

- [View all releases](https://github.com/RollBerryStudios/BardBerry/releases)

- Direct tag: [v0.1.15](https://github.com/RollBerryStudios/BardBerry/releases/tag/v0.1.15)

| Platform | Release artifact |

|---|---|

| Windows x64 | `BardBerry.Setup.0.1.15.exe` |

| Linux x64 | `BardBerry-0.1.15.AppImage`, `bardberry_0.1.15_amd64.deb` |

| macOS x64 | `BardBerry-0.1.15.dmg`, `BardBerry-0.1.15-mac.zip` |

| macOS Apple Silicon | `BardBerry-0.1.15-arm64.dmg`, `BardBerry-0.1.15-arm64-mac.zip` |

### Features

| Category | What you get |

|---|---|

| **Live Mixer** | Three channels: Music, Ambience, and Combat with Play/Pause, Stop, Loop, Seek, and per-channel volume |

| **Master Control** | Global master volume plus separate SFX volume |

| **Combat Mode** | Music and Ambience are paused/faded down; when combat ends, positions and volumes are restored |

| **Scene Deck** | Save, name, describe, and re-apply the current Music, Ambience, Combat, and board selection as reusable scenes |

| **Themes & Tracks** | Import individual audio files or recursively import whole folders |

| **Themes** | Sort tracks by table situations like city, tavern, dungeon, or mystic; folder imports are automatically kept as themes |

| **Channel Assignment** | Assign tracks to Music, Ambience, or Combat; right-click a chip to play directly on that channel |

| **SFX Boards** | Multiple boards with ten slots each for quick sounds and loops |

| **Hotkeys** | Trigger SFX slots from the keyboard with `1` to `9` and `0` |

| **Slot Editor** | Configure title, emoji, custom icon, sound file, volume, and loop per slot |

| **Local Assets** | Imported audio and icons are copied into BardBerry's local app data folder |

| **Import/Export** | Export and import your complete library and boards as JSON |

| **Offline Use** | No servers, no accounts, no telemetry, no internet connection required |

| **App Chrome** | Compact BoltBerry-inspired title bar with unified navigation and DPI-safe native-control spacing |

### Usage

1. **Import audio** - add individual files or whole folders to the library and filter by theme.

2. **Shape themes** - create table situations like city, tavern, or dungeon and assign tracks directly in the list.

3. **Fill channels** - assign tracks to Music, Ambience, or Combat, then control volume, loop, play/pause, and seek per channel.

4. **Save scenes** - store complete soundscapes from channels and the active SFX board in the Scene Deck.

5. **Use SFX** - configure board slots with sounds, icons, and loop options; trigger slots by click or with `1` to `0`.

6. **Check shortcuts** - open help with the info button, `?`, or `F1`; `Escape` closes help, settings, and editors.

### Supported Files

| Type | Formats |

|---|---|

| Audio | `.mp3`, `.ogg`, `.wav`, `.m4a` |

| Slot icons | `.png`, `.jpg`, `.jpeg`, `.webp` |

| Library | `.json` |

### Getting Started

**Prerequisites:** Node.js 20+ and npm 10+

```bash

git clone https://github.com/RollBerryStudios/BardBerry.git

cd BardBerry

npm install

npm run dev

```

### Building

```bash

npm run build      # Compile TypeScript, preload, and renderer

npm run pack       # Build an unpacked app directory for the current platform

npm run dist       # Build distributable packages for the current platform

```

Packaging is configured in `electron-builder.yml`.

| Platform | Target |

|---|---|

| macOS | `.dmg` and `.zip` for x64/arm64 |

| Windows | NSIS installer for x64 |

| Linux | `.AppImage` and `.deb` for x64 |

> Note: The repository is configured for local unsigned builds. Notarized macOS

> releases or signed Windows installers require your own certificates and CI

> secrets.

Ready-to-use builds are published as [GitHub Releases](https://github.com/RollBerryStudios/BardBerry/releases).

The release page contains Windows, Linux, and macOS artifacts.

### Quality Assurance

```bash

npm run test:e2e          # Build + Playwright/Electron E2E suite

npm run test:e2e:headed   # Same suite with a visible window

npm run test:e2e:update   # Refresh screenshot baselines after intentional UI changes

```

The E2E suite launches BardBerry with isolated test data, generates local

WAV/PNG fixtures, covers mixer, Scene Deck, library, combat, SFX, hotkey, and

persistence flows, and validates desktop plus responsive screenshots.

### Local Data

BardBerry stores its data in the operating system's Electron app data folder:

- `data/bardberry-library.json` - library, themes, scenes, boards, volumes, and assignments

- `assets/audio/` - imported audio files

- `assets/icons/` - imported slot icons

The app validates imported files by extension and magic bytes and limits single

assets to 300 MB.

### Project Structure

```text

src/

  main/          Electron main process, IPC, file dialogs, asset import

  preload/       Safe context bridge for the renderer API

  renderer/      React app, mixer UI, track library, SFX boards

resources/

  logo.png       BardBerry logo

  icon.png       PNG app icon

  icon.icns      macOS app icon

scripts/

  build-preload.mjs

```

### Tech Stack

| Technology | Usage |

|---|---|

| Electron 41 | Desktop shell and native dialogs |

| React 18 | User interface |

| TypeScript 5.9 | Typed app logic |

| Vite 6 | Renderer bundling |

| Zustand 5 | Audio and UI state |

| HTMLAudioElement | Local track and SFX playback |

| electron-builder | Packaging for macOS, Windows, and Linux |

### Contributing

Issues, feature ideas, and pull requests are welcome. Please keep changes

focused, test local builds before opening a PR, and describe which audio or UI

flows are affected.

### License

App code: [MIT](LICENSE) (c) 2026 RollBerry Studios.