# joaquinruiz/miscoshorts-ai architecture

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

- Interactive diagram: https://gitdiagram.com/joaquinruiz/miscoshorts-ai
- Repository: https://github.com/joaquinruiz/miscoshorts-ai

## Overview

Miscoshorts is a command-line YouTube Shorts generator. The user supplies a video URL, then the main script downloads the video, transcribes it, asks Gemini to recommend a segment, and lets the user accept or edit its timestamps. It crops the selected footage to vertical format, adds subtitles, and renders an MP4. The README documents these capabilities, while the sampled source shows the main orchestration and subtitle implementation; dependency internals are not included.

Main entry points: [`maker.py`](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py) (Shorts workflow), [`cerebro_gemini.py`](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/cerebro_gemini.py) (Segment analysis client), [`subtitulos.py`](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/subtitulos.py) (Subtitle composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow"]
  node_main["Shorts workflow<br/>[maker.py]"]
  node_download["Video download<br/>[maker.py]"]
  node_transcribe["Audio transcription<br/>[maker.py]"]
  node_transcript["Timestamped transcript"]
  node_parse["Suggestion parsing<br/>[maker.py]"]
  node_confirm["Segment confirmation<br/>[maker.py]"]
end

subgraph group_ai["AI Analysis"]
  node_gemini_client["Segment analysis client<br/>[cerebro_gemini.py]"]
  node_gemini["Gemini"]
end

subgraph group_editing["Video Editing"]
  node_crop["Vertical crop<br/>[maker.py]"]
  node_subtitles["Subtitle composition<br/>[subtitulos.py]"]
  node_render["MP4 rendering<br/>[maker.py]"]
  node_output["Short video"]
end

node_user(("User"))
node_youtube(("YouTube"))

node_user -->|"runs"| node_main
node_youtube -->|"provides video"| node_download
node_main -->|"downloads"| node_download
node_main -->|"transcribes"| node_transcribe
node_transcribe -->|"writes transcript"| node_transcript
node_main -->|"requests analysis"| node_gemini_client
node_gemini_client -->|"sends prompt"| node_gemini
node_gemini -->|"returns suggestion"| node_gemini_client
node_main -->|"parses suggestion"| node_parse
node_main -->|"requests choice"| node_confirm
node_user -->|"chooses timestamps"| node_confirm
node_main -->|"crops segment"| node_crop
node_main -->|"adds subtitles"| node_subtitles
node_main -->|"renders video"| node_render
node_render -->|"writes MP4"| node_output

click node_main "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py"
click node_download "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py"
click node_transcribe "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py"
click node_gemini_client "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/cerebro_gemini.py"
click node_parse "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py"
click node_confirm "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py"
click node_crop "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py"
click node_subtitles "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/subtitulos.py"
click node_render "https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.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_main,node_download,node_transcribe,node_transcript,node_parse,node_confirm,node_user toneBlue
class node_gemini_client,node_gemini toneAmber
class node_crop,node_subtitles,node_render,node_output toneMint
class node_youtube toneIndigo
```

## Components

### Workflow

- [Shorts workflow](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py): `maker.py`
- [Video download](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py): `maker.py`
- [Audio transcription](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py): `maker.py`
- **Timestamped transcript**
- [Suggestion parsing](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py): `maker.py`
- [Segment confirmation](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py): `maker.py`

### AI Analysis

- [Segment analysis client](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/cerebro_gemini.py): `cerebro_gemini.py`
- **Gemini**

### Video Editing

- [Vertical crop](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py): `maker.py`
- [Subtitle composition](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/subtitulos.py): `subtitulos.py`
- [MP4 rendering](https://github.com/joaquinruiz/miscoshorts-ai/blob/main/maker.py): `maker.py`
- **Short video**

### Other components

- **User**
- **YouTube**

## Connections

- User → Shorts workflow: runs
- YouTube → Video download: provides video
- Shorts workflow → Video download: downloads
- Shorts workflow → Audio transcription: transcribes
- Audio transcription → Timestamped transcript: writes transcript
- Shorts workflow → Segment analysis client: requests analysis
- Segment analysis client → Gemini: sends prompt
- Gemini → Segment analysis client: returns suggestion
- Shorts workflow → Suggestion parsing: parses suggestion
- Shorts workflow → Segment confirmation: requests choice
- User → Segment confirmation: chooses timestamps
- Shorts workflow → Vertical crop: crops segment
- Shorts workflow → Subtitle composition: adds subtitles
- Shorts workflow → MP4 rendering: renders video
- MP4 rendering → Short video: writes MP4