# lavanyajc/ccextractor architecture

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

- Interactive diagram: https://gitdiagram.com/lavanyajc/ccextractor
- Repository: https://github.com/lavanyajc/ccextractor

## Overview

##### Project type and purpose
- CCExtractor is an open-source, cross-platform subtitle extraction tool. It ships as a command-line executable (ccextractor) and platform-specific GUIs (Windows/Mac). Its core functionality is written in C (lib_ccx), with a modern Rust port (lib_ccxr) and various packaging/build scripts.
- Use cases: extract closed captions from TV streams or files, translate them, hard-sub burn, output in multiple subtitle formats.

##### File structure
- Top-level “src” directory holds:
- ccextractor.c / .h — CLI entry point
- lib_ccx/ — the main C library modules (demuxers, decoders, encoders, OCR, HardsubX, networking, utility)
- rust/ — Rust port with two crates: lib_ccxr (core logic) and the Rust binary wrapper
- thirdparty/ — bundled external dependencies (freetype, libpng, zlib, protobuf-c, utf8proc, etc.)
- Platform subdirectories: linux/, mac/, windows/ contain build scripts, installers, GUIs.
- docker/ & Vagrantfile provide reproducible dev/test environments.
- package_creators/ automates distribution packaging (RPM, Debian, Arch, tarballs).

##### README for technical stack
- Core languages: C, Rust, small Python tools.
- Build tools: CMake, Bazel (BUILD files), Make, autoconf/automake.
- Packaging & CI: GitHub Actions, Travis, AppImage, Windows Installer (WiX), Homebrew/MacPorts.

##### Main components and interactions (to represent
- CLI executable (“ccextractor”)
- Windows GUI (InstallCCExtractorMacGUI.app for Mac, .sln/.vcxproj for Windows)
- Rust wrapper (in rust/src) for new CLI
- Demuxers → Bitstream parser → CC decoders (608, 708, ISDB, teletext) → Timing & sequencing
- Optional modules: OCR engine, HardsubX classifier/decoder, networking input
- Output encoders: SRT, WebVTT, SCC, SAMI, MPL2, transcripts, burned-in PNG (uses libpng+freetype)
- freetype (font metrics/rendering)
- libpng (image output)
- zlib (compression)
- protobuf-c (data serialization for internal messages)
- utf8proc, iconv, system libs
- Build systems: CMake, Bazel, Make + autoconf
- CI/CD: GitHub workflows, Travis, Sample-Platform
- Distribution: Docker image, Vagrant VM, platform installers, package_creators scripts

##### Relationships & data flow
- Input media (file/stream) → Front-end → Core library demuxer
- Core demuxer → CC decoder → timing/sequencing
- Sequenced captions → Output encoders → Subtitle files or burned video frames
- Encoders → Third-party libs (freetype+libpng for PNG burn; zlib for compression)
- Rust wrapper calls into the same core functionality (via C FFI or direct Rust implementation).

##### Architectural patterns & principles
- Modular pipeline: clearly separated stages (demux → decode → process → encode)
- Pluggable I/O: supports local files, network streams
- Dual implementation: C reference library and Rust port for safety/performance
- Cross-platform abstraction: platform layers for Windows/Mac/Linux build & GUI

## Diagram (Mermaid)

