Setup Documentation

Requirements

Before you begin, make sure you have the following:

• macOS 12 Monterey or laterWindows support is planned for a future release
• Node.js 18 or laterDownload from nodejs.org
• Azure account with Cognitive ServicesFree tier is sufficient for most events
• Audio interface or microphoneAny device recognized by macOS will work

Installation

Download the latest release and install the dependencies:

1. Download

Download the zip from GitHub and unzip it to your Applications folder or anywhere you prefer:

# Download and unzip
curl -L https://github.com/catmadu-1234/multi-language-captions/archive/refs/heads/main.zip -o captions.zip
unzip captions.zip -d ~/multi-language-captions
cd ~/multi-language-captions/multi-language-captions-main

2. Install dependencies

npm install

3. Verify the install

node --version   # should print v18.0.0 or higher
npm --version    # should print 9.0.0 or higher

Azure Speech Setup

The app uses Azure Cognitive Services for real-time speech recognition. You need a Speech resource key and region.

Create a Speech resource

1. 1Go to portal.azure.com and sign in.
2. 2Click Create a resource and search for Speech.
3. 3Select your subscription, create a new resource group, choose a region close to your event, and select the Free F0 pricing tier.
4. 4Once deployed, go to Keys and Endpoint in the resource menu. Copy KEY 1 and your Location/Region.

Enter your credentials

On first launch, the app will prompt you for your credentials. You can also set them via environment variables:

# Create a .env file in the project root
AZURE_SPEECH_KEY=your_key_here
AZURE_SPEECH_REGION=eastus   # replace with your region

Azure Translator Setup (optional)

If you want to add a third language in addition to English and French, you can enable the Azure Translator service for on-the-fly translation of the transcribed text.

Create a Translator resource

Follow the same steps as for the Speech resource, but search for Translator instead. Then add to your .env:

AZURE_TRANSLATOR_KEY=your_translator_key
AZURE_TRANSLATOR_REGION=eastus
AZURE_TRANSLATOR_ENDPOINT=https://api.cognitive.microsofttranslator.com/

Without this, the app runs in two-language mode (EN + FR) using Azure Speech's native multilingual recognition — no additional configuration needed.

Running the App

Start the caption server

npm start

This starts both the Electron desktop app and the WebSocket server. The app window will open and display your audio device selector.

Select your audio device

From the device dropdown, select the microphone or audio interface input you want to transcribe. Click Start Captioning.

Share the viewer URL

The app displays a URL like:

http://your-local-ip:3000/viewer

For public events, use the hosted viewer at:

https://multi-language-captions.littlebigideas.ca/viewer

Anyone with the link can open it in any browser — desktop or mobile — and see captions update in real time.

Troubleshooting