# aastroza/ai-podcast-generator architecture

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

- Interactive diagram: https://gitdiagram.com/aastroza/ai-podcast-generator
- Repository: https://github.com/aastroza/ai-podcast-generator

## Overview

##### Project Type and Purpose
- This is an open-source CLI tool (“AI Podcast Generator”) that automates the end-to-end creation of podcast scripts and audio. It reads a YAML spec, uses an AI text generator (via Marvin/OpenAI), converts script segments to speech (via Play.ht), and stitches the audio together (via pydub).

##### Key Components (to show
a. CLI / Orchestration Layer
- podcast.py (entry point)
- src/utils.py (config loading, file management)
b. Configuration
- YAML config file (examples/…/podcast.YAML)
- data/voices.json (metadata for available voices)
- .env (environment variables for OPENAI_API_KEY, PLAYHT_USER_ID, PLAYHT_SECRET)
c. Script Generation Service
- src/chat.py → wraps Marvin/OpenAI calls
d. Text-to-Speech Service
- src/audio.py → Play.ht API client
e. Audio Processing
- pydub (merge audio segments into final MP3)
f. File System
- Input folder (examples/…)
- Output folder (as specified in YAML)
- Intermediate files (JSON transcripts, per-segment MP3s)
g. External Services
- OpenAI (via Marvin client)
- Play.ht REST API

##### Component Relationships and Data Flow
1. User invokes CLI: `python podcast.py --input podcast.YAML`.
2. CLI loads YAML & voices.json via utils, loads API keys from .env.
3. For each “talk turn” (host, guest, topics) → chat.py → Marvin/OpenAI → returns script text segments.
4. Each segment passed to audio.py → Play.ht API → returns TTS MP3 URLs or binary.
5. CLI downloads/saves each segment (examples/…/*.mp3, *.json transcripts).
6. pydub merges all segment MP3s into a single podcast file.
7. Final MP3 written to the output folder.

##### Architectural Patterns and Design Principles
- Modular Pipeline: clear separation between configuration, script generation, TTS conversion, and audio merging.
- Single Responsibility: each src module handles one concern.
- External Service Adapters: wrappers around OpenAI and Play.ht.
- File-based staging: uses local filesystem for inputs, outputs, and intermediates.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Internal Modules
    subgraph "Internal Modules"
        CLI["CLI / Orchestrator\n(podcast.py)"]:::internal
        Utils["Config Loader\n(src/utils.py)"]:::internal
        Chat["Script Generator\n(src/chat.py)"]:::internal
        Audio["TTS Client\n(src/audio.py)"]:::internal
        Merger["Audio Merger\n(pydub)"]:::internal
    end

    %% Filesystem
    F1["Filesystem: Input & Intermediate\n(examples/, transcripts, segment MP3s)"]:::folder
    F2["Filesystem: Output\n(final MP3)"]:::folder

    %% Configuration Resources
    Env[".env / .env.example\n(environment variables)"]:::config
    Voices["voices.json\n(voice metadata)"]:::config
    YAML["podcast.YAML\n(example spec)"]:::config

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Playht["Play.ht API"]:::external
    end

    %% Connections
    CLI -->|"load config"| Utils
    Utils -.->|".env, voices.json, YAML"| Env
    Utils -.->|".env, voices.json, YAML"| Voices
    Utils -.->|".env, voices.json, YAML"| YAML

    CLI -->|"generate script text"| Chat
    Chat -->|"API call"| OpenAI
    OpenAI -->|"text response"| Chat

    Chat -->|"script segments"| Audio
    Audio -->|"TTS request"| Playht
    Playht -->|"audio binaries"| Audio

    Audio -->|"save segments"| F1
    Audio -->|"send to merger"| Merger

    Merger -->|"merge MP3s"| F2

    %% Click Events
    click CLI "https://github.com/aastroza/ai-podcast-generator/blob/main/podcast.py"
    click Utils "https://github.com/aastroza/ai-podcast-generator/blob/main/src/utils.py"
    click Chat "https://github.com/aastroza/ai-podcast-generator/blob/main/src/chat.py"
    click Audio "https://github.com/aastroza/ai-podcast-generator/blob/main/src/audio.py"
    click Merger "https://github.com/aastroza/ai-podcast-generator/blob/main/podcast.py"
    click Env "https://github.com/aastroza/ai-podcast-generator/blob/main/.env"
    click Voices "https://github.com/aastroza/ai-podcast-generator/blob/main/data/voices.json"
    click YAML "https://github.com/aastroza/ai-podcast-generator/blob/main/examples/*/podcast.YAML"
    click F1 "https://github.com/aastroza/ai-podcast-generator/tree/main/examples/"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#0366d6,stroke-width:1px
    classDef external fill:#d9ead3,stroke:#6aa84f,stroke-width:1px
    classDef folder fill:#f2f2f2,stroke:#999999,stroke-width:1px
    classDef config fill:#f2f2f2,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
```
