Video Walkthrough Tools for Presenting Code Changes to Non-Technical Clients

#!/usr/bin/env python3
# Generate video walkthrough script from git diff

import subprocess
import sys
from typing import List, Dict

class VideoWalkthroughScriptGenerator:
    def __init__(self, repo_path: str, start_sha: str, end_sha: str):
        self.repo_path = repo_path
        self.start_sha = start_sha
        self.end_sha = end_sha

    def get_changed_files(self) -> List[str]:
        """Retrieve list of files changed between commits"""
        result = subprocess.run(
            ['git', 'diff', '--name-only', f'{self.start_sha}..{self.end_sha}'],
            cwd=self.repo_path,
            capture_output=True,
            text=True
        )
        return result.stdout.strip().split('\n')

    def get_commit_message(self) -> str:
        """Extract commit message for intro"""
        result = subprocess.run(
            ['git', 'log', '-1', '--pretty=%B', self.end_sha],
            cwd=self.repo_path,
            capture_output=True,
            text=True
        )
        return result.stdout.strip()

    def get_diff_summary(self) -> Dict[str, int]:
        """Calculate insertions, deletions, files changed"""
        result = subprocess.run(
            ['git', 'diff', '--stat', f'{self.start_sha}..{self.end_sha}'],
            cwd=self.repo_path,
            capture_output=True,
            text=True
        )
        # Parse format: " file.js | 45 +++++++-----"
        lines = result.stdout.strip().split('\n')
        return {
            'files_changed': len([l for l in lines if '|' in l]),
            'raw_output': result.stdout
        }

    def generate_script(self) -> str:
        """Generate a walkthrough script template"""
        commit_msg = self.get_commit_message()
        summary = self.get_diff_summary()
        files = self.get_changed_files()

        script = f"""
# VIDEO WALKTHROUGH SCRIPT
# Generated from {self.start_sha}..{self.end_sha}

## INTRO (30 seconds)
Start with: "This video explains the changes we made to {', '.join(files[:2])}"

**Point to make:**
- What was the original issue?
- Why did we need to change this?
- What's the business impact?

**Opening statement:**
"{commit_msg}"

## TECHNICAL WALKTHROUGH (2-3 minutes)
Show these files in order (git is showing {summary['files_changed']} changed):
"""
        for i, file in enumerate(files[:5], 1):
            script += f"\n{i}. {file}"
            script += f"\n   - Open the file: Cmd+P (VS Code) and type filename"
            script += f"\n   - Highlight the key changes"
            script += f"\n   - Explain what each change does"

        script += f"""

## CLIENT-FACING SUMMARY (30 seconds)
Translate to business impact:
- "This means [X] for your users"
- "Testing confirmed [Y]"
- "The fix is live and monitoring shows [Z]"

## CLOSING
Offer follow-up: "Let me know if you have any questions about these changes"
"""
        return script

    def show_files_to_record(self):
        """Print file list with git diff for easy reference while recording"""
        result = subprocess.run(
            ['git', 'diff', f'{self.start_sha}..{self.end_sha}', '--'],
            cwd=self.repo_path,
            capture_output=True,
            text=True
        )
        return result.stdout

# Usage
if __name__ == '__main__':
    generator = VideoWalkthroughScriptGenerator(
        repo_path='.',
        start_sha='HEAD~5',
        end_sha='HEAD'
    )

    print(generator.generate_script())
    print("\n\n# GIT DIFF for reference:")
    print(generator.show_files_to_record())

# Video catalog management
import os
import json
from pathlib import Path
from datetime import datetime

class VideoWalkthroughLibrary:
    def __init__(self, library_path: str):
        self.library_path = Path(library_path)
        self.catalog_file = self.library_path / "catalog.json"
        self.catalog = self.load_catalog()

    def catalog_video(self, video_path: str, metadata: dict):
        """Register a video with searchable metadata"""
        video_file = Path(video_path)
        file_size_mb = video_file.stat().st_size / (1024 * 1024)

        entry = {
            'filename': video_file.name,
            'path': str(video_path),
            'uploaded_date': datetime.now().isoformat(),
            'file_size_mb': round(file_size_mb, 2),
            'duration_seconds': self.get_video_duration(video_path),
            'tags': metadata.get('tags', []),
            'title': metadata.get('title', ''),
            'commit_sha': metadata.get('commit_sha', ''),
            'related_files': metadata.get('files', []),
            'ticket_id': metadata.get('ticket_id', '')
        }

        self.catalog.append(entry)
        self.save_catalog()
        return entry

    def search_videos(self, query: str = '', tag: str = '', ticket_id: str = ''):
        """Find videos by search terms, tags, or ticket ID"""
        results = []
        for entry in self.catalog:
            if query and query.lower() in entry['title'].lower():
                results.append(entry)
            elif tag and tag in entry['tags']:
                results.append(entry)
            elif ticket_id and ticket_id == entry['ticket_id']:
                results.append(entry)

        return results

    def get_video_duration(self, video_path: str) -> int:
        """Get video duration in seconds using ffprobe"""
        import subprocess
        result = subprocess.run(
            ['ffprobe', '-v', 'error', '-show_entries',
             'format=duration', '-of',
             'default=noprint_wrappers=1:nokey=1:noprint_filename=1',
             video_path],
            capture_output=True,
            text=True
        )
        return int(float(result.stdout.strip()))

    def load_catalog(self):
        if self.catalog_file.exists():
            with open(self.catalog_file, 'r') as f:
                return json.load(f)
        return []

    def save_catalog(self):
        with open(self.catalog_file, 'w') as f:
            json.dump(self.catalog, f, indent=2)

# Usage
library = VideoWalkthroughLibrary('~/Videos/code_walkthroughs')
library.catalog_video(
    '~/Videos/code_walkthroughs/walkthrough_20260321_143022.mov',
    {
        'title': 'Login Timeout Fix',
        'tags': ['authentication', 'bug-fix', 'client-communication'],
        'commit_sha': 'a3f5d9e2c1b4',
        'files': ['config/auth.php', 'app/Http/Controllers/PasswordResetController.php'],
        'ticket_id': 'PROJ-1247'
    }
)

# Later: Find the video by ticket
results = library.search_videos(ticket_id='PROJ-1247')
for result in results:
    print(f"{result['title']} ({result['duration_seconds']}s)")