Interview Processor

A Python tool for processing interview transcripts from VTT files, with automatic speaker labeling and Word document generation. Built with love to help my wonderful wife <3 with her thesis!

Features

• VTT Processing: Parse WebVTT transcript files with timestamp extraction
• Speaker Labeling: Automatically replace speaker names with consistent "Interviewer" and "Interviewee N" labels
• Caption Concatenation: Merge contiguous captions from the same speaker for cleaner output
• Word Document Generation: Create formatted Word documents with simplified timestamps
• Consistent Numbering: Match interviewee numbers to interview numbers (Interview 1 -> Interviewee 1)

Installation

This project uses uv for dependency management. Install uv first, then:

git clone <repository-url>
cd interview-processor
uv sync

Usage

1. Process VTT Transcripts

Place your VTT files in the interviews/ directory structure:

interviews/
├── 01/
│   └── GMT20250616-140650_Recording.transcript.vtt
├── 02/
│   └── GMT20250616-153105_Recording.transcript.vtt
└── ...

Run the transcript processor:

uv run python process_transcripts.py

This will:

• Read all VTT files from interview folders
• Concatenate contiguous captions from the same speaker
• Replace speaker names with "Interviewer" and "Interviewee N" labels
• Save processed transcripts to processed/ directory

2. Generate Word Document

Create a combined Word document from all processed transcripts:

uv run python create_word_document.py

This generates combined_interviews.docx with:

• Plain text formatting (no styling)
• Simplified timestamps in [HH:MM:SS] format
• "Interview N" titles with page breaks between interviews
• Consistent speaker labeling throughout

Project Structure

interview-processor/
├── process_transcripts.py    # VTT processing and speaker labeling
├── create_word_document.py   # Word document generation
├── interviews/               # Input VTT files (gitignored)
├── processed/                # Processed transcript files (gitignored)
├── combined_interviews.docx  # Output Word document (gitignored)
├── pyproject.toml            # Project configuration
├── LICENSE                   # BSD 3-Clause License
└── README.md                 # This file

Development

Setup

uv sync --dev

Testing

Run the test suite:

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_process_transcripts.py

Code Quality

This project uses ruff for linting and formatting:

# Check code
uv run ruff check .

# Format code
uv run ruff format .

# Auto-fix issues
uv run ruff check --fix .

Configuration

• Line length: 119 characters
• Python version: 3.13+
• Import sorting: Enabled via ruff
• Type hints: Modern syntax (list[dict] instead of List[Dict])

Example Output

Processed Transcript Format

[00:00:03] Interviewer: Hello, how are you?

[00:00:11] Interviewee 1: I'm good, thank you. How about you?

[00:00:21] Interviewer: I'm doing well, thanks for asking.

Word Document Structure

• Interview 1 (plain text title)
• Transcript content with timestamps and speaker labels
• Page break
• Interview 2
• ...and so on

Requirements

• Python 3.13+
• uv package manager
• Dependencies managed via pyproject.toml

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run code quality checks (uv run ruff check . && uv run ruff format .)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Notes

• The tool assumes the first speaker in each interview is the interviewer
• Interview folders should be numbered (01, 02, 03, etc.)
• VTT files should follow standard WebVTT format
• Generated Word documents use plain text formatting for maximum compatibility