Recording Laptop Setup

The ingest agent runs on the recording laptop, transcribes audio on-device with faster-whisper, and streams finalized captions to the server. Audio never leaves the machine — only text is sent.

Python 3.10+Windows / macOS / LinuxNo GPU neededCPU int8 · ~1 GB RAMPoppins font bundled

Choose your setup path:

Setup progress0 / 7 steps

⚡ Quick Setup Script

Copy and run this in your terminal to complete steps 1–2 in one go.

cd dot-pulse/agent

# 1. Create & activate virtual environment
python -m venv .venv
.venv\Scripts\activate

# 2. Install dependencies (launcher + ASR + GUI)
pip install -r requirements_launcher.txt

echo Done! Run:  python launcher.py

Navigate to the agent folder

Open a terminal and navigate to the agent/ subfolder of the dot-pulse project.

cd dot-pulse/agent

Create virtual environment & install dependencies

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements_launcher.txt

requirements_launcher.txt includes the ASR engine, GUI framework, audio libraries, and PyInstaller. Only needed once — on later runs just activate the venv.

CLI-only? Use requirements.txt instead — it skips customtkinter and pyinstaller for a lighter install.

Run the desktop launcher

Make sure the venv is active, then:

python launcher.py

The launcher opens with three tabs: Settings, Recording, and Setup Guide (this page in desktop form). Poppins font loads automatically.

Configure server URL and token (Settings tab)

In the Settings tab, enter:

Server URLhttps://pulse.dtsmanagement.siteThe dot-pulse server address

Ingest tokenask the organiserShared secret — must match server INGEST_TOKEN

ModelsmallWhisper model size; small is the best speed/accuracy balance

Deviceauto-detectedLeave blank to use the system default mic

Fetch config from server: If the organiser has already set up the event on the server, click Fetch Config in Settings — it pulls the server URL, token, and model choice automatically. No manual .env editing needed.

Choose audio source and start recording (Recording tab)

Switch to the Recording tab.

Mic Mode (default)

Select the microphone or mixer line-in from the device dropdown, then click Start. For best results, use the venue mixer's line-out rather than a room mic.

Meeting Mode new

Toggle Mic → Meeting to capture system audio (loopback) instead — useful for online meetings, screen shares, or any audio playing through speakers. The launcher auto-detects virtual audio devices (Stereo Mix, VB-Cable, Voicemeeter, BlackHole).

Windows: Enable "Stereo Mix" in Sound settings → Recording devices (right-click the speaker icon → Sounds → Recording tab → right-click empty area → Show Disabled Devices). If you use Google Meet / Zoom, VB-Cable gives cleaner results.

After clicking Start, captions appear at https://pulse.dtsmanagement.site/live as soon as the first utterance is finalised.

Advanced: Panel Discussion Mode

Register panelists for hotkey speaker switching

When multiple speakers share one mic, add their names so you can tag who is speaking with a number key.

In the Settings tab, enter comma-separated names in Speakers (e.g. Alice,Bob,Carol,David). On the Recording tab, press 1–4 to switch the active speaker before they start talking.

Dry run — test without audio

Use the built-in simulator to exercise the full pipeline without a microphone. Useful for rehearsals and verifying the server connection.

First, in the moderator panel, set panelists to Alice, Bob, Carol, David and click Start Panel Mode. Then:

python simulate_panel.py --fast

Watch /live update with captions and the moderator panel fill with AI-generated key points and follow-up question hints.

Build the pre-compiled executable

Creates dist/DotPulseLauncher.exe— a single portable file that includes Python, faster-whisper, the GUI, and the Poppins fonts. Hand this to event operators who don't have Python installed.

cd dot-pulse/agent
.venv\Scripts\activate
build.bat
# Output: dist\DotPulseLauncher.exe

Debug build: Run build.bat --debug to get a version with a visible console window — useful for diagnosing audio device issues on the event laptop.

All environment variables

Set in agent/.env or injected via --fetch-config. The launcher GUI exposes the most common ones in its Settings tab.

PULSE_SERVER_URLURL of the dot-pulse serverhttps://pulse.dtsmanagement.site

PULSE_INGEST_TOKENShared secret — must match server's INGEST_TOKENask organiser

PULSE_MODELfaster-whisper model size (tiny/base/small/medium/large-v3)small

PULSE_LANGForce language ("en") or blank for auto-detect(blank)

PULSE_DEVICEAudio input device index from --list or launcher Settings(auto)

PULSE_SPEAKERDefault speaker label (single-speaker mode)Speaker

PULSE_SPEAKERSComma-separated names for panel / hotkey mode(blank)

PULSE_CPU_THREADSCPU threads for faster-whisper4

PULSE_SILENCE_TAIL_MSMilliseconds of silence before finalising an utterance500

PULSE_MAX_UTTERANCE_SHard cap on utterance length in seconds8

PULSE_NO_SPEECH_THRESHWhisper no-speech confidence threshold (0–1)0.5

PULSE_AVG_LOGPROB_THRESHWhisper average log-prob threshold (negative; lower = stricter)-0.8

PULSE_DIARIZE_THRESHOLDVoice-change detection sensitivity (0–1; higher = less sensitive)0.82

Model size reference

tiny~75 MB~2× real-timeBasic accuracy; fine for clean audio with simple vocab

base~145 MB~5× real-timeNoticeably better; still very fast

small ★~480 MB~8× real-timeRecommended — handles English + Kinyarwanda mix at real-time on modern laptops

medium~1.5 GB~5× real-timeHigher accuracy; ~3× slower than small on CPU

large-v3~3 GB~2× real-timeBest accuracy; requires ~6 GB RAM; use for post-processing only