aula-whisper-live

Live PT→EN subtitles for university classes, plus post-class transcription and study-notes generation. Uses the Groq API (Whisper for ASR, Llama for translation and summarisation).

Designed for the case of a Portuguese-speaking lecturer who needs English subtitles displayed on a second screen for international students.

Status: snapshot, not actively maintained. Used in production by the author throughout 2026; works as of May 2026. Tested only on Ubuntu 24.04.

What it does

• Live transcription of microphone audio (Portuguese → text) via Groq Whisper, with WebRTC VAD to detect utterance boundaries.
• Live translation PT → EN via Groq Llama, watching the transcript file and producing an EN file in parallel.
• Subtitle viewer (Tk window, no extra dependencies) that follows the EN file and displays the latest line(s). Drop it on the projector output.
• Recording to WAV in parallel for backup / post-processing.
• Post-class transcription of the recording with a larger / non-realtime pipeline (also Groq Whisper, chunked to fit the 25 MB API limit).
• Study notes (sebenta) and glossary generation from the cleaned transcript via Groq Llama 70B.

Why Groq and not local Whisper

Earlier versions used whisper.cpp locally. That worked but the latency on laptop CPUs was too high for live use, and quality on small/medium models was below what you get from Groq's whisper-large-v3-turbo at similar latency. Groq became the practical choice; offline support was dropped.

If you'd rather run everything locally, replace the client.audio.transcriptions.create(...) calls in live_transcribe.py and postprocess_groq.py with a whisper.cpp subprocess call, and the client.chat.completions.create(...) in translator.py and make_sebenta.py with a local LLM (e.g. llama.cpp, ollama).

Requirements

• Python 3.10+

• ffmpeg (for start_recording.sh)

• A Groq API key — sign up at https://console.groq.com (free tier is enough for occasional class use)

• Python packages:

  pip install groq python-dotenv numpy sounddevice webrtcvad

  tkinter is needed by the subtitle viewer; on Ubuntu/Debian: sudo apt install python3-tk.

Setup

git clone <this-repo> aula-whisper-live
cd aula-whisper-live
cp .env.example .env
# edit .env and put your Groq key

Live use during a class

Three terminals (or tmux panes):

A — live transcription (Portuguese):

./start_live.sh

Variants:

WHISPER_MODEL=whisper-large-v3 ./start_live.sh   # higher accuracy, slightly slower
WHISPER_LANG=it                ./start_live.sh   # Italian source

B — translator + subtitle window (English on the projector):

./start_subtitles.sh

The script launches translator.py in the background and opens the viewer. Useful options:

MODE=fullscreen LINES=2 FONT_SIZE=36 ./start_subtitles.sh

Inside the viewer: Esc or q to close. Drag from the thin top bar.

C — backup recording (WAV at 16 kHz mono):

./start_recording.sh

File is named recordings/aula_YYYYMMDD_HHMMSS.wav.

Tip: putting the subtitle window on the projector

In GNOME, set the displays to "Join displays" (extend mode), then drag the viewer onto the projector. MODE=fullscreen makes it cover the projector screen; MODE=bottom (default) is a strip at the bottom. The script accepts --screen-width / --screen-height for cases where Tk picks the wrong screen geometry.

After the class

./postprocess.sh recordings/aula_YYYYMMDD_HHMMSS.wav

Produces a clean transcript at transcripts/aula_pt_<stamp>.txt. Pass -l it (or any other language code) for non-Portuguese recordings.

Generate study notes and a glossary from the transcript:

python3 make_sebenta.py transcripts/aula_pt_<stamp>.txt

Outputs <input>_sebenta.md and <input>_glossario.md.

Files

File	Purpose
live_transcribe.py	Mic → VAD → Groq Whisper → transcript file
translator.py	Watches PT file, writes EN translations via Groq Llama
subtitles_viewer.py	Tk window that follows a transcript file
postprocess_groq.py	Whole-recording transcription, chunked
make_sebenta.py	Structured notes + glossary from a transcript
start_live.sh	Wrapper for live_transcribe.py + log file
start_subtitles.sh	Launches translator + viewer together
start_recording.sh	ffmpeg recorder
postprocess.sh	Wrapper for postprocess_groq.py

Caveats

• Whisper hallucinates on silence. live_transcribe.py drops a small list of known hallucinations (obrigado, legenda por…, etc.) and applies a minimum-RMS gate before sending audio to the API. The viewer also drops obvious garbage. Long-form quality is fine; expect 1–2 weird lines per hour of class.
• Latency from speech end → English subtitle is ~1.5–3 s on Groq, dominated by the round trip. Acceptable for following along, not for word-by-word reading.
• The translator uses a small/fast Llama model and per-line context only — it doesn't remember prior sentences. Good for technical content where consistency matters less than throughput.

Licence

MIT — see LICENSE.