Skip to main content

Structure

meetings/
├── bin/
│   ├── meeting-start        # starts recording + live transcription
│   ├── meeting-stop         # stops recording, asks for meeting name, renames files
│   ├── meeting-follow       # follow transcript while it is being written
│   └── summarize-meeting    # create post-meeting summaries (planned, not yet realized)
│
├── lib/
│   ├── paths.sh             # creates session dirs + defines file paths
│   └── whisper.sh           # whisper.cpp binary, model, ASR parameters
│
└── recordings/
    └── 2025-03-24_1930/     # session directory (created on meeting-start)
        ├── audio.wav        # raw system audio recording
        ├── transcript.txt  # live transcript (grows during meeting)
        ├── meta.env        # session metadata (PIDs, language, timestamps)
        ├── 2025-03-24T1930_project-sync_transcript.txt # the actual transcript
        ├── 2025-03-24T1930_project-sync_audio.wav # (see data protection discussion)
        └── summary.md      # created by summarize-meeting (planned, not yet realized)

Description of Paths and Scripts

Paths

Path: meetings/bin/

  • Executable scripts. 

Path: meetings/lib/

  • Scripts to be used by the executable scripts. 

Path: meetings/recordings/

  • Subdirectories (ISO timestamp format) containing:
    • Audio files (to be deleted after the transcript has been written)
    • transcript.txt (renamed and timestamped after the meeting's end by the meeting-stop script)
    • meta.env (Meeting information)
      • PIDs
      • language used
      • the meeting's timestamps
    • summary.md (meeting summary in Markdown format)

Scripts (current architecture)

TranscriptOMatic is implemented as a small set of composable shell scripts. Each script has a clearly defined responsibility within the session lifecycle. No script relies on implicit system state or hard-coded audio devices.

Library scripts (meetings/lib/)

meetings/lib/paths.sh

Responsible for session creation and path management.

On invocation, it:

  • creates a new session directory
~/meetings/recordings/<ISO_TIMESTAMP>/

  • defines canonical file locations:

    • audio.wav

    • transcript.txt

    • meta.env

  • provides these paths to all other scripts

This script is the only place where session directories are created.

meetings/lib/whisper.sh

Defines the speech recognition backend configuration.

It contains:

  • the path to the local whisper.cpp installation

  • model selection (language-specific vs. multilingual)

  • streaming parameters

  • threading configuration suitable for a Raspberry Pi–class system

The setup is explicitly optimized for live transcription using whisper-stream, not for batch processing.

No audio devices are referenced here.

Executable scripts (meetings/bin/)

meeting-start

Starts a new live transcription session.

Responsibilities

  1. Session initialization
    • creates a new session directory via paths.sh
    • writes the active session path to ~/meetings/recordings/.current

  2. Audio graph setup (PipeWire)

    • ensures a persistent null sink (discord_sink)
    • routes Discord audio into that sink
    • exposes the sink monitor as a virtual microphone (whisper_mic)
  3. Processing
    • records audio from whisper_mic via ffmpeg
    • performs (almost) live transcription using whisper-stream
    • appends output to transcript.txt
  4. State tracking
    • writes all relevant runtime information (PIDs, module IDs, paths) to meta.env

Usage

meeting-start --en    # force English

Planned, not yet realized:

meeting-start --de    # force German (planned, not yet realized)
meeting-start --auto  # auto-detect language (planned, not yet realized)

meeting-start is self-contained: it does not require any pre-existing audio configuration and can be run after a reboot.

meeting-follow

Passively follows the live transcript of the currently active session.

Behaviour

  • waits for the presence of ~/meetings/recordings/.current
  • reads the active session path from that file
  • waits until transcript.txt exists
  • follows the transcript in real time

This allows meeting-follow to be started:

  • before meeting-start
  • over SSH
  • in a shared terminal window

It will never attach to archived sessions.

Usage

meeting-follow # stop with ctrl+c

 

meeting-stop

Stops the active transcription session and finalises all session files.

Responsibilities

  1. Process teardown kills the ffmpegFFmpeg and whisper-stream processes via their stored PIDs
  2. State cleanupclean-up removes ~/meetings/recordings/.current unloads the whisper_mic remap-source module from PipeWire
  3. File finalisation prompts for a meeting name and slugifies it
      • renames transcript.txt and audio.wav to timestamped, named files (e.g. 2025-03-24T1930_project-sync_transcript.txt)

 

Back to top