# gstreamer/gst-python architecture

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

- Interactive diagram: https://gitdiagram.com/gstreamer/gst-python
- Repository: https://github.com/gstreamer/gst-python

## Overview

##### Project type and purpose
- This is an open-source binding library (“gst-python”) that provides Python language access to the GStreamer multimedia framework via GObject Introspection.
- It implements a native GStreamer plugin that allows Python-written elements to be registered into GStreamer pipelines.
- It supplies generated Python modules under the “gi” directory, example applications, and a full test suite.

##### File structure
- Top level
- meson.build & meson_options.txt – build configuration
- plugin/ – C code for the GstPython plugin that registers Python elements
- gi/ – generated and hand-written overrides for GObject-Introspection bindings (meson.build, overrides/*.py/.c)
- examples/ – sample Python scripts demonstrating pipeline construction & custom elements
- testsuite/ – Python and C tests driving the library and plugin
- hooks/pre-commit.hook – local git enforcement
- Patterns
- Build system: Meson drives generation of GI repos and compilation of plugin
- Binding layer: “gi” folder houses introspected Gst, GstPbutils APIs plus override modules
- Runtime plugin: gstpythonplugin.c sits in plugin/ and registers a GstPlugin that loads Python classes
- Extensibility: examples/plugins/ shows how users write new Python elements

##### README for additional insights
- The README is autogenerated, points to richer docs. We infer from file names that core dependencies are GObject-Introspection, GStreamer core C library, Python 3.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Generation
    subgraph "Build & Generation"
        MB["meson.build"]:::buildtools
        MO["meson_options.txt"]:::buildtools
        GISB["gi/meson.build"]:::buildtools
        PMSB["plugin/meson.build"]:::buildtools
        TMSB["testsuite/meson.build"]:::buildtools
        GIscan["g-ir-scanner"]:::buildtools
        GIRcomp["g-ir-compiler"]:::buildtools
    end

    %% Binding Layer
    subgraph "Binding Layer"
        GIrepo["gi (repository)"]:::generated
        GIMSB["gi/meson.build"]:::buildtools
        OvGst["gi/overrides/Gst.py"]:::generated
        OvPb["gi/overrides/GstPbutils.py"]:::generated
        OvModC["gi/overrides/gstmodule.c"]:::generated
        OvMes["gi/overrides/meson.build"]:::buildtools
    end

    %% Runtime Plugin
    subgraph "Runtime Plugin"
        PPc["plugin/gstpythonplugin.c"]:::cplugin
        PPmsb["plugin/meson.build"]:::buildtools
    end

    %% Python Application
    subgraph "Python Application"
        subgraph "Examples Scripts"
            hello["examples/helloworld.py"]:::python
            dynsrc["examples/dynamic_src.py"]:::python
            rec["examples/record_sound.py"]:::python
            reqs["examples/requirements.txt"]:::python
        end
        subgraph "Custom Elements"
            iden["examples/plugins/python/identity.py"]:::python
            ap["examples/plugins/python/audioplot.py"]:::python
            et["examples/plugins/python/exampleTransform.py"]:::python
            mix["examples/plugins/python/mixer.py"]:::python
            atest["examples/plugins/python/py_audiotestsrc.py"]:::python
            sink["examples/plugins/python/sinkelement.py"]:::python
        end
    end

    %% GStreamer Core
    subgraph "GStreamer Core"
        gstcore["libgstreamer-1.0"]:::external
        gstpb["libgstpbutils-1.0"]:::external
    end

    %% Test Harness
    subgraph "Test Harness"
        rtests["testsuite/runtests.py"]:::tests
        common["testsuite/common.py"]:::tests
        supp["testsuite/gstpython.supp"]:::tests
        tpyiden["testsuite/python/identity.py"]:::tests
        tgst["testsuite/test_gst.py"]:::tests
        tplug["testsuite/test_plugin.py"]:::tests
        ttypes["testsuite/test_types.py"]:::tests
        oldtests["testsuite/old/"]:::tests
    end

    %% Connections: Build phase
    MB -->|"drives"| GIscan
    GIscan -->|"generates XML"| GIRcomp
    GIRcomp -->|"produces Python modules"| GIrepo
    MB --> GISB
    MB --> PMSB
    MB --> TMSB
    GIMSB --> MB
    OvMes --> GIMSB

    %% Connections: Runtime
    hello -->|"import gi.repository.Gst"| GIrepo
    dynsrc -->|"import gi.repository.Gst"| GIrepo
    rec -->|"import gi.repository.Gst"| GIrepo
    GIrepo -->|"calls C API"| gstcore
    PPc -->|"registers plugin"| gstcore
    PPc -->|"loads elements"| iden
    PPc -->|"loads elements"| ap
    PPc -->|"loads elements"| et
    PPc -->|"loads elements"| mix
    PPc -->|"loads elements"| atest
    PPc -->|"loads elements"| sink
    gstcore --> gstpb

    %% Connections: Tests
    rtests -->|"test binding"| GIrepo
    rtests -->|"test plugin"| PPc
    rtests -->|"test core integration"| gstcore
    common --> rtests
    supp --> rtests
    tpyiden --> rtests
    tgst --> rtests
    tplug --> rtests
    ttypes --> rtests
    oldtests --> rtests

    %% Click Events
    click MB "https://github.com/gstreamer/gst-python/blob/master/meson.build"
    click MO "https://github.com/gstreamer/gst-python/blob/master/meson_options.txt"
    click GISB "https://github.com/gstreamer/gst-python/blob/master/gi/meson.build"
    click PMSB "https://github.com/gstreamer/gst-python/blob/master/plugin/meson.build"
    click TMSB "https://github.com/gstreamer/gst-python/blob/master/testsuite/meson.build"
    click GIMSB "https://github.com/gstreamer/gst-python/blob/master/gi/meson.build"
    click OvGst "https://github.com/gstreamer/gst-python/blob/master/gi/overrides/Gst.py"
    click OvPb "https://github.com/gstreamer/gst-python/blob/master/gi/overrides/GstPbutils.py"
    click OvModC "https://github.com/gstreamer/gst-python/blob/master/gi/overrides/gstmodule.c"
    click OvMes "https://github.com/gstreamer/gst-python/blob/master/gi/overrides/meson.build"
    click PPc "https://github.com/gstreamer/gst-python/blob/master/plugin/gstpythonplugin.c"
    click PPmsb "https://github.com/gstreamer/gst-python/blob/master/plugin/meson.build"
    click hello "https://github.com/gstreamer/gst-python/blob/master/examples/helloworld.py"
    click dynsrc "https://github.com/gstreamer/gst-python/blob/master/examples/dynamic_src.py"
    click rec "https://github.com/gstreamer/gst-python/blob/master/examples/record_sound.py"
    click reqs "https://github.com/gstreamer/gst-python/blob/master/examples/requirements.txt"
    click iden "https://github.com/gstreamer/gst-python/blob/master/examples/plugins/python/identity.py"
    click ap "https://github.com/gstreamer/gst-python/blob/master/examples/plugins/python/audioplot.py"
    click et "https://github.com/gstreamer/gst-python/blob/master/examples/plugins/python/exampleTransform.py"
    click mix "https://github.com/gstreamer/gst-python/blob/master/examples/plugins/python/mixer.py"
    click atest "https://github.com/gstreamer/gst-python/blob/master/examples/plugins/python/py_audiotestsrc.py"
    click sink "https://github.com/gstreamer/gst-python/blob/master/examples/plugins/python/sinkelement.py"
    click rtests "https://github.com/gstreamer/gst-python/blob/master/testsuite/runtests.py"
    click common "https://github.com/gstreamer/gst-python/blob/master/testsuite/common.py"
    click supp "https://github.com/gstreamer/gst-python/blob/master/testsuite/gstpython.supp"
    click tpyiden "https://github.com/gstreamer/gst-python/blob/master/testsuite/python/identity.py"
    click tgst "https://github.com/gstreamer/gst-python/blob/master/testsuite/test_gst.py"
    click tplug "https://github.com/gstreamer/gst-python/blob/master/testsuite/test_plugin.py"
    click ttypes "https://github.com/gstreamer/gst-python/blob/master/testsuite/test_types.py"
    click oldtests "https://github.com/gstreamer/gst-python/tree/master/testsuite/old/"

    %% Styles
    classDef buildtools fill:#fddc5c,stroke:#e28e0b,stroke-width:2,stroke-dasharray: 5 5
    classDef generated fill:#fff2a8,stroke:#e4b63b,stroke-width:2
    classDef cplugin fill:#a8d0ff,stroke:#4182c4,stroke-width:2
    classDef python fill:#d0ffd8,stroke:#42a754,stroke-width:2
    classDef external fill:#e0e0e0,stroke:#888,stroke-width:2
    classDef tests fill:#f0d0ff,stroke:#a044b0,stroke-width:2
```
