# z4pdy/ascii-media-renderer architecture

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

- Interactive diagram: https://gitdiagram.com/z4pdy/ascii-media-renderer
- Repository: https://github.com/z4pdy/ascii-media-renderer

## Overview

ASCII Media Renderer is a Java CLI that turns still images, video, live camera frames, and YouTube streams into terminal ASCII art, with optional audio. The main workflow parses a mode and display flags, obtains terminal dimensions, then loads or resolves a media source and dispatches rendering. Video playback converts frames and synchronizes optional audio; image conversion resizes, optionally adjusts contrast, and maps brightness to characters. The README documents YouTube search and camera support; source excerpts show their CLI dispatch. External-tool and terminal interactions are shown where source supports them.

Main entry points: [`app/src/main/java/com/zapdy/asciimediarenderer/Main.java`](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/Main.java) (Mode dispatcher), [`app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java`](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java) (Media renderer), [`app/src/main/java/com/zapdy/asciimediarenderer/YouTubeUtils.java`](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/YouTubeUtils.java) (YouTube resolver), [`app/src/main/java/com/zapdy/asciimediarenderer/AudioPlayer.java`](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/AudioPlayer.java) (Audio playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI orchestration"]
  node_main["Mode dispatcher<br/>[Main.java]"]
  node_terminal["Terminal sizing<br/>[TerminalUtils.java]"]
end

subgraph group_render["Media rendering"]
  node_renderer["Media renderer"]
  node_imageutils["Image conversion"]
  node_audio["Audio playback<br/>[AudioPlayer.java]"]
end

subgraph group_youtube["YouTube resolution"]
  node_streamurls["Stream URL record"]
  node_youtubeutils["YouTube resolver<br/>[YouTubeUtils.java]"]
end

node_user(("CLI user"))
node_media["Media source"]
node_ytdlp["yt-dlp process"]
node_terminalout(("Terminal display"))
node_audioout(("Audio device"))

node_user -->|"selects mode"| node_main
node_main -->|"gets dimensions"| node_terminal
node_media -->|"provides input"| node_main
node_main -->|"dispatches rendering"| node_renderer
node_main -->|"resolves search"| node_youtubeutils
node_main -->|"gets stream URLs"| node_youtubeutils
node_youtubeutils -->|"runs"| node_ytdlp
node_youtubeutils -->|"returns URLs"| node_streamurls
node_renderer -->|"converts images"| node_imageutils
node_renderer -->|"plays audio"| node_audio
node_renderer -->|"clears display"| node_terminal
node_renderer -->|"writes frames"| node_terminalout
node_audio -->|"writes samples"| node_audioout

click node_main "https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/Main.java"
click node_terminal "https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/TerminalUtils.java"
click node_renderer "https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java"
click node_imageutils "https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/AsciiImageUtils.java"
click node_audio "https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/AudioPlayer.java"
click node_streamurls "https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/YouTubeDirectStreamUrls.java"
click node_youtubeutils "https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/YouTubeUtils.java"

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_terminal,node_user toneBlue
class node_renderer,node_imageutils,node_audio toneAmber
class node_streamurls,node_youtubeutils toneMint
class node_media,node_ytdlp,node_terminalout,node_audioout toneIndigo
```

## Components

### CLI orchestration

- [Mode dispatcher](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/Main.java): `app/src/main/java/com/zapdy/asciimediarenderer/Main.java`
- [Terminal sizing](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/TerminalUtils.java): `app/src/main/java/com/zapdy/asciimediarenderer/TerminalUtils.java`

### Media rendering

- [Media renderer](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java): `app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java`
- [Image conversion](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/AsciiImageUtils.java): `app/src/main/java/com/zapdy/asciimediarenderer/AsciiImageUtils.java`
- [Audio playback](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/AudioPlayer.java): `app/src/main/java/com/zapdy/asciimediarenderer/AudioPlayer.java`

### YouTube resolution

- [Stream URL record](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/YouTubeDirectStreamUrls.java): `app/src/main/java/com/zapdy/asciimediarenderer/YouTubeDirectStreamUrls.java`
- [YouTube resolver](https://github.com/z4pdy/ascii-media-renderer/blob/main/app/src/main/java/com/zapdy/asciimediarenderer/YouTubeUtils.java): `app/src/main/java/com/zapdy/asciimediarenderer/YouTubeUtils.java`

### Other components

- **CLI user**
- **Media source**
- **yt-dlp process**
- **Terminal display**
- **Audio device**

## Connections

- CLI user → Mode dispatcher: selects mode (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/Main.java`)
- Mode dispatcher → Terminal sizing: gets dimensions (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/Main.java`)
- Media source → Mode dispatcher: provides input (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/Main.java`)
- Mode dispatcher → Media renderer: dispatches rendering (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/Main.java`)
- Mode dispatcher → YouTube resolver: resolves search (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/Main.java`)
- Mode dispatcher → YouTube resolver: gets stream URLs (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/Main.java`)
- YouTube resolver → yt-dlp process: runs (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/YouTubeUtils.java`)
- YouTube resolver → Stream URL record: returns URLs (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/YouTubeUtils.java`)
- Media renderer → Image conversion: converts images (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java`)
- Media renderer → Audio playback: plays audio (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java`)
- Media renderer → Terminal sizing: clears display (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java`)
- Media renderer → Terminal display: writes frames (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/AsciiMediaRenderer.java`)
- Audio playback → Audio device: writes samples (evidence: `app/src/main/java/com/zapdy/asciimediarenderer/AudioPlayer.java`)