acCompaniment

acCompaniment is a professional soundboard application built with Electron, designed for live performance, broadcasting, and advanced audio cue management. It offers robust control over audio playback, extensive customization options, and integration capabilities with Bitfocus Companion.

Features

• Cue Management:
  • Create, organize, and trigger audio cues.
  • Support for single audio files and complex playlists within a single cue.
  • Individual cue properties: volume, fade in/out times, looping, retrigger behavior.
  • Playlist-specific properties: shuffle, repeat one item, play modes (play through, stop after item).
  • Drag-and-drop interface for adding audio files.
  • Automatic discovery of audio file durations.
• Audio Playback Engine:
  • Powered by Howler.js for reliable and performant audio handling.
  • Visual waveform display for trimming audio start/end points.
  • Precise control over playback: play, pause, stop, stop all, fade out and stop.
• Configuration:
  • Global application settings for default cue behaviors, audio output device selection.
  • Workspace management: Save and load entire cue layouts.
  • Option to automatically load the last opened workspace.
• Integration & Control:
  • Bitfocus Companion: Seamless integration via a dedicated Companion module (https://github.com/mko1989/companion-module-highpass-accompaniment) for remote triggering of cues and receiving feedback (cue status, playback times).
  • HTTP Remote Control: Built-in web interface for remote control via any web browser.
• User Interface:
  • Clear and intuitive grid-based layout for cue buttons.
  • Real-time display of cue status (idle, playing, paused, cued next).
  • Display of current playback time, total duration, and remaining time on cue buttons.
  • Dedicated sidebars for cue properties and application configuration.
  • Dark theme optimized for live performance environments.
• Easter Egg:
  • A fun, hidden 16-bit style game, "Happy Pig!" accessible through Ctrl+Alt+P.

System Requirements

• Operating System: Windows 10/11, macOS 10.15+
• Memory: 4GB RAM minimum, 8GB recommended
• Storage: 200MB for application, additional space for audio files
• Audio: Compatible audio output device

Getting Started

Prerequisites

• Node.js 18+ and npm (for development builds)

Installation & Running

For End Users

Download the latest release from the Releases page for your operating system.

For Developers

1. Clone the repository:

   git clone <repository-url>
   cd acCompaniment

2. Install dependencies:

   npm install

3. Run the application:

   npm start

Usage

1. Adding Cues: Drag and drop audio files onto the main grid area to create cues
2. Show/Edit Mode: Use the show mode button in top right corrner to change show state (lights or pencile icon)
3. Playing Cues: Click on any cue button to start playback
4. Edit Mode: Hold Shift while clicking to edit cue properties
5. Stop All: Use the red "Don't Panic" button to stop all playing cues
6. Ducking: One cue is a ducking trigger, meaning when this cue is played, all the cues with ducking enable will be ducked with the set level.
7. Crossfade: When enabled only one cue is able to play and clicking a new one will trigger a crossfade between them.
8. Waveform editing: In single cue's properties users can set in and out points on the wave form to cut out unnecessary parts.
9. Remote Control: Enable HTTP remote control in settings to access the web interface

Main workspace (red in show mode, gray in edit mode)

Buttons

App config

Single cue properties

Playlist cue properties

Add multiple files modal

Cue's settings on buttons

Top left: cue's state. Next: looping if enabled. Middle: retrigger behaviour. Top right: ducking

Retrigger behaviour: Fade and Stop

Retrigger behaviour: Restart

Retrigger behaviour: Play new instance

Retrigger behaviour: Do nothing

Retrigger behaviour: Stop

Retrigger behaviour: Toggle Play/Pause

Retrigger behaviour: Play next playlist item

Retrigger behaviour: Replay current item

HTTP Web Remote

Development

The application is built using Electron. Key technologies include:

• Electron: For building the cross-platform desktop application.
• HTML, CSS, JavaScript: For the user interface and core logic.
• Howler.js: For audio playback.
• Node.js: For main process logic and system interactions.
• WebSockets: For communication with the Bitfocus Companion module.

Project Structure

The project follows a standard Electron structure:

• main.js - Main Electron process
• src/main/ - Main process modules
• src/renderer/ - Renderer process (UI) modules
• assets/ - Application icons and resources

Available Scripts

• npm start - Start the Electron application in development mode
• npm run pack - Package the application (without creating installers)
• npm run dist - Build distributables for all platforms
• npm run dist:mac - Build macOS distributable
• npm run dist:win - Build Windows distributable

Building for Distribution

To create distributable packages:

# Install dependencies
npm install

# Build for all platforms
npm run dist

# Or build for specific platform
npm run dist:mac    # macOS
npm run dist:win    # Windows

Built packages will be available in the dist/ directory.

Companion Module Integration

To control acCompaniment from Bitfocus Companion:

1. Ensure acCompaniment is running. The internal WebSocket server will start automatically.
2. Install the companion-module-highpass-accompaniment module into your Bitfocus Companion setup.
3. Add an instance of the "acCompaniment" module in Companion.
4. Configure the IP address and port if necessary (defaults usually work if Companion and acCompaniment are on the same machine).
5. Actions, variables, and feedbacks will become available in Companion to control and monitor cues.

Getting Help

If you encounter issues not covered here, please check the Issues page or create a new issue with:

• Your operating system and version
• Steps to reproduce the problem
• Any error messages

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

If you like it consider buying me a coffee

License

This project is licensed under the MIT License - see the LICENSE file for details.