# 🎤 meetings — local audio → transcript → summary + action items

A single-file shell script CLI that transcribes meeting recordings (using GGUF Whisper or Parakeet models), then generates a summary and extracts action items using Ollama. Everything runs 100% locally.

```
audio file ──▶ ffmpeg ──▶ whisper.cpp / parakeet.cpp ──▶ Ollama ──▶ report.md
                    │                    │                      │
              16kHz mono WAV      GGUF transcription      summary + actions
```

## Quick start

```bash
# 1. Clone/download
git clone <this-repo> meetings-cli && cd meetings-cli

# 2. One-time setup (installs whisper.cpp, downloads model, pulls Ollama LLM)
./meetings setup

# 3. Process a meeting recording
./meetings recording.mp3

# 4. Check everything is healthy
./meetings doctor
```

## What it does

| Step | Tool | What happens |
|------|------|--------------|
| 1. Convert | ffmpeg | Any audio → 16kHz mono WAV |
| 2. Transcribe | whisper.cpp or parakeet.cpp | GGUF/GGML model → text transcript |
| 3. Summarize | Ollama | Transcript → structured summary (topic, key points, decisions, open questions) |
| 4. Extract | Ollama | Transcript → numbered action items (who, what, when, priority) |

## Output

For each audio file, a directory is created containing:

```
2026-06-07_1402_team_standup/
├── report.md          # Combined: summary + actions + transcript
├── transcript.txt     # Raw transcription
├── summary.md         # LLM-generated summary
└── action_items.md    # Extracted action items
```

## Requirements

| Dependency | Install | Purpose |
|------------|---------|---------|
| **ffmpeg** | `brew install ffmpeg` | Audio format conversion |
| **whisper.cpp** | `brew install whisper-cpp` | Speech-to-text (GGML models) |
| **Ollama** | [ollama.com](https://ollama.com) | LLM for summarization |
| **jq** | `brew install jq` | JSON parsing for Ollama API |

> `./meetings setup` handles all of this automatically.

## STT engines

### whisper.cpp (default, recommended)
- Battle-tested, many languages, large model ecosystem
- Models from [ggerganov/whisper.cpp](https://huggingface.co/ggerganov/whisper.cpp)
- Install: `brew install whisper-cpp`

| Model | Size | Best for |
|-------|------|----------|
| tiny.en | 75 MB | Quick tests, English |
| base.en | 142 MB | Good balance, English |
| small.en | 466 MB | **Recommended for English** |
| medium.en | 1.5 GB | High accuracy, English |
| large-v3-turbo | 809 MB | Best multilingual, fast |
| large-v3 | 2.9 GB | Best accuracy, any language |

### parakeet.cpp (alternative, faster)
- NVIDIA Parakeet models, excellent English, smaller footprint
- Models from [mudler/parakeet-cpp-gguf](https://huggingface.co/mudler/parakeet-cpp-gguf)
- Install: Build from [source](https://github.com/mudler/parakeet.cpp) or use Docker

| Model | Size | Best for |
|-------|------|----------|
| tdt_ctc-110m-q8_0 | 178 MB | Fast, good English |
| tdt_ctc-110m-f16 | 268 MB | Fast, lossless English |
| tdt-0.6b-v3-f16 | 1.4 GB | Multilingual |

## Configuration

### Environment variables

```bash
MEETINGS_DIR       # Config & models directory (default: ~/.meetings)
MEETINGS_STT       # STT engine: whisper | parakeet
MEETINGS_STT_MODEL # Path to GGUF/GGML model file
MEETINGS_LLM       # Ollama model for summarization (default: llama3.1:8b)
MEETINGS_THREADS   # Thread count for STT (default: 4)
MEETINGS_LANG      # Language code (default: en; use "auto" for multilingual)
MEETINGS_OUTPUT    # Output directory (default: .)
```

### CLI flags

```bash
./meetings recording.mp3 --stt whisper --llm llama3.1:8b --lang en --output ./reports
```

### Config file

Saved at `~/.meetings/config` after running `./meetings setup`:

```
STT_ENGINE=whisper
OLLAMA_MODEL=llama3.1:8b
THREADS=4
STT_MODEL=/home/user/.meetings/models/ggml-small.en.bin
```

## Commands

```bash
./meetings <audio_file>              # Run the full pipeline
./meetings setup                     # Install deps + download model (interactive)
./meetings doctor                    # Check all dependencies
./meetings config                    # Show current configuration
./meetings help                      # Show help
```

## How Ollama fits in

**Ollama does NOT run the whisper/parakeet models** — those use their own inference engines (whisper.cpp / parakeet.cpp). Ollama is only used for the LLM steps:

1. **Summary generation** — sends the transcript to an Ollama model with a structured summarization prompt
2. **Action item extraction** — sends the transcript to an Ollama model with an action-item extraction prompt

You can use any Ollama model. Smaller models (llama3.2:1b, gemma3:1b) are faster; larger models (llama3.1:8b, qwen2.5-coder:7b) produce better summaries.

## Example

```bash
$ ./meetings team_standup.m4a

  ┌─────────────────────────────────────────────┐
  │          🎤  M E E T I N G S               │
  │   audio → transcript → summary + actions   │
  │       whisper.cpp · parakeet.cpp · ollama   │
  └─────────────────────────────────────────────┘

  Input:       team_standup.m4a
  STT engine:  whisper
  STT model:   ggml-small.en.bin
  LLM model:   llama3.1:8b
  Language:    en
  Output:      ./2026-06-07_1402_team_standup/

  ── Step 1/4 — Converting audio ──
  ▸ Converting audio to 16kHz mono WAV...
  ✓ Audio converted: 1.2M

  ── Step 2/4 — Transcribing with whisper ──
  ▸ Transcribing with whisper.cpp...
  ✓ Transcript: 847 words

  ── Step 3/4 — Summarizing (llama3.1:8b) ──
  ✓ Summary saved

  ── Step 4/4 — Extracting action items (llama3.1:8b) ──
  ✓ Action items saved

  ✓ All done! Files saved to: ./2026-06-07_1402_team_standup/

    📄 Report:        ./2026-06-07_1402_team_standup/report.md
    📝 Transcript:    ./2026-06-07_1402_team_standup/transcript.txt
    📋 Summary:      ./2026-06-07_1402_team_standup/summary.md
    ✅ Action Items:  ./2026-06-07_1402_item_standup/action_items.md
```

## License

MIT