```mermaid
graph TD
    %% Media Input
    MediaInput["Media Input\n(file/stream)"]

    %% Front-ends
    subgraph "Front-ends"
        CLI["CLI Executable\n(ccextractor)"]:::frontend
        click CLI "https://github.com/lavanyajc/ccextractor/blob/master/src/ccextractor.c"
        GUIWin["Windows GUI"]:::frontend
        click GUIWin "https://github.com/lavanyajc/ccextractor/blob/master/windows/ccextractor.sln"
        GUIMac["macOS GUI App Bundle"]:::frontend
        click GUIMac "https://github.com/lavanyajc/ccextractor/blob/master/mac/gui/InstallCCExtractorMacGUI.app"
        RustWrap["Rust Wrapper\n(new CLI)"]:::frontend
        click RustWrap "https://github.com/lavanyajc/ccextractor/tree/master/src/rust/src/"
    end

    %% Core Library
    subgraph "Core Processing Library"
        subgraph "Demux & Parse"
            Demux["Demuxers"]:::core
            click Demux "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_demuxer.c"
            Bitstream["Bitstream Parsers"]:::core
            click Bitstream "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/cc_bitstream.c"
        end
        subgraph "Decoders"
            Dec608["CC Decoder 608"]:::core
            click Dec608 "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_decoders_608.c"
            Dec708["CC Decoder 708"]:::core
            click Dec708 "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_decoders_708.c"
            DecISDB["CC Decoder ISDB"]:::core
            click DecISDB "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_decoders_isdb.c"
            DecTele["Teletext Decoder"]:::core
            click DecTele "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/telxcc.c"
        end
        subgraph "Timing & Sequencing"
            Timing["Timing & Sequencing"]:::core
            click Timing "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_common_timing.c"
        end
        subgraph "Optional Modules"
            OCR["OCR Engine"]:::core
            click OCR "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ocr.c"
            HardsubClass["HardsubX Classifier"]:::core
            click HardsubClass "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/hardsubx_classifier.c"
            HardsubDec["HardsubX Decoder"]:::core
            click HardsubDec "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/hardsubx_decoder.c"
            Networking["Networking Input"]:::core
            click Networking "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/networking.c"
        end
        subgraph "Output Encoders"
            SRT["SRT Encoder"]:::core
            click SRT "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_encoders_srt.c"
            WebVTT["WebVTT Encoder"]:::core
            click WebVTT "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_encoders_webvtt.c"
            SCC["SCC Encoder"]:::core
            click SCC "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_encoders_scc.c"
            SAMI["SAMI Encoder"]:::core
            click SAMI "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_encoders_sami.c"
            MPL2["MPL2 Encoder"]:::core
            click MPL2 "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_encoders_structs.h"
            Transcript["Transcript Encoder"]:::core
            click Transcript "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_encoders_transcript.c"
            SPUPNG["SPUPNG Encoder"]:::core
            click SPUPNG "https://github.com/lavanyajc/ccextractor/blob/master/src/lib_ccx/ccx_encoders_spupng.c"
        end
    end

    %% Rust Core Library
    RustCore["Rust Core Library\n(lib_ccxr)"]:::core
    click RustCore "https://github.com/lavanyajc/ccextractor/tree/master/src/rust/lib_ccxr/"

    %% Third-Party
    subgraph "Third-Party Libraries"
        Freetype["freetype"]:::thirdparty
        click Freetype "https://github.com/lavanyajc/ccextractor/tree/master/src/thirdparty/freetype/"
        Libpng["libpng"]:::thirdparty
        click Libpng "https://github.com/lavanyajc/ccextractor/tree/master/src/thirdparty/libpng/"
        Zlib["zlib"]:::thirdparty
        click Zlib "https://github.com/lavanyajc/ccextractor/tree/master/src/thirdparty/zlib/"
        ProtobufC["protobuf-c"]:::thirdparty
        click ProtobufC "https://github.com/lavanyajc/ccextractor/tree/master/src/thirdparty/protobuf-c/"
        UTF8Proc["utf8proc"]:::thirdparty
        click UTF8Proc "https://github.com/lavanyajc/ccextractor/tree/master/src/thirdparty/utf8proc/"
    end

    %% Packaging & Build
    subgraph "Build & Packaging"
        CMake["CMake"]:::build
        click CMake "https://github.com/lavanyajc/ccextractor/blob/master/src/CMakeLists.txt"
        Bazel["Bazel"]:::build
        click Bazel "https://github.com/lavanyajc/ccextractor/tree/master/src/BUILD"
        MakeLinux["Make & Autotools (Linux)"]:::build
        click MakeLinux "https://github.com/lavanyajc/ccextractor/blob/master/linux/Makefile.am"
        MakeMac["Make & Autotools (Mac)"]:::build
        click MakeMac "https://github.com/lavanyajc/ccextractor/blob/master/mac/Makefile.am"
        PackageCreators["Package Creators"]:::build
        click PackageCreators "https://github.com/lavanyajc/ccextractor/tree/master/package_creators/"
        DockerEnv["Docker Env"]:::build
        click DockerEnv "https://github.com/lavanyajc/ccextractor/tree/master/docker/dockerfile"
        VagrantEnv["Vagrant VM"]:::build
        click VagrantEnv "https://github.com/lavanyajc/ccextractor/tree/master/Vagrantfile"
        CI["CI/CD Workflows"]:::build
        click CI "https://github.com/lavanyajc/ccextractor/blob/master/.github/workflows/build_linux.yml"
    end

    %% Data Flow
    MediaInput --> CLI
    MediaInput --> GUIWin
    MediaInput --> GUIMac
    MediaInput --> RustWrap

    CLI --> Demux
    GUIWin --> Demux
    GUIMac --> Demux
    RustWrap --> RustCore
    RustCore --> Demux

    Demux --> Bitstream
    Bitstream --> Dec608
    Bitstream --> Dec708
    Bitstream --> DecISDB
    Bitstream --> DecTele

    Dec608 --> Timing
    Dec708 --> Timing
    DecISDB --> Timing
    DecTele --> Timing

    Timing --> SRT
    Timing --> WebVTT
    Timing --> SCC
    Timing --> SAMI
    Timing --> MPL2
    Timing --> Transcript
    Timing --> SPUPNG

    Timing --> OCR
    Timing --> HardsubClass
    Timing --> Networking

    SPUPNG --> Freetype
    SPUPNG --> Libpng
    SPUPNG --> Zlib

    %% Packaging & Build dependencies
    CLI --> CMake
    CLI --> Bazel
    CLI --> MakeLinux
    GUIWin --> MakeMac
    GUIMac --> MakeMac
    RustWrap --> CMake

    CMake --> CI
    Bazel --> CI
    MakeLinux --> CI
    MakeMac --> CI
    PackageCreators --> CI
    DockerEnv --> CI
    VagrantEnv --> CI

    %% Styles
    classDef frontend fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef thirdparty fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef build fill:#FFA500,stroke:#333,stroke-width:1px
```
