video-metadata-inspector

name	video-metadata-inspector
description	Use when asked to inspect video file metadata, get video duration, resolution, codec information, frame rate, or bitrate.

Video Metadata Inspector

Extract and analyze comprehensive metadata from video files including duration, resolution, codec, frame rate, and technical specifications.

Purpose

Video metadata inspection for:

• Format verification and compatibility checking
• Quality assessment and validation
• Transcoding planning and optimization
• Video library cataloging
• Technical specification reports

Features

• Basic Info: Duration, resolution, frame rate, file size
• Codec Details: Video/audio codec, profile, bitrate
• Technical Specs: Aspect ratio, pixel format, sample rate
• Metadata: Title, artist, creation date, tags
• Batch Analysis: Process multiple files in one operation
• Export Formats: JSON, CSV, human-readable text

Quick Start

from video_metadata_inspector import VideoMetadataInspector

# Inspect single video
inspector = VideoMetadataInspector()
inspector.load('video.mp4')
metadata = inspector.get_metadata()
print(f"Duration: {metadata['duration_seconds']:.2f}s")
print(f"Resolution: {metadata['width']}x{metadata['height']}")
print(f"FPS: {metadata['fps']}")

# Export full report
inspector.export_report('report.json', format='json')

# Batch inspect directory
inspector.batch_inspect(
    input_files=['video1.mp4', 'video2.mkv'],
    output='metadata.csv',
    format='csv'
)

CLI Usage

# Basic metadata
python video_metadata_inspector.py input.mp4

# Full technical details
python video_metadata_inspector.py input.mp4 --verbose

# Export to JSON
python video_metadata_inspector.py input.mp4 --output metadata.json --format json

# Batch inspect directory
python video_metadata_inspector.py *.mp4 --output metadata.csv --format csv

# Compare multiple videos
python video_metadata_inspector.py video1.mp4 video2.mp4 --compare

API Reference

VideoMetadataInspector

class VideoMetadataInspector:
    def load(self, filepath: str) -> 'VideoMetadataInspector'
    def get_metadata(self) -> Dict[str, Any]
    def get_basic_info(self) -> Dict[str, Any]
    def get_video_info(self) -> Dict[str, Any]
    def get_audio_info(self) -> Dict[str, Any]
    def get_format_info(self) -> Dict[str, Any]
    def export_report(self, output: str, format: str = 'json') -> str
    def batch_inspect(self, input_files: List[str], output: str = None,
                     format: str = 'csv') -> pd.DataFrame
     () -> pd.DataFrame

Metadata Categories

Basic Information

• Duration (seconds, formatted)
• Resolution (width × height)
• Frame rate (FPS)
• File size
• Aspect ratio

Video Stream

• Video codec (H.264, H.265, VP9, etc.)
• Codec profile and level
• Bitrate (kbps)
• Pixel format (yuv420p, etc.)
• Color space and range

Audio Stream

• Audio codec (AAC, MP3, Opus, etc.)
• Sample rate (Hz)
• Channels (mono, stereo, 5.1, etc.)
• Audio bitrate (kbps)

Container Format

• Container type (MP4, MKV, AVI, etc.)
• Creation date
• Metadata tags (title, artist, description)
• Number of streams

Use Cases

Format Verification:

inspector.load('video.mp4')
info = inspector.get_video_info()
if info['codec'] == 'h264' and info['width'] >= 1920:
    print("✓ Meets requirements: 1080p H.264")

Transcoding Planning:

# Check if transcoding needed
metadata = inspector.get_metadata()
if metadata['video_codec'] != 'h265' or metadata['bitrate_kbps'] > 5000:
    print("Transcode recommended")

Quality Assessment:

# Analyze video quality metrics
info = inspector.get_metadata()
quality_score = (
    (info['width'] * info['height']) / 2073600 * 50 +  # Resolution score
    min(info['fps'] / 60, 1) * 25 +  # Frame rate score
    min(info['bitrate_kbps'] / 10000, 1) * 25  # Bitrate score
)

Common Checks

Is video 4K?

metadata['width'] >= 3840 and metadata['height'] >= 2160

Is video HDR?

'hdr' in metadata.get('color_space', '').lower()

Is audio stereo?

metadata['audio_channels'] == 2

Is codec modern?

metadata['video_codec'] in ['h265', 'vp9', 'av1']

Limitations

• Cannot extract corrupt/damaged video metadata
• Some proprietary formats may have limited support
• DRM-protected content cannot be analyzed
• Metadata extraction may be slow for very large files
• Requires FFmpeg/FFprobe for full codec details