meeting-minutes

Meeting Minutes Generator

Generate detailed meeting minutes from a video recording, cross-referenced against project PRDs and user stories.

Inputs

• video_file: $ARGUMENTS.video_file — the recording to transcribe
• docs_dirs: $ARGUMENTS.docs_dirs — space-separated list of docs directories to study for project context

Step 1: Transcribe the recording

Use mlx-whisper with the chunked approach to avoid hallucination on long audio files. Whisper models hallucinate (repeating "So.", "Yeah.", etc.) when processing files longer than ~20 minutes in a single pass.

Setup (if needed)

python3 -m venv /tmp/whisper_env
source /tmp/whisper_env/bin/activate
pip install mlx-whisper

Split into 10-minute chunks

mkdir -p /tmp/whisper_chunks /tmp/whisper_chunks_out
DURATION=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "<video_file>")
NUM_CHUNKS=$(python3 -c "import math; print(math.ceil($DURATION / 600))")
for i in $(seq 0 $((NUM_CHUNKS - 1))); do
  ffmpeg -y -i "<video_file>" -ss $((i * 600)) -t 600 -c copy "/tmp/whisper_chunks/chunk_${i}.mp4" 2>/dev/null
done

Transcribe each chunk

source /tmp/whisper_env/bin/activate
for f in /tmp/whisper_chunks/chunk_*.mp4; do
  mlx_whisper "$f" --model mlx-community/whisper-medium-mlx --output-format srt --output-dir /tmp/whisper_chunks_out
done

Stitch into a single SRT

Write a Python script to stitch the chunk SRTs into one file. For each chunk, offset all timestamps by chunk_index * 600000 milliseconds and renumber sequence IDs sequentially. Use this script:

import re

def parse_timestamp(ts):
    h, m, rest = ts.split(':')
    s, ms = rest.split(',')
    return int(h)*3600000 + int(m)*60000 + int(s)*1000 + int(ms)

def format_timestamp(ms):
    h = ms // 3600000; ms %= 3600000
    m = ms // 60000; ms %= 60000
    s = ms // 1000; ms %= 1000
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

seq = 1
entries = []
for i in range(NUM_CHUNKS):
    offset_ms = i * 600000
    with open(f"/tmp/whisper_chunks_out/chunk_{i}.srt") as f:
        content = f.read()
    for match in re.finditer(r'(\d+)\n(\d{2}:\d{2}:\d{2},\d{3}) --> (\d{2}:\d{2}:\d{2},\d{3})\n(.*?)(?=\n\n|\n*$)', content, re.DOTALL):
        text = match.group(4).strip()
        if text:
            start = format_timestamp(parse_timestamp(match.group(2)) + offset_ms)
            end = format_timestamp(parse_timestamp(match.group(3)) + offset_ms)
            entries.append(f"{seq}\n{start} --> {end}\n{text}\n")
            seq += 1

with open("<output_srt>", 'w') as f:
    f.write("\n".join(entries))

Replace the original .srt file with the stitched version (keep a .bak backup of the original if one existed).

Step 2: Study project context

Read the PRDs and user stories from the specified docs directories to understand what the project is building. For each directory provided:

1. List all files in prds/ and user-stories/ subdirectories
2. Read each PRD and user story document using subagents for parallel processing
3. Build a mental model of the project's features, entities, terminology, and current status

This context is essential for cross-referencing discussion topics in the meeting with specific PRDs and user stories.

Step 3: Generate meeting minutes

Read the stitched SRT transcript and produce detailed meeting minutes. The minutes should include:

Structure

1. Header: Date, recording filename, attendees (identified from the transcript), duration
2. Summary table: Key items discussed with type, owner, and status
3. Detailed discussion sections: For each topic discussed:
   • Section heading with timestamp range
   • Discussion: What was said, by whom (where identifiable), key points
   • Decision (if any): What was agreed
   • Timestamps: Key moments to reference in the recording
   • PRD/US Impact: Which PRDs or user stories are affected, and how
4. New feature requirements: Any new features identified that aren't in existing PRDs
5. Action items table: All actions with owner, timestamp, and PRD reference
6. Relationship to previous meetings: If prior meeting notes exist in the same directory, link and reference them

Guidelines

• Use HH:MM:SS timestamps throughout so readers can find the moment in the recording
• Flag any sections where the transcript quality is poor (hallucination blocks, unclear audio) and recommend watching the recording
• Be specific about PRD references — cite the PRD number and section where relevant
• Capture the nuance of discussions — don't just summarise decisions, capture the reasoning and any dissent
• Note deferred items and who owns the follow-up
• Write the minutes to the appropriate docs/meetings/ directory with filename format YYYY-MM-DD-<meeting-description>.md

Transcript quality notes

Even with chunking, some short hallucination blocks may remain (repeated "Yeah.", "So.", etc. for 1-3 minutes). Flag these in the output and note the timestamp ranges where the recording should be watched directly.