🎬 CodecInspector

Video Codec Analysis, Quality Scoring & HEVC Transcoding Tool — built with FFmpeg/FFprobe, Python and Streamlit.

CodecInspector inspects any video file, extracts detailed codec/container metadata, computes an Overall Quality Score, gives an actionable recommendation, and can transcode the file to H.265 (HEVC) while reporting exactly how much bitrate and file size were saved. It also ships a Batch Analyzer for scanning an entire folder of videos at once.

⭐ If you find this useful, consider starring the repo.

---

✨ Features

Category	Feature
Metadata	Codec, profile, level, resolution, FPS, duration, frame count, container, file size, bitrate
Advanced Metadata	Pixel format, chroma subsampling, bit depth, aspect ratio, color space, encoder tag, B-frames, audio stream info
Quality Scoring	0–100 Overall Score based on codec modernity, bits-per-pixel efficiency and file size, with good/warning/bad badges
Recommendation Engine	Actionable, codec- and score-aware suggestions (e.g. "Convert to HEVC to cut bitrate further")
Transcoding	One-click H.264 → H.265 (HEVC) conversion via FFmpeg, with adjustable CRF
Comparison	Before/after codec, bitrate and size comparison with automatic savings %
Batch Analyzer	Scan an entire folder, analyze every video, and bulk-convert the whole batch to H.265 with aggregate savings
Reports	Styled HTML report, professional PDF report, and CSV export
Raw Data	One-click download of the raw FFprobe JSON metadata
Dashboard	Clean Streamlit UI with drag & drop upload, thumbnails, metrics and downloads

---

🖼️ Screenshots

Upload & drag-and-drop

Video analysis & Overall Score

Advanced metadata, audio stream & export

H.265 conversion & comparison report

Batch analyzer

---

🧱 Architecture

CodecInspector/
│
├── dashboard.py              # Main Streamlit UI (single-video analysis + conversion)
├── batch_dashboard.py        # Streamlit UI for batch folder analysis + bulk conversion
├── app.py                    # Terminal / CLI demo of the full pipeline
├── config.py                 # Cross-platform FFmpeg/FFprobe path resolution & directories
├── requirements.txt
│
├── models/
│   └── media_info.py         # MediaInfo dataclass — normalized video metadata
│
├── utils/
│   ├── ffprobe_utils.py       # FFprobe subprocess wrapper
│   ├── metadata.py            # Raw ffprobe JSON -> MediaInfo (advanced field extraction)
│   └── formatter.py           # Human-readable size / bitrate / duration formatting
│
├── services/
│   ├── analyzer.py            # Facade: ffprobe + metadata + score + recommendation in one call
│   ├── score.py                # Overall Score engine (codec / bitrate / size weighting)
│   ├── recommendation.py       # Recommendation engine
│   ├── thumbnail.py            # Thumbnail extraction (FFmpeg)
│   ├── transcoder.py           # H.264 -> H.265 transcoding (FFmpeg)
│   ├── compare.py              # Before/after comparison + savings calculation
│   ├── batch_analyzer.py       # Folder scanning + batch analysis + batch transcoding
│   ├── report.py               # Styled HTML report generator
│   ├── pdf_report.py           # PDF report generator (ReportLab)
│   ├── csv_export.py           # CSV export
│   └── json_export.py          # Raw FFprobe JSON export
│
├── sample_videos/             # Small sample clip for demos/tests
├── thumbnails/                # Generated thumbnails
├── reports/                   # Generated HTML/PDF/CSV reports & converted videos (gitignored)
├── temp/                      # Uploaded-file scratch space (gitignored)
└── screenshots/               # README screenshots

Design principle: ffprobe/ffmpeg calls, metadata parsing, scoring, and reporting are each isolated in their own service, so dashboard.py and batch_dashboard.py stay thin and only handle UI/state.

---

🚀 Installation

Prerequisites

• Python 3.9+
• FFmpeg & FFprobe installed and available on your system:
  • Windows: download from ffmpeg.org, add ffmpeg\bin to PATH (or set CODECINSPECTOR_FFMPEG / CODECINSPECTOR_FFPROBE env vars to the full .exe paths).
  • macOS: brew install ffmpeg
  • Linux: sudo apt install ffmpeg

Setup

git clone https://github.com/fatmanurylmaaaz/CodecInspector.git
cd CodecInspector

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

pip install -r requirements.txt

---

▶️ Usage

Interactive dashboard (single video)

streamlit run dashboard.py

Upload a video (drag & drop supported) to see:

• Full metadata + advanced metadata
• Overall Score + recommendation
• One-click H.265 conversion with before/after comparison
• JSON / CSV / HTML / PDF export buttons

Batch analyzer (whole folder)

streamlit run batch_dashboard.py

Point it at any folder to analyze every video inside, export the results to CSV, and optionally bulk-convert the entire batch to H.265 with aggregate size/bitrate savings.

CLI demo

python app.py

Runs the full pipeline (metadata → score → recommendation → thumbnail → H.265 conversion → comparison) against the bundled sample video and prints the results to the terminal.

---

🧮 How the Overall Score works

The score is a weighted combination of three factors:

Factor	Weight	What it measures
Codec modernity	45%	AV1/HEVC score highest, H.264 mid-high, legacy codecs (MPEG-2, MJPEG) score low
Bitrate efficiency	35%	Bits-per-pixel (bitrate / (width × height × fps)) — rewards efficient encoding
File size efficiency	20%	MB per minute of runtime — rewards compact files

Each factor also produces a ✔ good / ⚠ warning / ✘ bad badge, plus a Streaming Ready check (codec + container combination suitable for web/streaming delivery).

---

🛠️ Tech Stack

• Python 3
• Streamlit — dashboard UI
• FFmpeg / FFprobe — video analysis & transcoding
• Pandas — tabular data (batch analyzer, comparisons)
• ReportLab — PDF report generation

---

🗺️ Roadmap

Planned for future versions:

• AV1 transcoding support
• Configurable target bitrate/resolution presets
• Drag & drop batch folder upload (zip) for environments without local file access
• Dockerfile for one-command deployment

---

📄 License

Released under the MIT License.

---