# mathieubartozzi/video_auto_rating architecture

> Architecture diagram of the GitHub repository mathieubartozzi/video_auto_rating, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mathieubartozzi/video_auto_rating
- Repository: https://github.com/mathieubartozzi/video_auto_rating

## Overview

##### Main Components
- Video Source: Although not directly shown in the file tree, the project expects videos to be located in a directory (e.g., data/videos) and outputs compressed videos into data/videos_compressed.
- Compression Module: Uses FFmpeg to reduce video file sizes while preserving quality.
- Metadata Extraction: A component that parses the video filename to extract the student’s first name, last name, and group.
- Transcription Module: Utilizes the Whisper model to convert the audio track from the video into text.
- Non-verbal Analysis Module: Uses MediaPipe to analyze gestures and body language.
- Audio Feature Extraction: Leverages libraries such as librosa (and possibly OpenCV for handling video data) to calculate speech rate and tonal variations.
- Evaluation Module: Uses the OpenAI API to assess the transcription based on predefined criteria.
- Results Aggregation & Export: Collects processed data and exports it as a CSV file (resultats_evaluation.csv).

##### Relationships and Data Flow
- Next, branch off to the “Metadata Extraction” process, where the system extracts student information from filename patterns.
- All output from the transcription and feature analysis modules are then sent to the “Evaluation Module” where the transcription is scored using OpenAI.
- Finally, the outputs from these modules are merged/analyzed in the “Results Aggregation” component, which culminates in exporting a CSV file with all scores and details.

##### Architectural Patterns and Design Principles
- Pipeline Architecture Pattern: The project follows a linear, step-by-step data processing pipeline.
- Modular Design: Even though implemented within one script, the distinct steps (compression, transcription, analysis, evaluation, export) should be conceptually represented as separate modules.
- Data Flow Emphasis: The design should emphasize sequential processing as well as branching for parallel analyses (e.g., non-verbal and audio analysis).

##### Technologies, Frameworks, and External Services
- FFmpeg for video compression.
- Whisper for transcription.
- MediaPipe for gesture and non-verbal analysis.
- Librosa for audio processing.
- OpenAI API for evaluation.
- Python libraries like Pandas, Numpy, and OpenCV for data manipulation and processing.
- dotenv for environment configuration (.env file containing API keys).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    A["Video Input (data/videos)"]:::input

    %% Processing Pipeline
    B["Compression Module (FFmpeg)"]:::module
    C["Metadata Extraction (Filename Parsing)"]:::module
    D["Transcription Module (Whisper)"]:::module
    E["Non-verbal Analysis (MediaPipe)"]:::module
    F["Audio Feature Extraction (Librosa/OpenCV)"]:::module
    G["Evaluation Module (OpenAI API)"]:::module

    %% Output Layer
    H["Results Aggregation & Export (CSV)"]:::output

    %% External Dependencies
    I["FFmpeg Tool"]:::external
    J["Whisper Model"]:::external
    K["MediaPipe Library"]:::external
    L["Librosa/OpenCV"]:::external
    M["OpenAI API"]:::external

    %% Data Flow
    A -->|"feeds"| B
    A -->|"raw video info"| C
    B -->|"compressed video"| D
    B -->|"compressed video"| E
    B -->|"compressed video"| F
    D -->|"transcription output"| G
    E -->|"gesture metrics"| G
    F -->|"audio features"| G
    C -->|"metadata info"| G
    G -->|"aggregated results"| H

    %% External Usage
    B -->|"uses"| I
    D -->|"uses"| J
    E -->|"uses"| K
    F -->|"uses"| L
    G -->|"calls"| M

    %% Click Events - Processing Pipeline mapped to traitement_videos.py
    click B "https://github.com/mathieubartozzi/video_auto_rating/blob/main/traitement_videos.py"
    click C "https://github.com/mathieubartozzi/video_auto_rating/blob/main/traitement_videos.py"
    click D "https://github.com/mathieubartozzi/video_auto_rating/blob/main/traitement_videos.py"
    click E "https://github.com/mathieubartozzi/video_auto_rating/blob/main/traitement_videos.py"
    click F "https://github.com/mathieubartozzi/video_auto_rating/blob/main/traitement_videos.py"
    click G "https://github.com/mathieubartozzi/video_auto_rating/blob/main/traitement_videos.py"
    click H "https://github.com/mathieubartozzi/video_auto_rating/blob/main/traitement_videos.py"

    %% Click Events - Documentation mapped to README.md
    click I "https://github.com/mathieubartozzi/video_auto_rating/blob/main/README.md"
    click J "https://github.com/mathieubartozzi/video_auto_rating/blob/main/README.md"
    click K "https://github.com/mathieubartozzi/video_auto_rating/blob/main/README.md"
    click L "https://github.com/mathieubartozzi/video_auto_rating/blob/main/README.md"
    click M "https://github.com/mathieubartozzi/video_auto_rating/blob/main/README.md"

    %% Styles
    classDef input fill:#ffe6e6,stroke:#aa0000,stroke-width:2px;
    classDef module fill:#e6f7ff,stroke:#0055aa,stroke-width:2px;
    classDef output fill:#e6ffe6,stroke:#008800,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#b58900,stroke-width:2px;
```
