Video Analyzer

AI-powered video analysis tool using Gemini 3 Flash to identify events, generate timestamps, and help organize your home videos.

Features

• Automatic Event Detection: Identifies distinct events, activities, and scenes in your videos
• Timestamp Generation: Provides accurate start/end timestamps for all events
• Smart Video Splitting: Automatically splits long videos (>30 min) into chunks for analysis
• Intelligent Stitching: Uses AI to merge multi-chunk analyses into a coherent timeline
• Rich Metadata: Extracts people, locations, tags, and highlights from video content
• Multiple Export Formats: JSON, Markdown, and CSV exports
• Easy CLI Interface: Simple command-line interface for all operations

Requirements

• Python 3.10+
• ffmpeg (for video processing)
• OpenRouter API key (for Gemini 3 Flash access)

Installation

1. Install ffmpeg

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install ffmpeg

Windows: Download from ffmpeg.org or use:

choco install ffmpeg

2. Clone and Setup

cd video-analyzer

# Install Python dependencies
pip install -r requirements.txt

# Or use a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Configure API Key

The .env file is already created with your API key. If you need to update it:

# Edit .env file
nano .env

# Add your OpenRouter API key
OPENROUTER_API_KEY=your-api-key-here

Usage

Analyze a Video

# Basic analysis
python -m src.main analyze videos/birthday.mp4

# Custom output name
python -m src.main analyze videos/vacation.mp4 --output vacation_summer_2023

# Skip automatic splitting (for videos < 30 min or to force single analysis)
python -m src.main analyze videos/short_clip.mp4 --no-split

# Use simple stitching instead of LLM stitching (faster, less intelligent)
python -m src.main analyze videos/long_video.mp4 --no-stitch

# Keep video chunks with AI-generated descriptive names (instead of deleting them)
python -m src.main analyze videos/long_video.mp4 --keep-chunks

List All Analyses

python -m src.main list

View Analysis Summary

python -m src.main summary birthday_20231225_143022.json

Query Specific Events

# View all events
python -m src.main events birthday_20231225_143022.json

# Filter by event type
python -m src.main events vacation.json --type outdoor_activity

# Filter by tags
python -m src.main events party.json --tags celebration,family

Export Analysis

# Export to Markdown
python -m src.main export birthday.json --format markdown

# Export to CSV (event timestamps)
python -m src.main export birthday.json --format csv --output events.csv

# Copy JSON to custom location
python -m src.main export birthday.json --format json --output backup.json

AI-Generated Chunk Names

When using the --keep-chunks flag, the analyzer will automatically rename video chunks with descriptive names based on their content:

• Before: 2106880-01-USB_compressed_chunk_001.mp4
• After: 000000-001000_mountain-hiking-trail.mp4

This makes it easy to:

• Browse chunks by content without re-watching
• Share specific segments with others
• Quickly locate interesting moments in long videos
• Organize your video library

The AI analyzes the events, people, locations, and activities in each chunk to generate concise, descriptive filenames.

How It Works

Video Analysis Pipeline

1. Video Validation: Checks if the video file is valid and supported
2. Duration Check: Determines if video needs to be split (>10 minutes)
3. Splitting (if needed): Uses ffmpeg to split video into 10-minute chunks
4. Analysis: Each chunk is:
   • Encoded to base64
   • Sent to Gemini 3 Flash via OpenRouter
   • Analyzed for events, timestamps, people, locations, and tags
5. Naming (if --keep-chunks): AI generates descriptive filenames for chunks
6. Stitching (if multiple chunks): AI merges analyses and adjusts timestamps
7. Output: Saves comprehensive JSON analysis with metadata
8. Cleanup: Removes temporary chunks (unless --keep-chunks is used)

Analysis Output

Each analysis includes:

• Events: Detailed timeline of activities with timestamps
• Scene Changes: Points where the video significantly changes
• Overall Summary: High-level description of video content
• Metadata: Video info, analysis date, model used

Example Output Structure

{
  "metadata": {
    "original_video": "birthday.mp4",
    "duration": "01:15:30",
    "analyzed_at": "2025-12-22T10:30:00",
    "model": "google/gemini-3-flash-preview",
    "chunks_processed": 3
  },
  "events": [
    {
      "start_time": "00:00:00",
      "end_time": "00:05:30",
      "event_type": "party_setup",
      "description": "Adults setting up decorations and tables in backyard",
      "people": ["adult male", "adult female"],
      "location": "backyard",
      "tags": ["preparation", "outdoor", "decorations"],
      "highlights": ["Birthday banner hung at 00:02:15"]
    },
    {
      "start_time": "00:15:00",
      "end_time": "00:25:30",
      "event_type": "birthday_celebration",
      "description": "Children gathered around cake, singing and celebration",
      "people": ["birthday child", "group of children", "parents"],
      "location": "backyard table",
      "tags": ["celebration", "cake", "singing", "family"],
      "highlights": ["Cake cutting at 00:18:30", "Gift opening at 00:22:00"]
    }
  ],
  "scene_changes": ["00:05:30", "00:15:00", "00:30:00"],
  "overall_summary": "Birthday party celebration with setup, cake, gifts, and outdoor games"
}

