---
title: Meeting Minutes
---

Meeting Minutes (hereinafter the "Application") is a local, offline meeting recording, transcription, and summarisation tool designed to protect user data privacy by processing all audio and text entirely on the user's machine without any external services or cloud processing.

## 1. User Documentation

This section is for those interacting with a live instance of the Application.

### Overview

The Application automates the process of capturing, transcribing, and summarising meeting audio. It operates entirely offline to ensure complete data privacy and confidentiality of your meeting discussions.

### Features

- **Audio Recording**: Captures meeting audio from your system's default audio input/output mix
- **Speech-to-Text Transcription**: Converts recorded audio to text using WhisperX (OpenAI's Whisper model)
- **AI Summarisation**: Generates concise meeting summaries with key decisions, action items, and discussion points using a local LLM
- **Speaker Diarization** (Optional): Identifies and labels different speakers in the meeting
- **Complete Privacy**: All processing happens locally on your machine with no data transmission to external services

### How to Use

1. **Configure the meeting**: Edit the configuration section in `main.py`:
   - `WHISPER_MODEL`: Speech recognition model size (default: "small.en")
   - `DURATION`: Maximum recording duration in seconds (default: 36000 = 10 hours)

2. **Start recording**: Uncomment the `record_audio()` call in the main execution block to enable live recording, or place a pre-recorded `.wav` file in the project directory

3. **Run the application**: Execute `uvx python@3.12 main.py`

4. **Review output**: The Application generates:
   - A JSON transcript file containing the full transcription with timestamps
   - A text summary file containing the meeting summary, key decisions, action items, and discussion points

### Output Format

**Transcript** (`meeting_audio_[timestamp].json`): Contains:
- Full transcript text
- Segment-level timing information
- Speaker labels (if diarization is enabled)

**Summary** (`summary_[timestamp].txt`): Contains:
- Concise narrative summary of the meeting
- Key decisions made
- Action items identified
- Notable discussion points

### Keyboard Controls

- Press `q` during recording to stop early (when using the record_audio function)

## 2. Technical Documentation

This section is for those interested in running their own instance of the Application.

### System Requirements

- **Operating System**: Linux (default), Windows, or macOS with appropriate audio input configuration
- **Python**: Version 3.12 or compatible
- **Audio System**: PulseAudio (Linux) or equivalent audio framework
- **Disk Space**: Sufficient space for audio files and model storage (~2-5 GB for models)
- **Memory**: Minimum 8GB RAM recommended for local LLM processing

### Dependencies

The Application requires the following external tools:

1. **FFmpeg**: For audio recording and processing
2. **WhisperX**: For speech-to-text transcription
3. **Ollama**: For local LLM-based summarisation with llama3:8b model
4. **uv**: Python package and environment manager

### Installation

#### Step 1: Install Ollama

Download and install Ollama from https://ollama.ai, then pull the required model:

```bash
ollama pull llama3:8b
```

#### Step 2: Install uv

Follow the installation instructions at https://docs.astral.sh/uv/

#### Step 3: Install WhisperX

```bash
uvx python@3.12 whisperx
```

#### Step 4: Install FFmpeg

**Linux (Debian/Ubuntu):**
```bash
sudo apt-get install ffmpeg
```

**macOS:**
```bash
brew install ffmpeg
```

**Windows:**
Download from https://ffmpeg.org/download.html

#### Step 5: Clone the Repository

```bash
git clone [repository-url]
cd meeting-minutes
```

### Configuration

Edit `main.py` to configure the Application (lines 5-13):

```python
TIMESTAMP = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")  # Uncomment for dynamic timestamps
MEETING_FILE = f"meeting_audio_{TIMESTAMP}.wav"
WHISPER_MODEL = "small.en"  # Options: tiny.en, base.en, small.en, medium.en, large
DURATION = 36000  # Recording duration in seconds
OUTPUT_TRANSCRIPT = f"meeting_audio_{TIMESTAMP}.json"
OUTPUT_SUMMARY = f"summary_{TIMESTAMP}.txt"
```

#### Audio Input Configuration

By default, the Application uses PulseAudio (Linux). For other platforms:

**macOS:**
```python
"-f", "avfoundation",  # Replace line 19
"-i", ":0",            # Replace line 20 (use appropriate device index)
```

**Windows:**
```python
"-f", "dshow",         # Replace line 19
"-i", "audio=DEVICE_NAME",  # Replace line 20 (use your audio device name)
```

List available devices:
```bash
ffmpeg -list_devices true -f [dshow|avfoundation] -i dummy
```

### Optional: Speaker Diarization

Speaker diarization allows the Application to identify and label different speakers in the meeting.

#### Setup

1. Create a Hugging Face account at https://huggingface.co
2. Accept terms for these models:
   - https://huggingface.co/pyannote/segmentation-3.0
   - https://huggingface.co/pyannote/speaker-diarization-3.1
3. Generate a Hugging Face token with read permissions
4. Add the token to the WhisperX command in `transcribe_audio()` function (main.py:27-37):

```python
subprocess.run([
    "whisper",
    MEETING_FILE,
    "--device", "cpu",
    "--language", "en",
    "--model", WHISPER_MODEL,
    "--output_format", "json",
    "--output_dir", ".",
    "--hf_token", "YOUR_HF_TOKEN_HERE",  # Add this line
], check=True)
```

After the first successful run, you can remove the token from the code.

### Running the Application

#### With Live Recording

1. Uncomment line 84 in `main.py`:
   ```python
   record_audio()
   ```

2. Run the application:
   ```bash
   uvx python@3.12 main.py
   ```

#### With Pre-recorded Audio

1. Ensure line 84 remains commented out
2. Place your `.wav` file in the project directory
3. Update the `TIMESTAMP` variable to match your file name
4. Run:
   ```bash
   uvx python@3.12 main.py
   ```

### Architecture

The Application follows a linear pipeline architecture:

```
Audio Input → Recording (FFmpeg) → Transcription (WhisperX) → Summarisation (Ollama) → Cleanup
```

#### Component Details

**Recording Module** (`record_audio()` - main.py:15-25):
- Uses FFmpeg to capture system audio
- Supports configurable duration and audio quality
- Outputs WAV format for compatibility

**Transcription Module** (`transcribe_audio()` - main.py:27-37):
- Leverages WhisperX for accurate speech recognition
- Supports multiple model sizes (trade-off between speed and accuracy)
- Generates timestamped JSON transcripts
- Optional speaker diarization support

**Summarisation Module** (`summarize_with_local_model()` - main.py:39-74):
- Uses Ollama with llama3:8b for local AI processing
- Extracts key decisions, action items, and discussion points
- Generates natural language summaries
- No external API calls or data transmission

**Cleanup Module** (`cleanup()` - main.py:76-81):
- Removes temporary audio and transcript files
- Retains only the final summary

### Customization

#### Changing the Whisper Model

Available models with trade-offs:

- `tiny.en`: Fastest, least accurate (~1GB RAM)
- `base.en`: Fast, moderate accuracy (~1GB RAM)
- `small.en`: Balanced (default) (~2GB RAM)
- `medium.en`: Slower, more accurate (~5GB RAM)
- `large`: Slowest, most accurate (~10GB RAM)

Change the model on line 10 of `main.py`.

#### Changing the LLM Model

To use a different Ollama model:

1. Pull the desired model: `ollama pull [model-name]`
2. Update line 63 in `main.py`:
   ```python
   ["ollama", "run", "[model-name]"],
   ```

Popular alternatives:
- `llama3.1:8b`: Newer version of llama3
- `mistral`: Smaller, faster model
- `mixtral`: More powerful model (requires more RAM)

#### Customizing the Summary Prompt

Modify the prompt in `summarize_with_local_model()` (lines 49-60) to adjust summary style and content.

### Troubleshooting

**Issue**: "ffmpeg: command not found"
**Solution**: Install FFmpeg for your operating system

**Issue**: "ollama: command not found"
**Solution**: Install Ollama and ensure it's in your system PATH

**Issue**: WhisperX fails to transcribe
**Solution**: Ensure the audio file is valid WAV format and the Whisper model is downloaded

**Issue**: Summarisation takes too long
**Solution**: Use a smaller/faster Ollama model or switch to GPU processing

**Issue**: No audio captured during recording
**Solution**: Check your system's default audio input/output settings and adjust FFmpeg device parameters

### Performance Optimization

- **GPU Acceleration**: Change `--device` from "cpu" to "cuda" in the transcribe_audio() function if you have a compatible NVIDIA GPU
- **Smaller Models**: Use smaller Whisper models for faster processing
- **Parallel Processing**: For multiple meetings, run separate instances in different directories

## 3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

### Privacy Considerations

The Application is designed with privacy as a core principle:

- **No External Data Transmission**: All audio recording, transcription, and summarisation occurs locally on the user's machine
- **No Cloud Services**: No APIs, cloud services, or external servers are contacted during operation
- **User Control**: Users have complete control over all recorded data, transcripts, and summaries
- **Data Retention**: The Application automatically cleans up temporary files, retaining only the user-requested summary

### User Responsibilities

Users of the Application must:

1. **Obtain Consent**: Ensure all meeting participants have consented to recording before using the Application
2. **Comply with Laws**: Follow all applicable local, state, and federal laws regarding audio recording and consent
3. **Protect Data**: Securely store and handle meeting summaries and transcripts containing sensitive or confidential information
4. **Respect Confidentiality**: Honour any confidentiality agreements or expectations of meeting participants

### Compliance Recommendations

- Check local "one-party" vs "all-party" consent laws before recording
- Announce at the beginning of meetings that recording is in progress
- Store output files in encrypted storage if they contain sensitive information
- Implement appropriate data retention policies for meeting summaries

### License

This software is licensed under the [global software licence](https://docs.nhcarrigan.com/#/license).

Copyright held by Naomi Carrigan.

For additional legal documentation, refer to:
- [Terms of Service](TERMS.md)
- [Privacy Policy](PRIVACY.md)
- [Security Policy](SECURITY.md)

## 4. Contributing Documentation

This section is for documentation related to contributing to the Application's codebase.

### How to Contribute

We welcome contributions to the Meeting Minutes Application! Please review our [contributing guidelines](https://docs.nhcarrigan.com/#/contributing) before getting started.

### Contribution Process

1. **Fork the Repository**: Create your own fork of the project
2. **Create a Branch**: Make a feature branch for your changes
3. **Make Changes**: Implement your feature or bug fix
4. **Test Thoroughly**: Ensure your changes work as expected
5. **Submit a Pull Request**: Describe your changes and submit for review

### Code of Conduct

Before interacting with our community, please read our [Code of Conduct](CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for all contributors.

### Development Setup

To set up a development environment:

1. Follow the installation instructions in Section 2
2. Create a test meeting audio file or use the sample files
3. Make changes to `main.py`
4. Test your changes with various audio inputs and configurations

### Contribution Ideas

We welcome contributions in the following areas:

**Features**:
- GUI interface for easier configuration and operation
- Support for additional audio formats (MP3, M4A, etc.)
- Real-time transcription display during recording
- Integration with calendar systems for automatic meeting detection
- Multi-language support beyond English
- Custom vocabulary support for domain-specific terminology
- Export to additional formats (PDF, Markdown, etc.)
- Meeting analytics and insights

**Improvements**:
- Better error handling and user feedback
- Configuration file support (YAML/JSON) instead of hardcoded values
- Automated testing suite
- Performance optimisations
- Documentation improvements
- Cross-platform compatibility testing

**Bug Fixes**:
- Any identified issues in audio recording, transcription, or summarisation
- Platform-specific bugs
- Edge cases in file handling

### Testing Guidelines

When contributing, please test:

1. **Audio Recording**: Verify recording works with various audio sources
2. **Transcription**: Test with different accents, speaking speeds, and audio quality
3. **Summarisation**: Ensure summaries are coherent and capture key information
4. **Cross-platform**: Test on different operating systems if possible
5. **Error Handling**: Test edge cases and error conditions

### Code Style

- Follow PEP 8 Python style guidelines
- Use meaningful variable and function names
- Add comments for complex logic
- Keep functions focused on single responsibilities

### Reporting Issues

If you encounter bugs or have feature requests:

1. Check existing posts in the #bug-reports or #feature-requests forum channels to avoid duplicates
2. Post in the appropriate forum channel with a clear title and description
3. Include steps to reproduce (for bugs)
4. Provide system information (OS, Python version, etc.)

### Getting Help

If you need assistance:

- Post in the #bug-reports or #feature-requests forum channels on our Discord community
- Join our [Chat Server](https://chat.nhcarrigan.com)
- Email us at `contact@nhcarrigan.com`

### Recognition

All contributors will be acknowledged in the project. Thank you for helping make Meeting Minutes better!
