# Git Commit Video Walkthrough Generator

A command-line tool that generates narrated video walkthroughs of git commits, staged/unstaged changes, or entire codebases with AI-powered analysis and explanations.

## Features

- 🎥 Automatic video generation from git commits, diffs, or codebases
- 🤖 AI-powered code analysis using Claude (Anthropic) or Gemini (Google)
- 🗣️ Natural text-to-speech narration
- 🎨 Syntax-highlighted code visualization
- 📊 Multiple presentation styles (beginner, technical, overview)
- ⚡ Standalone CLI - no external services required
- 🔑 Direct LLM API integration (Anthropic, Google AI)

## Installation

### Prerequisites

- **FFmpeg**: Required for video compilation
  - macOS: `brew install ffmpeg`
  - Linux: `apt install ffmpeg`
  - Windows: Download from [ffmpeg.org](https://ffmpeg.org/)

- **Node.js/Bun**: For running the CLI
  - Recommended: Bun 1.0+ (`curl -fsSL https://bun.sh/install | bash`)
  - Or Node.js 20+

- **LLM API Key**: You need an API key from one of these providers:
  - **Anthropic Claude**: Get from [console.anthropic.com](https://console.anthropic.com/)
  - **Google AI**: Get from [ai.google.dev](https://ai.google.dev/)

### Install from Source

```bash
# Clone the repository
git clone https://github.com/yourusername/code-walkthrough-cli.git
cd code-walkthrough-cli

# Install dependencies
bun install

# Build TypeScript
bun run build

# Optional: Create compiled binary
bun run build:bin
```

### Setup API Keys

Set your API key as an environment variable:

```bash
# For Anthropic Claude
export ANTHROPIC_API_KEY="your-api-key-here"

# Or for Google Gemini
export GOOGLE_API_KEY="your-api-key-here"

# Add to your shell profile (~/.zshrc, ~/.bashrc) to persist
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
```

## Usage

### Basic Usage

```bash
# Analyze a specific commit
git-commit-video abc123

# Analyze staged changes
git-commit-video --staged

# Analyze unstaged changes
git-commit-video --unstaged

# Analyze entire codebase
git-commit-video --codebase
```

### Options

```bash
git-commit-video <commit-hash> [options]

Options:
  --repo <path>          Path to git repository (default: current directory)
  --output <path>        Output video path (default: ./walkthrough.mp4)
  --style <style>        Presentation style: beginner, technical, overview (default: technical)
  --theme <theme>        Visual theme: dark, light, github (default: dark)
  --llm <provider>       LLM provider: anthropic, google (default: anthropic)
  --model <name>         Specific model to use (default: provider's latest)
  --help, -h             Show help
```

### Examples

```bash
# Generate video for commit with technical style
git-commit-video abc123 --style technical

# Analyze staged changes with light theme
git-commit-video --staged --theme light --output ./staged-changes.mp4

# Analyze entire codebase using Google Gemini
git-commit-video --codebase --llm google --style overview

# Use specific repository path
git-commit-video abc123 --repo /path/to/repo --output ./my-video.mp4
```

### Target Types

- **Specific Commit**: `git-commit-video <commit-hash>`
- **Staged Changes**: `git-commit-video --staged`
- **Unstaged Changes**: `git-commit-video --unstaged`
- **Entire Codebase**: `git-commit-video --codebase`

### Presentation Styles

- **beginner**: Detailed explanations, slower pace, educational tone
- **technical**: Precise, focused on implementation details
- **overview**: Quick, high-level summary of changes

### Visual Themes

- **dark**: Dark background (ideal for code)
- **light**: Light background
- **github**: GitHub-style syntax highlighting

## How It Works

The CLI follows a three-stage pipeline:

1. **Extract Git Data**: Analyzes commits, diffs, or codebase structure
2. **LLM Analysis**: Calls Claude/Gemini API to analyze code and generate narration script
3. **Video Generation**: Creates frames, generates audio, compiles into MP4

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Git Data   │ --> │ LLM Analysis │ --> │ Video Gen   │
│  Extraction │     │  (API Call)  │     │ (Frames+TTS)│
└─────────────┘     └──────────────┘     └─────────────┘
```

## Configuration

### API Key Configuration

You can provide your API key in multiple ways (in order of precedence):

1. **Environment Variable** (recommended):
   ```bash
   export ANTHROPIC_API_KEY="your-key"
   # or
   export GOOGLE_API_KEY="your-key"
   ```

2. **Command-line Argument**:
   ```bash
   git-commit-video abc123 --api-key "your-key"
   ```

3. **Config File** (`~/.git-commit-video/config.json`):
   ```json
   {
     "anthropicApiKey": "your-key",
     "googleApiKey": "your-key",
     "defaultLlm": "anthropic",
     "defaultStyle": "technical",
     "defaultTheme": "dark"
   }
   ```

### LLM Providers

**Anthropic Claude** (default):
- Best for code analysis
- Models: `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229`
- Get API key: [console.anthropic.com](https://console.anthropic.com/)

**Google Gemini**:
- Fast and cost-effective
- Models: `gemini-1.5-pro`, `gemini-1.5-flash`
- Get API key: [ai.google.dev](https://ai.google.dev/)

## Project Structure

```
.
├── src/
│   ├── cli.ts                # CLI entry point
│   ├── index.ts              # Core application logic
│   ├── stages/
│   │   ├── analysis.ts       # LLM analysis via API
│   │   ├── script.ts         # Script generation via API
│   │   └── video.ts          # Video generation pipeline
│   ├── extractors/
│   │   ├── commit.ts         # Extract commit info
│   │   ├── staged.ts         # Extract staged changes
│   │   ├── unstaged.ts       # Extract unstaged changes
│   │   └── codebase.ts       # Extract codebase info
│   ├── llm/
│   │   ├── anthropic.ts      # Anthropic API integration
│   │   ├── google.ts         # Google AI integration
│   │   └── types.ts          # LLM provider interface
│   ├── types/
│   │   ├── state.ts          # Type definitions
│   │   └── analysis.ts       # Analysis types
│   └── utils/
│       ├── prompts.ts        # LLM prompts for analysis
│       └── args.ts           # CLI argument parsing
├── dist/                     # Compiled JavaScript
├── bin/
│   └── git-commit-video      # Compiled binary (optional)
└── video_output/             # Generated videos (default)
```

## Development

```bash
# Watch mode (auto-rebuild on changes)
bun run watch

# Run CLI locally
bun run dev

# Build TypeScript
bun run build

# Build standalone binary
bun run build:bin

# Run tests
bun test
```

## Architecture

This CLI application uses a straightforward pipeline:

1. **User** runs CLI command with target (commit, staged, unstaged, codebase)
2. **CLI** extracts code/commits from git repository
3. **CLI** calls LLM API (Anthropic/Google) to analyze code
4. **LLM** returns structured analysis (JSON)
5. **CLI** calls LLM API again to generate narration script
6. **LLM** returns timed script with narration
7. **CLI** generates video frames, audio, and compiles final MP4

All processing happens locally - only the LLM analysis is done via API calls.

## Video Generation Pipeline

1. **Analysis**: Code is analyzed to understand what it does
2. **Script**: A narrated script is generated based on analysis
3. **Frames**: HTML frames are created with syntax-highlighted code
4. **Screenshots**: Puppeteer captures PNG screenshots of each frame
5. **Audio**: Text-to-speech generates narration audio
6. **Compilation**: FFmpeg combines frames and audio into MP4

## Output

The generated video includes:
- Introduction with project overview
- Section-by-section code walkthrough
- Syntax-highlighted code snippets
- Professional narration
- Conclusion summary

Example output structure:
```
walkthrough.mp4           # Final video
temp_frames/              # Temporary frame images (auto-deleted)
temp_audio.mp3           # Temporary audio (auto-deleted)
```

## Troubleshooting

### "API Key Not Found" Error

Make sure you've set your API key:
```bash
export ANTHROPIC_API_KEY="your-key"
# or
export GOOGLE_API_KEY="your-key"
```

Add it to your shell profile to persist across sessions.

### "FFmpeg Not Found" Error

Install FFmpeg:
- macOS: `brew install ffmpeg`
- Linux: `apt install ffmpeg`
- Windows: Download from ffmpeg.org and add to PATH

Verify installation: `ffmpeg -version`

### "Invalid JSON Response" Error

The LLM returned malformed JSON. This can happen with very large diffs. Try:
- Analyzing a smaller commit
- Using a different LLM provider (`--llm google`)
- Using a more capable model (`--model claude-3-opus-20240229`)

### No Audio in Video

The CLI uses system text-to-speech. If TTS fails, the video will be generated without audio (silent).

To improve TTS quality, install edge-tts:
```bash
pip install edge-tts
```

### Puppeteer Issues

Puppeteer downloads Chromium automatically. If it fails:
```bash
# Reinstall dependencies
rm -rf node_modules
bun install
```

### Rate Limiting

If you hit API rate limits, the CLI will automatically retry with exponential backoff. For large codebases, consider:
- Using `--style overview` for shorter analysis
- Splitting analysis into multiple commits
- Using a higher rate limit tier with your LLM provider

## Cost Estimates

Typical API costs (approximate):

| Target Type | Tokens | Anthropic (Claude) | Google (Gemini) |
|-------------|--------|-------------------|-----------------|
| Small commit (~10 files) | ~3K | $0.01 | $0.00 |
| Medium commit (~50 files) | ~15K | $0.05 | $0.01 |
| Large commit (~200 files) | ~60K | $0.20 | $0.03 |
| Entire codebase (small) | ~20K | $0.07 | $0.01 |
| Entire codebase (large) | ~100K | $0.35 | $0.05 |

Use `--dry-run` to see estimated costs before execution.

## License

MIT

## Contributing

Contributions welcome! Please ensure:
- TypeScript code compiles without errors
- Follow existing code style
- Update documentation for new features
- Add tests for new functionality

## Roadmap

- [ ] Support for more LLM providers (OpenAI, Cohere)
- [ ] Custom TTS voices
- [ ] Interactive mode with live preview
- [ ] Video editing features (trim, merge sections)
- [ ] Export to different formats (GIF, WebM)
- [ ] GitHub Actions integration