Directory Structure

video-analyzer/
├── videos/              # Place your videos here
├── outputs/
│   ├── analyses/        # JSON analysis files saved here
│   └── chunks/          # Temporary video chunks (auto-deleted)
├── src/                 # Source code
│   ├── main.py          # CLI interface
│   ├── config.py        # Configuration
│   ├── video_processor.py  # Video splitting & encoding
│   ├── analyzer.py      # API integration & analysis
│   ├── stitcher.py      # Multi-chunk merging
│   └── utils.py         # Helper functions
├── .env                 # API key (DO NOT COMMIT)
├── .gitignore           # Git ignore rules
├── requirements.txt     # Python dependencies
└── README.md            # This file

Configuration

Edit src/config.py to customize:

• CHUNK_DURATION: Video chunk size in seconds (default: 1800 = 30 min)
• THINKING_LEVEL: Gemini reasoning level (minimal, low, medium, high)
• MEDIA_RESOLUTION: Video processing resolution (low, medium, high)
• MAX_RETRIES: API request retry attempts
• MODEL_ID: OpenRouter model to use

Supported Video Formats

• MP4 (.mp4)
• MOV (.mov)
• AVI (.avi)
• WebM (.webm)
• MPEG (.mpeg, .mpg)
• M4V (.m4v)
• 3GPP (.3gpp)

Troubleshooting

"ffmpeg is not installed"

Install ffmpeg using the instructions in the Installation section above.

"API request failed (401)"

Check that your OPENROUTER_API_KEY in .env is correct and active.

"API request failed (429)" - Rate Limited

The API is rate-limited. The tool will automatically retry with exponential backoff. For persistent issues:

• Wait a few minutes between analyses
• Use smaller videos or split manually
• Check your OpenRouter plan limits

"Failed to encode video"

• Check that the video file is not corrupted
• Ensure file size is reasonable (<500MB per chunk)
• Try converting to MP4 format first

Analysis takes a very long time

• Video analysis can take 2-5 minutes per 30-minute chunk
• Longer videos require more time
• Network speed affects upload time for base64-encoded video

Out of memory errors

• Use --no-split for smaller videos to avoid chunk overhead
• Close other applications
• Split very large videos manually into smaller files first

Cost Estimation

Using Gemini 3 Flash via OpenRouter:

• Input: $0.50 per 1M tokens
• Output: $3.00 per 1M tokens
• Audio: $1.00 per 1M tokens

Approximate costs:

• 30-minute video (with audio): ~$0.05-0.15
• 1-hour video (2 chunks): ~$0.10-0.30
• Token usage varies based on video content and complexity

Tips for Best Results

1. Video Quality: Higher quality videos (1080p) provide better analysis
2. Lighting: Well-lit videos are analyzed more accurately
3. Audio: Videos with clear audio provide richer context
4. Stability: Steady camera work helps with scene detection
5. Length: Break very long videos (>2 hours) into logical segments
6. File Names: Use descriptive names for easier organization

Privacy & Security

• Local Processing: All video encoding happens locally
• API Transmission: Videos are sent to OpenRouter/Gemini via secure HTTPS
• No Storage: OpenRouter doesn't store your video data (zero retention policy)
• API Key: Keep your .env file secure and never commit it to git

Advanced Usage

Custom Analysis Prompts

Modify ANALYSIS_PROMPT in src/analyzer.py to customize what the AI looks for in your videos.

Batch Processing

# Process multiple videos
for video in videos/*.mp4; do
    python -m src.main analyze "$video"
done

Integration with Video Editors

Export events to CSV and import timestamps into:

• DaVinci Resolve
• Adobe Premiere Pro
• Final Cut Pro

Contributing

This is a personal project, but suggestions and improvements are welcome! Feel free to:

• Open issues for bugs or feature requests
• Submit pull requests for enhancements
• Share your use cases and results

License

MIT License - feel free to use and modify as needed.

Acknowledgments

• Powered by Google Gemini 3 Flash
• API access via OpenRouter
• Video processing with ffmpeg

Support

For issues or questions:

1. Check this README's Troubleshooting section
2. Review the code comments in src/ directory
3. Check OpenRouter and Gemini documentation for API issues

---

Happy video organizing! 🎥✨