# henrisallila/hccapet architecture

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

- Interactive diagram: https://gitdiagram.com/henrisallila/hccapet
- Repository: https://github.com/henrisallila/hccapet

## Overview

HccaPET is a command-line MP4-to-PETSCII-art video converter. The workflow opens and samples source frames, converts each selected frame to a configurable character grid and palette, writes the video, then optionally muxes the original audio with ffmpeg. The graph separates orchestration, conversion, and C64 visual data. The README documents palette modes and audio fallback; implementation details are based on the shown source excerpts.

Main entry points: [`converter.py`](https://github.com/henrisallila/hccapet/blob/main/converter.py) (Frame converter), [`hccapet.py`](https://github.com/henrisallila/hccapet/blob/main/hccapet.py) (Conversion CLI), [`petscii_data.py`](https://github.com/henrisallila/hccapet/blob/main/petscii_data.py) (PETSCII font)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Video workflow"]
  node_cli["Conversion CLI<br/>[hccapet.py]"]
  node_frame_source["Frame reader<br/>[hccapet.py]"]
  node_frame_schedule["Frame selection<br/>[hccapet.py]"]
  node_video_writer["Video writer<br/>[hccapet.py]"]
  node_audio_mux["Audio mux<br/>[hccapet.py]"]
end

subgraph group_engine["PETSCII conversion"]
  node_converter["Frame converter<br/>[converter.py]"]
  node_palette_match["Palette matching<br/>[converter.py]"]
  node_cell_match["Character matching<br/>[converter.py]"]
  node_frame_render["Frame rendering<br/>[converter.py]"]
end

subgraph group_visuals["C64 visual data"]
  node_font_data["PETSCII font<br/>[petscii_data.py]"]
  node_palette_data["C64 palette<br/>[petscii_data.py]"]
end

node_user(("CLI user"))
node_source_video["Input video"]
node_ffmpeg["ffmpeg"]
node_output_video["Output video"]

node_user -->|"runs conversion"| node_cli
node_source_video -->|"video frames"| node_frame_source
node_cli -->|"opens input"| node_frame_source
node_frame_source -->|"reads frames"| node_frame_schedule
node_cli -->|"sets output rate"| node_frame_schedule
node_frame_schedule -->|"converts selected frames"| node_converter
node_cli -->|"configures palette"| node_converter
node_converter -->|"maps pixel colors"| node_palette_match
node_converter -->|"matches characters"| node_cell_match
node_converter -->|"renders cells"| node_frame_render
node_converter -->|"loads bitmaps"| node_font_data
node_converter -->|"loads colors"| node_palette_data
node_frame_render -->|"returns rendered frame"| node_video_writer
node_cli -->|"writes frames"| node_video_writer
node_video_writer -->|"temporary video"| node_audio_mux
node_source_video -->|"source audio"| node_audio_mux
node_audio_mux -->|"runs mux command"| node_ffmpeg
node_audio_mux -->|"saves muxed or silent video"| node_output_video

click node_cli "https://github.com/henrisallila/hccapet/blob/main/hccapet.py"
click node_frame_source "https://github.com/henrisallila/hccapet/blob/main/hccapet.py"
click node_frame_schedule "https://github.com/henrisallila/hccapet/blob/main/hccapet.py"
click node_video_writer "https://github.com/henrisallila/hccapet/blob/main/hccapet.py"
click node_audio_mux "https://github.com/henrisallila/hccapet/blob/main/hccapet.py"
click node_converter "https://github.com/henrisallila/hccapet/blob/main/converter.py"
click node_palette_match "https://github.com/henrisallila/hccapet/blob/main/converter.py"
click node_cell_match "https://github.com/henrisallila/hccapet/blob/main/converter.py"
click node_frame_render "https://github.com/henrisallila/hccapet/blob/main/converter.py"
click node_font_data "https://github.com/henrisallila/hccapet/blob/main/petscii_data.py"
click node_palette_data "https://github.com/henrisallila/hccapet/blob/main/petscii_data.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_frame_source,node_frame_schedule,node_video_writer,node_audio_mux,node_user toneBlue
class node_converter,node_palette_match,node_cell_match,node_frame_render toneAmber
class node_font_data,node_palette_data toneMint
class node_source_video,node_ffmpeg,node_output_video toneIndigo
```

## Components

### Video workflow

- [Conversion CLI](https://github.com/henrisallila/hccapet/blob/main/hccapet.py): `hccapet.py`
- [Frame reader](https://github.com/henrisallila/hccapet/blob/main/hccapet.py): `hccapet.py`
- [Frame selection](https://github.com/henrisallila/hccapet/blob/main/hccapet.py): `hccapet.py`
- [Video writer](https://github.com/henrisallila/hccapet/blob/main/hccapet.py): `hccapet.py`
- [Audio mux](https://github.com/henrisallila/hccapet/blob/main/hccapet.py): `hccapet.py`

### PETSCII conversion

- [Frame converter](https://github.com/henrisallila/hccapet/blob/main/converter.py): `converter.py`
- [Palette matching](https://github.com/henrisallila/hccapet/blob/main/converter.py): `converter.py`
- [Character matching](https://github.com/henrisallila/hccapet/blob/main/converter.py): `converter.py`
- [Frame rendering](https://github.com/henrisallila/hccapet/blob/main/converter.py): `converter.py`

### C64 visual data

- [PETSCII font](https://github.com/henrisallila/hccapet/blob/main/petscii_data.py): `petscii_data.py`
- [C64 palette](https://github.com/henrisallila/hccapet/blob/main/petscii_data.py): `petscii_data.py`

### Other components

- **CLI user**
- **Input video**
- **ffmpeg**
- **Output video**

## Connections

- CLI user → Conversion CLI: runs conversion (evidence: `README.md`)
- Input video → Frame reader: video frames (evidence: `hccapet.py`)
- Conversion CLI → Frame reader: opens input (evidence: `hccapet.py`)
- Frame reader → Frame selection: reads frames (evidence: `hccapet.py`)
- Conversion CLI → Frame selection: sets output rate (evidence: `hccapet.py`)
- Frame selection → Frame converter: converts selected frames (evidence: `hccapet.py`)
- Conversion CLI → Frame converter: configures palette (evidence: `hccapet.py`)
- Frame converter → Palette matching: maps pixel colors (evidence: `converter.py`)
- Frame converter → Character matching: matches characters (evidence: `converter.py`)
- Frame converter → Frame rendering: renders cells (evidence: `converter.py`)
- Frame converter → PETSCII font: loads bitmaps (evidence: `converter.py`)
- Frame converter → C64 palette: loads colors (evidence: `converter.py`)
- Frame rendering → Video writer: returns rendered frame (evidence: `hccapet.py`)
- Conversion CLI → Video writer: writes frames (evidence: `hccapet.py`)
- Video writer → Audio mux: temporary video (evidence: `hccapet.py`)
- Input video → Audio mux: source audio (evidence: `hccapet.py`)
- Audio mux → ffmpeg: runs mux command (evidence: `hccapet.py`)
- Audio mux → Output video: saves muxed or silent video (evidence: `hccapet.py`)
