# gbrlpzz/scribe architecture

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

- Interactive diagram: https://gitdiagram.com/gbrlpzz/scribe
- Repository: https://github.com/gbrlpzz/scribe

## Overview

##### Project type and purpose
- This is an open-source, command-line transcription tool written in Python.
- It provides two modes:
- A “local” version (scribe.py) that uses the Whisper ASR model locally, then generates a PDF via ReportLab.
- A “diet” version (diet-scribe.py) that uses the OpenAI API for transcription and emits a plain text file.

##### High-level architectural overview
Both scripts implement a linear data-pipeline pattern. The core stages are:
1. CLI Interface & Input Validation
2. Audio Format Conversion (using pydub/moviepy)
3. Speech-to-Text (Whisper locally or OpenAI API)
4. (Local only) Title Generation via OpenAI GPT-3.5-turbo
5. Output Generation (PDF with ReportLab or TXT)

##### Main components and interactions
- CLI Layer (scribe.py / diet-scribe.py)
– Parses command-line arguments and validates input file.
– Orchestrates the pipeline stages in sequence.
- Audio Converter
– Uses pydub (or moviepy for MP4) to transcode MP3/M4A/MP4 → WAV.
- ASR Engine
– Local: OpenAI Whisper (imported module).
– API: OpenAI’s Whisper endpoint or chat completions for transcription.
- LLM Title Generator (local version only)
– Calls OpenAI’s chat.completions endpoint (model=gpt-3.5-turbo) to produce a document title.
- Document Renderer
– PDF: Uses ReportLab to lay out title & transcript on A4 pages.
– TXT: Writes raw transcript to .txt file.
- External Services
– OpenAI API (for transcription in diet version and title generation in local version).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Local Pipeline"
        CLI_Local["CLI Interface & Input Validation (Local)"]:::local
        Converter["Audio Converter\n(pydub, moviepy)"]:::local
        ASR_Local["Local ASR Engine\n(Whisper)"]:::local
        Title["LLM Title Generator\n(gpt-3.5-turbo)"]:::local
        PDF["PDF Document Renderer\n(ReportLab)"]:::output
        CLI_Local --> Converter --> ASR_Local --> Title --> PDF
    end

    subgraph "Diet Pipeline"
        CLI_Diet["CLI Interface & Input Validation (Diet/API)"]:::local
        Converter_D["Audio Converter\n(pydub, moviepy)"]:::local
        ASR_API["API ASR Engine\n(OpenAI Whisper API)"]:::local
        TXT["TXT Document Renderer\n(plain text)"]:::output
        CLI_Diet --> Converter_D --> ASR_API --> TXT
    end

    ASR_Local -->|"API call"| OpenAI_API
    Title -->|"API call"| OpenAI_API
    ASR_API -->|"API call"| OpenAI_API

    OpenAI_API["OpenAI API"]:::api

    %% Click Events
    click CLI_Local "https://github.com/gbrlpzz/scribe/blob/main/scribe.py"
    click CLI_Diet "https://github.com/gbrlpzz/scribe/blob/main/diet-scribe.py"
    click Converter "https://github.com/gbrlpzz/scribe/blob/main/scribe.py"
    click Converter_D "https://github.com/gbrlpzz/scribe/blob/main/scribe.py"
    click ASR_Local "https://github.com/gbrlpzz/scribe/blob/main/scribe.py"
    click ASR_API "https://github.com/gbrlpzz/scribe/blob/main/diet-scribe.py"
    click Title "https://github.com/gbrlpzz/scribe/blob/main/scribe.py"
    click PDF "https://github.com/gbrlpzz/scribe/blob/main/scribe.py"
    click TXT "https://github.com/gbrlpzz/scribe/blob/main/diet-scribe.py"
    click OpenAI_API "https://github.com/gbrlpzz/scribe/blob/main/README.md"

    classDef local fill:#BBDEFB,stroke:#039BE5,color:#000
    classDef api fill:#FFCC80,stroke:#FB8C00,color:#000
    classDef output fill:#C8E6C9,stroke:#388E3C,color:#000
```
