# nikolasfaria/video-sharingan architecture

> Architecture diagram of the GitHub repository nikolasfaria/video-sharingan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikolasfaria/video-sharingan
- Repository: https://github.com/nikolasfaria/video-sharingan

## Overview

video-sharingan is a command-line video-analysis tool and agent skill: it turns a reference video into measured edit, camera, focus, look, and audio findings, then produces a recreation brief and comparison gates. The main workflow is orchestrated by `scripts/sharingan.py`; the README documents the stages and optional standalone commands. Source excerpts confirm several stage implementations and their inputs, but not every orchestration call, so undocumented links are omitted. Outputs are generated artifacts, not repository modules.

Main entry points: [`scripts/sharingan.py`](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/sharingan.py) (CLI workflow), [`scripts/common.py`](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/common.py) (Media helpers), [`scripts/compare.py`](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/compare.py) (Render comparison), [`scripts/brief.py`](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/brief.py) (Brief generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow orchestration"]
  node_cli["CLI workflow<br/>[sharingan.py]"]
  node_media_probe["Media probe<br/>[probe.py]"]
  node_shared_helpers["Media helpers<br/>[common.py]"]
end

subgraph group_edit_motion["Edit and motion"]
  node_cut_detection["Cut detection<br/>[cuts.py]"]
  node_camera_tracking["Camera tracking<br/>[camera_track.py]"]
  node_contact_sheets["Contact sheets<br/>[contact_sheet.py]"]
end

subgraph group_visual_audio["Visual and audio analysis"]
  node_focus_analysis["Focus and framing<br/>[focus_map.py]"]
  node_look_analysis["Optical look<br/>[look.py]"]
  node_audio_analysis["Audio analysis<br/>[audio.py]"]
end

subgraph group_deliverables["Brief and validation"]
  node_analysis_output["Analysis JSON"]
  node_brief_generator["Brief generator<br/>[brief.py]"]
  node_brief_output["Recreation brief"]
  node_comparison["Render comparison<br/>[compare.py]"]
end

node_user(("Analyst or agent"))
node_reference_video["Reference video"]
node_render_analysis["Render analysis"]
node_qc_report["QC gate report"]

node_user -->|"runs analysis"| node_cli
node_reference_video -->|"supplies video"| node_cli
node_cli -->|"probes media"| node_media_probe
node_cli -->|"detects cuts"| node_cut_detection
node_cli -->|"tracks camera"| node_camera_tracking
node_cli -->|"builds sheets"| node_contact_sheets
node_cli -->|"measures focus"| node_focus_analysis
node_cli -->|"measures look"| node_look_analysis
node_cli -->|"analyzes audio"| node_audio_analysis
node_cli -->|"writes analysis"| node_analysis_output
node_cli -->|"renders brief"| node_brief_generator
node_brief_generator -->|"reads findings"| node_analysis_output
node_brief_generator -->|"writes brief"| node_brief_output
node_user -->|"runs comparison"| node_comparison
node_comparison -->|"reads reference"| node_analysis_output
node_comparison -->|"reads render"| node_render_analysis
node_comparison -->|"reports gates"| node_qc_report
node_media_probe -->|"uses probe"| node_shared_helpers
node_cut_detection -->|"uses frame helpers"| node_shared_helpers
node_camera_tracking -->|"uses frame helpers"| node_shared_helpers
node_contact_sheets -->|"uses frame helpers"| node_shared_helpers
node_focus_analysis -->|"uses frame helpers"| node_shared_helpers
node_look_analysis -->|"uses media probe"| node_shared_helpers
node_audio_analysis -->|"uses helpers"| node_shared_helpers
node_comparison -->|"derives metrics"| node_brief_generator

click node_cli "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/sharingan.py"
click node_media_probe "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/probe.py"
click node_shared_helpers "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/common.py"
click node_cut_detection "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/cuts.py"
click node_camera_tracking "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/camera_track.py"
click node_contact_sheets "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/contact_sheet.py"
click node_focus_analysis "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/focus_map.py"
click node_look_analysis "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/look.py"
click node_audio_analysis "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/audio.py"
click node_brief_generator "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/brief.py"
click node_comparison "https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/compare.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_media_probe,node_shared_helpers toneBlue
class node_cut_detection,node_camera_tracking,node_contact_sheets toneAmber
class node_focus_analysis,node_look_analysis,node_audio_analysis toneMint
class node_analysis_output,node_brief_generator,node_brief_output,node_comparison toneRose
class node_user,node_reference_video,node_render_analysis,node_qc_report toneIndigo
```

## Components

### Workflow orchestration

- [CLI workflow](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/sharingan.py): `scripts/sharingan.py`
- [Media probe](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/probe.py): `scripts/probe.py`
- [Media helpers](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/common.py): `scripts/common.py`

### Edit and motion

- [Cut detection](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/cuts.py): `scripts/cuts.py`
- [Camera tracking](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/camera_track.py): `scripts/camera_track.py`
- [Contact sheets](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/contact_sheet.py): `scripts/contact_sheet.py`

### Visual and audio analysis

- [Focus and framing](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/focus_map.py): `scripts/focus_map.py`
- [Optical look](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/look.py): `scripts/look.py`
- [Audio analysis](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/audio.py): `scripts/audio.py`

### Brief and validation

- **Analysis JSON**
- [Brief generator](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/brief.py): `scripts/brief.py`
- **Recreation brief**
- [Render comparison](https://github.com/nikolasfaria/video-sharingan/blob/main/scripts/compare.py): `scripts/compare.py`

### Other components

- **Analyst or agent**
- **Reference video**
- **Render analysis**
- **QC gate report**

## Connections

- Analyst or agent → CLI workflow: runs analysis (evidence: `README.md`)
- Reference video → CLI workflow: supplies video (evidence: `README.md`)
- CLI workflow → Media probe: probes media (evidence: `scripts/sharingan.py`)
- CLI workflow → Cut detection: detects cuts (evidence: `scripts/sharingan.py`)
- CLI workflow → Camera tracking: tracks camera (evidence: `scripts/sharingan.py`)
- CLI workflow → Contact sheets: builds sheets (evidence: `scripts/sharingan.py`)
- CLI workflow → Focus and framing: measures focus (evidence: `README.md`)
- CLI workflow → Optical look: measures look (evidence: `README.md`)
- CLI workflow → Audio analysis: analyzes audio (evidence: `scripts/sharingan.py`)
- CLI workflow → Analysis JSON: writes analysis (evidence: `scripts/sharingan.py`)
- CLI workflow → Brief generator: renders brief (evidence: `scripts/sharingan.py`)
- Brief generator → Analysis JSON: reads findings (evidence: `scripts/brief.py`)
- Brief generator → Recreation brief: writes brief
- Analyst or agent → Render comparison: runs comparison (evidence: `README.md`)
- Render comparison → Analysis JSON: reads reference (evidence: `README.md`)
- Render comparison → Render analysis: reads render (evidence: `README.md`)
- Render comparison → QC gate report: reports gates (evidence: `README.md`)
- Media probe → Media helpers: uses probe (evidence: `scripts/probe.py`)
- Cut detection → Media helpers: uses frame helpers (evidence: `scripts/cuts.py`)
- Camera tracking → Media helpers: uses frame helpers (evidence: `scripts/camera_track.py`)
- Contact sheets → Media helpers: uses frame helpers (evidence: `scripts/contact_sheet.py`)
- Focus and framing → Media helpers: uses frame helpers (evidence: `scripts/focus_map.py`)
- Optical look → Media helpers: uses media probe (evidence: `scripts/look.py`)
- Audio analysis → Media helpers: uses helpers (evidence: `scripts/audio.py`)
- Render comparison → Brief generator: derives metrics (evidence: `scripts/compare.py`)