# akirco/vt architecture

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

- Interactive diagram: https://gitdiagram.com/akirco/vt
- Repository: https://github.com/akirco/vt

## Overview

vt is a terminal media player whose main workflow parses CLI options, selects an output protocol, then loads an image or decodes video (including piped input) and renders frames in the terminal. Video playback also handles optional audio and timing; image loading can fall back to FFmpeg. The rendering layer dispatches to several terminal graphics encoders. The README documents an optional Ratatui image widget and optional sixel-rs backend; their paths are shown, but unsampled wiring is not expanded.

Main entry points: [`src/encoder.rs`](https://github.com/akirco/vt/blob/main/src/encoder.rs) (Encoder dispatch), [`src/video.rs`](https://github.com/akirco/vt/blob/main/src/video.rs) (Video input), [`src/player.rs`](https://github.com/akirco/vt/blob/main/src/player.rs) (Playback loop), [`src/main.rs`](https://github.com/akirco/vt/blob/main/src/main.rs) (CLI workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_main["CLI workflow<br/>[main.rs]"]
  node_args["Arguments<br/>[args.rs]"]
  node_config["Playback config<br/>[config.rs]"]
  node_protocol["Protocol selection<br/>[protocol.rs]"]
end

subgraph group_media["Media playback"]
  node_image["Image loading<br/>[image.rs]"]
  node_video["Video input<br/>[video.rs]"]
  node_decoder["Video decoder<br/>[video.rs]"]
  node_player["Playback loop<br/>[player.rs]"]
  node_audio["Audio playback<br/>[audio.rs]"]
end

subgraph group_render["Terminal rendering"]
  node_terminal_ops["Sizing and terminal<br/>[terminal.rs]"]
  node_encoder["Encoder dispatch<br/>[encoder.rs]"]
  node_sixel["Sixel encoder<br/>[sixel.rs]"]
  node_kitty["Kitty encoder<br/>[kitty.rs]"]
  node_halfblock["HalfBlock encoder<br/>[halfblock.rs]"]
  node_braille["Braille encoder<br/>[braille.rs]"]
  node_ascii["ASCII encoder<br/>[ascii.rs]"]
end

subgraph group_optional["Optional integrations"]
  node_ratatui["Ratatui widget<br/>[ratatui.rs]"]
  node_sixelrs["Sixel-rs backend<br/>[sixel_rs.rs]"]
end

node_user(("User / pipe"))
node_terminal["Terminal"]
node_audio_device["Audio output"]
node_ffmpeg["FFmpeg"]

node_user -->|"provides input"| node_main
node_main -->|"parses options"| node_args
node_args -->|"creates config"| node_config
node_main -->|"selects protocol"| node_protocol
node_main -->|"loads image"| node_image
node_main -->|"runs video"| node_video
node_image -->|"falls back"| node_video
node_video -->|"opens media"| node_ffmpeg
node_video -->|"creates decoder"| node_decoder
node_video -->|"fits dimensions"| node_terminal_ops
node_video -->|"initializes audio"| node_audio
node_video -->|"starts playback"| node_player
node_player -->|"decodes packets"| node_decoder
node_player -->|"encodes frames"| node_encoder
node_player -->|"sends samples"| node_audio
node_player -->|"controls display"| node_terminal_ops
node_audio -->|"plays samples"| node_audio_device
node_encoder -->|"dispatches Sixel"| node_sixel
node_encoder -->|"dispatches Kitty"| node_kitty
node_encoder -->|"dispatches HalfBlock"| node_halfblock
node_encoder -->|"dispatches Braille"| node_braille
node_encoder -->|"dispatches ASCII"| node_ascii
node_encoder -->|"writes render stream"| node_terminal
node_player -->|"writes playback"| node_terminal
node_ratatui -->|"encodes widget image"| node_encoder
node_ratatui -->|"writes widget output"| node_terminal
node_encoder -.->|"optional backend"| node_sixelrs

click node_main "https://github.com/akirco/vt/blob/main/src/main.rs"
click node_args "https://github.com/akirco/vt/blob/main/src/args.rs"
click node_config "https://github.com/akirco/vt/blob/main/src/config.rs"
click node_protocol "https://github.com/akirco/vt/blob/main/src/protocol.rs"
click node_image "https://github.com/akirco/vt/blob/main/src/image.rs"
click node_video "https://github.com/akirco/vt/blob/main/src/video.rs"
click node_decoder "https://github.com/akirco/vt/blob/main/src/video.rs"
click node_player "https://github.com/akirco/vt/blob/main/src/player.rs"
click node_audio "https://github.com/akirco/vt/blob/main/src/audio.rs"
click node_terminal_ops "https://github.com/akirco/vt/blob/main/src/terminal.rs"
click node_encoder "https://github.com/akirco/vt/blob/main/src/encoder.rs"
click node_sixel "https://github.com/akirco/vt/blob/main/src/sixel.rs"
click node_kitty "https://github.com/akirco/vt/blob/main/src/kitty.rs"
click node_halfblock "https://github.com/akirco/vt/blob/main/src/halfblock.rs"
click node_braille "https://github.com/akirco/vt/blob/main/src/braille.rs"
click node_ascii "https://github.com/akirco/vt/blob/main/src/ascii.rs"
click node_ratatui "https://github.com/akirco/vt/blob/main/src/ratatui.rs"
click node_sixelrs "https://github.com/akirco/vt/blob/main/src/sixel_rs.rs"

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_main,node_args,node_config,node_protocol,node_user toneBlue
class node_image,node_video,node_decoder,node_player,node_audio toneAmber
class node_terminal_ops,node_encoder,node_sixel,node_kitty,node_halfblock,node_braille,node_ascii toneMint
class node_ratatui,node_sixelrs toneRose
class node_terminal,node_audio_device,node_ffmpeg toneIndigo
```

## Components

### Application entry

- [CLI workflow](https://github.com/akirco/vt/blob/main/src/main.rs): `src/main.rs`
- [Arguments](https://github.com/akirco/vt/blob/main/src/args.rs): `src/args.rs`
- [Playback config](https://github.com/akirco/vt/blob/main/src/config.rs): `src/config.rs`
- [Protocol selection](https://github.com/akirco/vt/blob/main/src/protocol.rs): `src/protocol.rs`

### Media playback

- [Image loading](https://github.com/akirco/vt/blob/main/src/image.rs): `src/image.rs`
- [Video input](https://github.com/akirco/vt/blob/main/src/video.rs): `src/video.rs`
- [Video decoder](https://github.com/akirco/vt/blob/main/src/video.rs): `src/video.rs`
- [Playback loop](https://github.com/akirco/vt/blob/main/src/player.rs): `src/player.rs`
- [Audio playback](https://github.com/akirco/vt/blob/main/src/audio.rs): `src/audio.rs`

### Terminal rendering

- [Sizing and terminal](https://github.com/akirco/vt/blob/main/src/terminal.rs): `src/terminal.rs`
- [Encoder dispatch](https://github.com/akirco/vt/blob/main/src/encoder.rs): `src/encoder.rs`
- [Sixel encoder](https://github.com/akirco/vt/blob/main/src/sixel.rs): `src/sixel.rs`
- [Kitty encoder](https://github.com/akirco/vt/blob/main/src/kitty.rs): `src/kitty.rs`
- [HalfBlock encoder](https://github.com/akirco/vt/blob/main/src/halfblock.rs): `src/halfblock.rs`
- [Braille encoder](https://github.com/akirco/vt/blob/main/src/braille.rs): `src/braille.rs`
- [ASCII encoder](https://github.com/akirco/vt/blob/main/src/ascii.rs): `src/ascii.rs`

### Optional integrations

- [Ratatui widget](https://github.com/akirco/vt/blob/main/src/ratatui.rs): `src/ratatui.rs`
- [Sixel-rs backend](https://github.com/akirco/vt/blob/main/src/sixel_rs.rs): `src/sixel_rs.rs`

### Other components

- **User / pipe**
- **Terminal**
- **Audio output**
- **FFmpeg**

## Connections

- User / pipe → CLI workflow: provides input
- CLI workflow → Arguments: parses options
- Arguments → Playback config: creates config
- CLI workflow → Protocol selection: selects protocol
- CLI workflow → Image loading: loads image
- CLI workflow → Video input: runs video
- Image loading → Video input: falls back
- Video input → FFmpeg: opens media
- Video input → Video decoder: creates decoder
- Video input → Sizing and terminal: fits dimensions
- Video input → Audio playback: initializes audio
- Video input → Playback loop: starts playback
- Playback loop → Video decoder: decodes packets
- Playback loop → Encoder dispatch: encodes frames
- Playback loop → Audio playback: sends samples
- Playback loop → Sizing and terminal: controls display
- Audio playback → Audio output: plays samples
- Encoder dispatch → Sixel encoder: dispatches Sixel
- Encoder dispatch → Kitty encoder: dispatches Kitty
- Encoder dispatch → HalfBlock encoder: dispatches HalfBlock
- Encoder dispatch → Braille encoder: dispatches Braille
- Encoder dispatch → ASCII encoder: dispatches ASCII
- Encoder dispatch → Terminal: writes render stream
- Playback loop → Terminal: writes playback
- Ratatui widget → Encoder dispatch: encodes widget image
- Ratatui widget → Terminal: writes widget output
- Encoder dispatch → Sixel-rs backend: optional backend