# mli/autocut architecture

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

- Interactive diagram: https://gitdiagram.com/mli/autocut
- Repository: https://github.com/mli/autocut

## Overview

##### Project type and purpose
- AutoCut is a command-line Python package that automates video subtitle generation and segment‐based cutting.
- It uses OpenAI’s Whisper (or faster-whisper / OpenAI API) for transcription, ffmpeg for cutting/merging, and provides a daemon mode to watch folders.

##### File structure
- Top-level:
- Dockerfile(.cuda): containerization for CPU and GPU
- setup.py, setup.cfg: packaging
- .github/workflows: CI (lint, tests, faster-whisper)
- autocut/ : core library
- Key modules in autocut/:
- main.py — CLI entrypoint, arg parsing
- transcribe.py — model loading, audio extraction, Whisper API calls, generates `.srt` & `.md`
- cut.py — reads `.srt`/`.md`, constructs ffmpeg cut/merge commands
- daemon.py — monitors directories, orchestrates transcribe → cut loop
- utils.py — file I/O, path utils, encoding helpers
- whisper_model.py — abstraction over different Whisper backends
- test/*: unit tests for cutting and transcription
- imgs/: screenshots for README

##### README for additional insights
- Supported transcription backends: openai-whisper, faster-whisper, OpenAI API
- CLI usage patterns: `autocut -t (transcribe)`, `autocut -c (cut)`, `autocut -d (daemon)`
- Dependencies: Python, PyTorch, ffmpeg
- Docker images for isolation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLI["CLI (autocut)"]:::presentation
        CLI -->|"invokes"| MainPy
        CLI -->|"module run"| MainEntry
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        MainPy["main.py"]:::application
        MainEntry["__main__.py"]:::application
        Daemon["daemon.py"]:::application
        MainPy -->|"daemon command"| Daemon
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        Transcribe["transcribe.py"]:::domain
        PackageTrans["package_transcribe.py"]:::domain
        WhisperModel["whisper_model.py"]:::domain
        Cutter["cut.py"]:::domain
        Utils["utils.py"]:::domain
        Types["type.py"]:::domain

        MainPy -->|"transcribe command"| Transcribe
        MainPy -->|"cut command"| Cutter
        Daemon -->|"watch & orchestrate"| Transcribe
        Daemon -->|"on edit trigger"| Cutter

        Transcribe -->|"calls"| WhisperModel
        Transcribe -->|"uses utils"| Utils
        Transcribe -->|"packages via"| PackageTrans
        Cutter -->|"uses utils"| Utils
        Cutter -->|"uses types"| Types
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        FS["Filesystem"]:::infra
        FFmpeg["ffmpeg"]:::infra
        OpenAIAPI["OpenAI API"]:::infra
        Torch["PyTorch Models"]:::infra
        DockerCPU["Dockerfile (CPU)"]:::infra
        DockerGPU["Dockerfile.cuda (GPU)"]:::infra

        Transcribe -->|"writes .srt/.md"| FS
        Cutter -->|"reads .srt/.md"| FS
        Cutter -->|"executes"| FFmpeg
        WhisperModel -->|"local model"| Torch
        WhisperModel -->|"API calls"| OpenAIAPI
        DockerCPU -.->|"builds"| MainPy
        DockerGPU -.->|"builds"| MainPy
    end

    %% CI / Testing
    subgraph "CI & Testing"
        direction TB
        CIBase["base.yml"]:::ci
        CILint["lint.yml"]:::ci
        CIFast["faster-whisper.yml"]:::ci
        TestCut["test_cut.py"]:::ci
        TestTrans["test_transcribe.py"]:::ci
        MediaFixtures["test/media/"]:::ci
        SubtitleFixtures["test/content/"]:::ci

        CIBase -->|runs| TestCut
        CIBase -->|runs| TestTrans
        CILint -->|formats & lints| MainPy
        CIFast -->|benchmarks| Transcribe
        TestCut -->|uses fixtures| MediaFixtures
        TestTrans -->|uses fixtures| SubtitleFixtures
    end

    %% Click Events
    click MainPy "https://github.com/mli/autocut/blob/main/autocut/main.py"
    click MainEntry "https://github.com/mli/autocut/blob/main/autocut/__main__.py"
    click Transcribe "https://github.com/mli/autocut/blob/main/autocut/transcribe.py"
    click PackageTrans "https://github.com/mli/autocut/blob/main/autocut/package_transcribe.py"
    click WhisperModel "https://github.com/mli/autocut/blob/main/autocut/whisper_model.py"
    click Cutter "https://github.com/mli/autocut/blob/main/autocut/cut.py"
    click Daemon "https://github.com/mli/autocut/blob/main/autocut/daemon.py"
    click Utils "https://github.com/mli/autocut/blob/main/autocut/utils.py"
    click Types "https://github.com/mli/autocut/blob/main/autocut/type.py"
    click SetupPy "https://github.com/mli/autocut/blob/main/setup.py"
    click SetupCfg "https://github.com/mli/autocut/blob/main/setup.cfg"
    click DockerCPU "https://github.com/mli/autocut/tree/main/Dockerfile"
    click DockerGPU "https://github.com/mli/autocut/blob/main/Dockerfile.cuda"
    click CIBase "https://github.com/mli/autocut/blob/main/.github/workflows/base.yml"
    click CILint "https://github.com/mli/autocut/blob/main/.github/workflows/lint.yml"
    click CIFast "https://github.com/mli/autocut/tree/main/.github/workflows/faster-whisper"
    click TestCut "https://github.com/mli/autocut/blob/main/test/test_cut.py"
    click TestTrans "https://github.com/mli/autocut/blob/main/test/test_transcribe.py"
    click MediaFixtures "https://github.com/mli/autocut/tree/main/test/media/"
    click SubtitleFixtures "https://github.com/mli/autocut/tree/main/test/content/"

    %% Styles
    classDef presentation fill:#ffe4b5,stroke:#b36b00;
    classDef application fill:#b3cde0,stroke:#034f84;
    classDef domain fill:#ccebc5,stroke:#006d2c;
    classDef infra fill:#fdd0a2,stroke:#b30000;
    classDef ci fill:#decbe4,stroke:#663399;
```
