# lekhanj/ascii-player architecture

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

- Interactive diagram: https://gitdiagram.com/lekhanj/ascii-player
- Repository: https://github.com/lekhanj/ascii-player

## Overview

ASCII Video Player accepts a video path, extracts PNG frames with FFmpeg, decodes each PNG through its zlib/DEFLATE data into pixels, converts pixels to colored ASCII, and plays frames in the terminal. The decoder’s custom Huffman and DEFLATE behavior is implemented within one module; BitReader is the sampled internal layer. The README documents dynamic and fixed Huffman support. The graph follows sampled call sites; internal PNG parsing details are not split into separate components.

Main entry points: [`src/index.ts`](https://github.com/lekhanj/ascii-player/blob/main/src/index.ts) (CLI entry), [`src/player.ts`](https://github.com/lekhanj/ascii-player/blob/main/src/player.ts) (Frame player), [`src/extract.ts`](https://github.com/lekhanj/ascii-player/blob/main/src/extract.ts) (Frame extraction), [`src/renderframe.ts`](https://github.com/lekhanj/ascii-player/blob/main/src/renderframe.ts) (Frame conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["CLI orchestration"]
  node_cli["CLI entry<br/>[index.ts]"]
end

subgraph group_extraction["Frame extraction"]
  node_ffmpeg_check["FFmpeg check<br/>[ffmpeg.ts]"]
  node_extract["Frame extraction<br/>[extract.ts]"]
end

subgraph group_decoding["PNG decoding"]
  node_decoder["PNG zlib DEFLATE decoder<br/>[decoder.ts]"]
  node_bitreader["Bit reader<br/>[bitreader.ts]"]
end

subgraph group_playback["Terminal playback"]
  node_player["Frame player<br/>[player.ts]"]
  node_render_frame["Frame conversion<br/>[renderframe.ts]"]
  node_renderer["ASCII color renderer<br/>[renderer.ts]"]
end

node_user(("Video user"))
node_ffmpeg["FFmpeg"]
node_frames["PNG frames"]
node_terminal(("Terminal"))

node_user -->|"provides video"| node_cli
node_cli -->|"checks availability"| node_ffmpeg_check
node_ffmpeg_check -->|"probes version"| node_ffmpeg
node_cli -->|"extracts frames"| node_extract
node_extract -->|"runs extraction"| node_ffmpeg
node_extract -->|"writes PNGs"| node_frames
node_cli -->|"starts playback"| node_player
node_player -->|"reads PNGs"| node_frames
node_player -->|"renders each frame"| node_render_frame
node_render_frame -->|"decodes PNG"| node_decoder
node_decoder -->|"reads bits"| node_bitreader
node_render_frame -->|"renders pixels"| node_renderer
node_player -->|"writes frames"| node_terminal

click node_cli "https://github.com/lekhanj/ascii-player/blob/main/src/index.ts"
click node_ffmpeg_check "https://github.com/lekhanj/ascii-player/blob/main/src/ffmpeg.ts"
click node_extract "https://github.com/lekhanj/ascii-player/blob/main/src/extract.ts"
click node_player "https://github.com/lekhanj/ascii-player/blob/main/src/player.ts"
click node_render_frame "https://github.com/lekhanj/ascii-player/blob/main/src/renderframe.ts"
click node_decoder "https://github.com/lekhanj/ascii-player/blob/main/src/decoder.ts"
click node_bitreader "https://github.com/lekhanj/ascii-player/blob/main/src/bitreader.ts"
click node_renderer "https://github.com/lekhanj/ascii-player/blob/main/src/renderer.ts"

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_user toneBlue
class node_ffmpeg_check,node_extract toneAmber
class node_decoder,node_bitreader toneMint
class node_player,node_render_frame,node_renderer toneRose
class node_ffmpeg,node_frames,node_terminal toneIndigo
```

## Components

### CLI orchestration

- [CLI entry](https://github.com/lekhanj/ascii-player/blob/main/src/index.ts): `src/index.ts`

### Frame extraction

- [FFmpeg check](https://github.com/lekhanj/ascii-player/blob/main/src/ffmpeg.ts): `src/ffmpeg.ts`
- [Frame extraction](https://github.com/lekhanj/ascii-player/blob/main/src/extract.ts): `src/extract.ts`

### PNG decoding

- [PNG zlib DEFLATE decoder](https://github.com/lekhanj/ascii-player/blob/main/src/decoder.ts): `src/decoder.ts`
- [Bit reader](https://github.com/lekhanj/ascii-player/blob/main/src/bitreader.ts): `src/bitreader.ts`

### Terminal playback

- [Frame player](https://github.com/lekhanj/ascii-player/blob/main/src/player.ts): `src/player.ts`
- [Frame conversion](https://github.com/lekhanj/ascii-player/blob/main/src/renderframe.ts): `src/renderframe.ts`
- [ASCII color renderer](https://github.com/lekhanj/ascii-player/blob/main/src/renderer.ts): `src/renderer.ts`

### Other components

- **Video user**
- **FFmpeg**
- **PNG frames**
- **Terminal**

## Connections

- Video user → CLI entry: provides video
- CLI entry → FFmpeg check: checks availability
- FFmpeg check → FFmpeg: probes version
- CLI entry → Frame extraction: extracts frames
- Frame extraction → FFmpeg: runs extraction
- Frame extraction → PNG frames: writes PNGs
- CLI entry → Frame player: starts playback
- Frame player → PNG frames: reads PNGs
- Frame player → Frame conversion: renders each frame
- Frame conversion → PNG zlib DEFLATE decoder: decodes PNG
- PNG zlib DEFLATE decoder → Bit reader: reads bits
- Frame conversion → ASCII color renderer: renders pixels
- Frame player → Terminal: writes frames