# yellowcandle/mv-face-recognition architecture

> Architecture diagram of the GitHub repository yellowcandle/mv-face-recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yellowcandle/mv-face-recognition
- Repository: https://github.com/yellowcandle/mv-face-recognition

## Overview

##### Main Components

a) Input Sources Layer:
- Video Input Component (YouTube videos via yt-dlp)
- Photo Database Component (contestant reference photos)
- Contestant Information Component (CSV data)

b) Processing Layer:
- Face Detection Module (InsightFace)
- Face Recognition Module (InsightFace embeddings)
- Video Frame Processing (OpenCV)
- Data Processing Pipeline

c) Output Layer:
- Labeled Video Generation
- Analysis Reports Generation
- Results Storage

**[Input Layer]**
- ↓
**[Processing Layer]**
- ↓
**[Output Layer]**

##### Component Details

Input Layer:
- Rectangle: "Video Downloader (yt-dlp)" → connects to video processing
- Database Symbol: "Contestant Photo Database" → connects to face recognition
- Document Symbol: "Contestant Info CSV" → connects to data processing

Processing Layer:
- Hexagon: "Face Detection Engine (InsightFace)"
- Hexagon: "Face Recognition Engine (InsightFace)"
- Rectangle: "Frame Processor (OpenCV)"
- Diamond: "Data Pipeline Manager"

Output Layer:
- Movie Symbol: "Labeled Video Output"
- Document Symbol: "Analysis Reports"
- Database Symbol: "Results Storage"

##### Data Flow Representation

- Video download → Frame extraction
- Reference photos → Face embedding generation
- Face detection → Recognition matching
- Recognition results → Video labeling
- Results → Analysis generation

##### Additional Elements

Technical details in notes or callouts:
- Python as primary language
- InsightFace model specifications
- OpenCV processing capabilities
- Data formats (embedding files, CSV)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style definitions
    classDef input fill:#a8d1f0,stroke:#000
    classDef processing fill:#98fb98,stroke:#000
    classDef output fill:#ffa07a,stroke:#000
    classDef storage fill:#dcdcdc,stroke:#000
    classDef critical fill:#ff6b6b,stroke:#000

    subgraph Input
        VD["Video Downloader"]
        PDB[("Photo Database")]
        CI["Contestant Info CSV"]
    end

    subgraph Processing
        FD{"Face Detection Engine"}
        FR{"Face Recognition Engine"}
        FP["Frame Processor"]
        DPM["Data Pipeline Manager"]
        EMB[("Embeddings Storage")]
    end

    subgraph Output
        LV[("Labeled Videos")]
        AR["Analysis Reports"]
        RS[("Results Storage")]
    end

    %% Connections
    VD --> FP
    PDB --> FR
    CI --> DPM
    FP --> FD
    FD --> FR
    FR --> DPM
    DPM --> EMB
    DPM --> LV
    DPM --> AR
    DPM --> RS

    %% Click events
    click VD "https://github.com/yellowcandle/mv-face-recognition/blob/main/videos_dl.py"
    click PDB "https://github.com/yellowcandle/mv-face-recognition/tree/main/source/photo/contestants/"
    click CI "https://github.com/yellowcandle/mv-face-recognition/blob/main/contestant_info.csv"
    click FD "https://github.com/yellowcandle/mv-face-recognition/blob/main/face_detect.py"
    click FR "https://github.com/yellowcandle/mv-face-recognition/blob/main/mv-face-recognition.py"
    click FP "https://github.com/yellowcandle/mv-face-recognition/tree/main/output_frames/"
    click LV "https://github.com/yellowcandle/mv-face-recognition/tree/main/output_mp4s/"
    click AR "https://github.com/yellowcandle/mv-face-recognition/blob/main/face_verification_results.csv"
    click RS "https://github.com/yellowcandle/mv-face-recognition/tree/main/comparison_results/"
    click EMB "https://github.com/yellowcandle/mv-face-recognition/tree/main/source/photo/contestants/"

    %% Legend
    subgraph Legend
        L1["Process"]:::processing
        L2[("Storage")]:::storage
        L3{"Engine"}:::critical
        L4["Input"]:::input
        L5["Output"]:::output
    end

    %% Styles
    class VD,CI input
    class PDB,EMB storage
    class FD,FR critical
    class FP,DPM processing
    class LV,RS storage
    class AR output
```
