# allthingsaman/clipkaro architecture

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

- Interactive diagram: https://gitdiagram.com/allthingsaman/clipkaro
- Repository: https://github.com/allthingsaman/clipkaro

## Overview

ClipKaro turns a local video or YouTube source into vertical, captioned short videos, with a live-stream mode that can post clips while a stream is running. The standard workflow fetches and transcribes media, prepares transcript parts and candidate moments, reviews and cuts selected clips, then edits and checks the results. Separate capabilities include deep clips, speech and visual cues, speaker-aware framing, and rendering. The README documents the main stages; some branches are represented by their source modules, but their internal calls were not sampled, so unsupported links are omitted.

Main entry points: [`clipper/cut.py`](https://github.com/allthingsaman/clipkaro/blob/main/clipper/cut.py) (Clip cutting), [`clipper/parts.py`](https://github.com/allthingsaman/clipkaro/blob/main/clipper/parts.py) (Transcript parts), [`clipper/edit.py`](https://github.com/allthingsaman/clipkaro/blob/main/clipper/edit.py) (Clip editing), [`clipper/fetch.py`](https://github.com/allthingsaman/clipkaro/blob/main/clipper/fetch.py) (Fetch and transcribe)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Media intake"]
  node_cli["Command workflow<br/>[run.py]"]
  node_fetch["Fetch and transcribe<br/>[fetch.py]"]
  node_live["Live clipping<br/>[live.py]"]
  node_twitch["Stream reaction hints<br/>[twitch.py]"]
end

subgraph group_discovery["Clip discovery"]
  node_parts["Transcript parts<br/>[parts.py]"]
  node_topics["Topics and candidates<br/>[topics.py]"]
  node_critic["Blind clip review<br/>[critic.py]"]
  node_deep["Deep clips<br/>[deep.py]"]
end

subgraph group_production["Clip production"]
  node_cut["Clip cutting<br/>[cut.py]"]
  node_edit["Clip editing<br/>[edit.py]"]
  node_qa["Quality checks<br/>[qa.py]"]
  node_common["Shared media utilities<br/>[common.py]"]
end

subgraph group_enhancement["Analysis and framing"]
  node_kind["Video type and breaks<br/>[kind.py]"]
  node_sound["Sound cues<br/>[sound.py]"]
  node_hints["Speech and action hints<br/>[hints.py]"]
  node_speakers["Speaker analysis<br/>[speakers.py]"]
  node_voices["Voice identity<br/>[voices.py]"]
  node_reframe["Speaker-aware reframing<br/>[reframe.py]"]
  node_facecam["Facecam detection<br/>[facecam.py]"]
  node_motion["Motion cues<br/>[motion.py]"]
end

subgraph group_delivery["Rendering and delivery"]
  node_plan["Edit plan<br/>[plan.py]"]
  node_remotion["Remotion renderer<br/>[Clip.tsx]"]
  node_post["Social posting<br/>[post.py]"]
end

node_user(("Video creator"))
node_platforms(("Posting platforms"))

node_user -->|"requests clips"| node_cli
node_cli -->|"starts intake"| node_fetch
node_fetch -->|"transcript for"| node_parts
node_parts -->|"parts read"| node_topics
node_topics -->|"candidate ideas"| node_critic
node_critic -->|"selected clips"| node_cut
node_cut -->|"cut footage"| node_edit
node_edit -->|"edited clips"| node_qa
node_cli -->|"starts live mode"| node_live
node_live -.->|"adds reaction hints"| node_twitch
node_live -->|"checks clips"| node_qa
node_qa -->|"approved clips"| node_post
node_post -->|"posts clips"| node_platforms
node_parts -->|"supports deep clips"| node_deep
node_fetch -->|"detects video type"| node_kind
node_kind -->|"detects facecam"| node_facecam
node_kind -->|"reads metadata"| node_fetch
node_parts -->|"uses transcript hints"| node_hints
node_hints -->|"loads sound cues"| node_sound
node_hints -->|"gets other voices"| node_voices
node_hints -->|"combines motion cues"| node_motion
node_cut -->|"gets source video"| node_fetch
node_cut -->|"frames shots"| node_reframe
node_cut -->|"uses speaker signals"| node_speakers
node_cut -->|"applies video rules"| node_kind
node_cut -->|"uses sound cues"| node_sound
node_edit -->|"builds edit plan"| node_plan
node_edit -->|"uses framing data"| node_reframe
node_plan -.->|"shared render plan"| node_remotion
node_parts -->|"loads sound cues"| node_sound
node_parts -->|"filters break spans"| node_kind
node_speakers -->|"speaker framing signals"| node_reframe
node_voices -->|"uses voice analysis"| node_speakers
node_reframe -->|"uses media helpers"| node_common
node_edit -->|"uses shared helpers"| node_common

click node_cli "https://github.com/allthingsaman/clipkaro/blob/main/run.py"
click node_fetch "https://github.com/allthingsaman/clipkaro/blob/main/clipper/fetch.py"
click node_live "https://github.com/allthingsaman/clipkaro/blob/main/clipper/live.py"
click node_twitch "https://github.com/allthingsaman/clipkaro/blob/main/clipper/twitch.py"
click node_parts "https://github.com/allthingsaman/clipkaro/blob/main/clipper/parts.py"
click node_topics "https://github.com/allthingsaman/clipkaro/blob/main/clipper/topics.py"
click node_critic "https://github.com/allthingsaman/clipkaro/blob/main/clipper/critic.py"
click node_deep "https://github.com/allthingsaman/clipkaro/blob/main/clipper/deep.py"
click node_cut "https://github.com/allthingsaman/clipkaro/blob/main/clipper/cut.py"
click node_edit "https://github.com/allthingsaman/clipkaro/blob/main/clipper/edit.py"
click node_qa "https://github.com/allthingsaman/clipkaro/blob/main/clipper/qa.py"
click node_kind "https://github.com/allthingsaman/clipkaro/blob/main/clipper/kind.py"
click node_sound "https://github.com/allthingsaman/clipkaro/blob/main/clipper/sound.py"
click node_hints "https://github.com/allthingsaman/clipkaro/blob/main/clipper/hints.py"
click node_speakers "https://github.com/allthingsaman/clipkaro/blob/main/clipper/speakers.py"
click node_voices "https://github.com/allthingsaman/clipkaro/blob/main/clipper/voices.py"
click node_reframe "https://github.com/allthingsaman/clipkaro/blob/main/clipper/reframe.py"
click node_facecam "https://github.com/allthingsaman/clipkaro/blob/main/clipper/facecam.py"
click node_motion "https://github.com/allthingsaman/clipkaro/blob/main/clipper/motion.py"
click node_plan "https://github.com/allthingsaman/clipkaro/blob/main/clipper/plan.py"
click node_remotion "https://github.com/allthingsaman/clipkaro/blob/main/remotion/src/Clip.tsx"
click node_post "https://github.com/allthingsaman/clipkaro/blob/main/clipper/post.py"
click node_common "https://github.com/allthingsaman/clipkaro/blob/main/clipper/common.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_fetch,node_live,node_twitch toneBlue
class node_parts,node_topics,node_critic,node_deep toneAmber
class node_cut,node_edit,node_qa,node_common toneMint
class node_kind,node_sound,node_hints,node_speakers,node_voices,node_reframe,node_facecam,node_motion toneRose
class node_plan,node_remotion,node_post,node_user,node_platforms toneIndigo
```

## Components

### Media intake

- [Command workflow](https://github.com/allthingsaman/clipkaro/blob/main/run.py): `run.py`
- [Fetch and transcribe](https://github.com/allthingsaman/clipkaro/blob/main/clipper/fetch.py): `clipper/fetch.py`
- [Live clipping](https://github.com/allthingsaman/clipkaro/blob/main/clipper/live.py): `clipper/live.py`
- [Stream reaction hints](https://github.com/allthingsaman/clipkaro/blob/main/clipper/twitch.py): `clipper/twitch.py`

### Clip discovery

- [Transcript parts](https://github.com/allthingsaman/clipkaro/blob/main/clipper/parts.py): `clipper/parts.py`
- [Topics and candidates](https://github.com/allthingsaman/clipkaro/blob/main/clipper/topics.py): `clipper/topics.py`
- [Blind clip review](https://github.com/allthingsaman/clipkaro/blob/main/clipper/critic.py): `clipper/critic.py`
- [Deep clips](https://github.com/allthingsaman/clipkaro/blob/main/clipper/deep.py): `clipper/deep.py`

### Clip production

- [Clip cutting](https://github.com/allthingsaman/clipkaro/blob/main/clipper/cut.py): `clipper/cut.py`
- [Clip editing](https://github.com/allthingsaman/clipkaro/blob/main/clipper/edit.py): `clipper/edit.py`
- [Quality checks](https://github.com/allthingsaman/clipkaro/blob/main/clipper/qa.py): `clipper/qa.py`
- [Shared media utilities](https://github.com/allthingsaman/clipkaro/blob/main/clipper/common.py): `clipper/common.py`

### Analysis and framing

- [Video type and breaks](https://github.com/allthingsaman/clipkaro/blob/main/clipper/kind.py): `clipper/kind.py`
- [Sound cues](https://github.com/allthingsaman/clipkaro/blob/main/clipper/sound.py): `clipper/sound.py`
- [Speech and action hints](https://github.com/allthingsaman/clipkaro/blob/main/clipper/hints.py): `clipper/hints.py`
- [Speaker analysis](https://github.com/allthingsaman/clipkaro/blob/main/clipper/speakers.py): `clipper/speakers.py`
- [Voice identity](https://github.com/allthingsaman/clipkaro/blob/main/clipper/voices.py): `clipper/voices.py`
- [Speaker-aware reframing](https://github.com/allthingsaman/clipkaro/blob/main/clipper/reframe.py): `clipper/reframe.py`
- [Facecam detection](https://github.com/allthingsaman/clipkaro/blob/main/clipper/facecam.py): `clipper/facecam.py`
- [Motion cues](https://github.com/allthingsaman/clipkaro/blob/main/clipper/motion.py): `clipper/motion.py`

### Rendering and delivery

- [Edit plan](https://github.com/allthingsaman/clipkaro/blob/main/clipper/plan.py): `clipper/plan.py`
- [Remotion renderer](https://github.com/allthingsaman/clipkaro/blob/main/remotion/src/Clip.tsx): `remotion/src/Clip.tsx`
- [Social posting](https://github.com/allthingsaman/clipkaro/blob/main/clipper/post.py): `clipper/post.py`

### Other components

- **Video creator**
- **Posting platforms**

## Connections

- Video creator → Command workflow: requests clips
- Command workflow → Fetch and transcribe: starts intake
- Fetch and transcribe → Transcript parts: transcript for
- Transcript parts → Topics and candidates: parts read (evidence: `clipper/topics.py`)
- Topics and candidates → Blind clip review: candidate ideas (evidence: `clipper/critic.py`)
- Blind clip review → Clip cutting: selected clips (evidence: `clipper/critic.py`)
- Clip cutting → Clip editing: cut footage (evidence: `clipper/edit.py`)
- Clip editing → Quality checks: edited clips
- Command workflow → Live clipping: starts live mode
- Live clipping → Stream reaction hints: adds reaction hints
- Live clipping → Quality checks: checks clips
- Quality checks → Social posting: approved clips
- Social posting → Posting platforms: posts clips
- Transcript parts → Deep clips: supports deep clips (evidence: `clipper/deep.py`)
- Fetch and transcribe → Video type and breaks: detects video type (evidence: `clipper/fetch.py`)
- Video type and breaks → Facecam detection: detects facecam (evidence: `clipper/kind.py`)
- Video type and breaks → Fetch and transcribe: reads metadata (evidence: `clipper/kind.py`)
- Transcript parts → Speech and action hints: uses transcript hints (evidence: `clipper/parts.py`)
- Speech and action hints → Sound cues: loads sound cues (evidence: `clipper/hints.py`)
- Speech and action hints → Voice identity: gets other voices (evidence: `clipper/hints.py`)
- Speech and action hints → Motion cues: combines motion cues (evidence: `clipper/hints.py`)
- Clip cutting → Fetch and transcribe: gets source video (evidence: `clipper/cut.py`)
- Clip cutting → Speaker-aware reframing: frames shots (evidence: `clipper/cut.py`)
- Clip cutting → Speaker analysis: uses speaker signals (evidence: `clipper/cut.py`)
- Clip cutting → Video type and breaks: applies video rules (evidence: `clipper/cut.py`)
- Clip cutting → Sound cues: uses sound cues (evidence: `clipper/cut.py`)
- Clip editing → Edit plan: builds edit plan (evidence: `clipper/edit.py`)
- Clip editing → Speaker-aware reframing: uses framing data (evidence: `clipper/edit.py`)
- Edit plan → Remotion renderer: shared render plan (evidence: `clipper/plan.py`)
- Transcript parts → Sound cues: loads sound cues (evidence: `clipper/parts.py`)
- Transcript parts → Video type and breaks: filters break spans (evidence: `clipper/parts.py`)
- Speaker analysis → Speaker-aware reframing: speaker framing signals (evidence: `clipper/speakers.py`)
- Voice identity → Speaker analysis: uses voice analysis (evidence: `clipper/voices.py`)
- Speaker-aware reframing → Shared media utilities: uses media helpers (evidence: `clipper/reframe.py`)
- Clip editing → Shared media utilities: uses shared helpers (evidence: `clipper/edit.py`)
