Skip to main content

PyCFGst

PyPI version Python versions License: MIT

PyCFGst (Cristi Fati's GStreamer utilities for Python) provides pipeline parsing and registry access for GStreamer.

Install

python -m pip install --upgrade pycfgst

Requirements

GStreamer and its plugins must be installed separately (system packages or platform-specific installers).

Usage

Pipeline Parser

Convert a live GStreamer pipeline into a gst-launch-1.0 command string:

import gi
gi.require_version("Gst", "1.0")
from gi.repository import Gst

Gst.init(None)

from pycfgst.pipeline_parser import PipelineParser

pipeline = Gst.parse_launch(
    "videotestsrc pattern=18 ! tee name=t0 "
    "! queue ! autovideosink "
    "t0. ! queue ! autovideosink"
)
pipeline.set_state(Gst.State.PAUSED)

pp = PipelineParser()
print(pp.gst_launch(pipeline))

pipeline.set_state(Gst.State.NULL)

Output:

gst-launch-1.0 -e \
  videotestsrc \
      pattern=18 \
  ! tee \
      name=t0 \
  t0. \
    ! queue \
    ! autovideosink \
  t0. \
    ! queue \
    ! autovideosink

Registry Access

Inspect the GStreamer plugin registry:

import gi
gi.require_version("Gst", "1.0")
from gi.repository import Gst

Gst.init(None)

from pycfgst.registry_access import RegistryAccess

ra = RegistryAccess()
print(f"Plugins: {len(ra.contents())}")
print(f"Element classes: {len(ra.element_classes())}")
print(f"Failed: {ra.failed_classes}")

Property Filtering

When converting a GStreamer pipeline to a gst-launch-1.0 command, PipelineParser decides which element and pad properties to include in the output. Properties are excluded (filtered out) based on a YAML configuration file using a 3-tier pattern matching system.

Configuration File Format

The configuration file has three top-level keys:

excluded_property_filter:
    # filter rules here

explicit_request_pads:
    # factories requiring explicit request pad names in output

traversed_bins:
    # experimental: bin factories to traverse into instead of treating as opaque elements

Pattern Matching (3 tiers)

Under excluded_property_filter, keys are element factory name patterns. They are matched against each element in the pipeline using three tiers of increasing specificity:

Tier Pattern Example Matches
1 * (global) "*" All elements
2 Glob te*, *sink, video?rc Elements matching the glob via fnmatch
3 Exact tee, compositor Only that specific element

Higher tiers override lower tiers. Within the glob tier, patterns are applied in order of appearance (last match wins).

Property Items

Each pattern maps to a list of property items:

"*":
    - parent          # Exclude "parent" property
    - "!name"         # Re-include "name" (negation)
    - "*"             # Exclude ALL properties
    - "@pad":         # Pad properties section
        - direction   # Exclude pad "direction" property
        - "!caps"     # Re-include pad "caps"
        - "*"         # Exclude ALL pad properties
Syntax Meaning
propname Exclude this property
!propname Re-include this property (undo a previous exclusion)
* Exclude all properties
@pad Nested list of pad-specific property rules (same syntax)

Resolution Example

For an element named tee, given:

excluded_property_filter:
    "*":
        - name
        - parent
    "te*":
        - alloc-pad
    tee:
        - "!name"

Resolution order: * then te* then tee.

  1. * excludes name and parent
  2. te* matches, adds alloc-pad to exclusions
  3. tee exact match, !name re-includes name

Result: parent and alloc-pad are excluded. name is included.

Explicit Request Pads

Some GStreamer elements (particularly vendor-specific ones like Nvidia DeepStream or Qualcomm IM SDK) require request pads to be explicitly named in gst-launch syntax for linking to work. The explicit_request_pads configuration key lists factories where the parser should emit pad names on source and sink references.

For elements in this list, the parser output changes from:

tee name=t0 \
t0. \
  ! queue \

to:

tee name=t0 \
t0.src_0 \
  ! queue \

And for sink-side request pads (single predecessor):

! comp0.sink_0 \
compositor name=comp0 \
! autovideosink

Only request pads are affected — static pads are left unchanged.

Elements in explicit_request_pads automatically have their name property preserved in the output (regardless of the excluded_property_filter rules), since the name is required for pad references.

Configuration

explicit_request_pads:
    - nvcompositor
    - nvstreammux
    - nvtee

The default configuration includes Nvidia DS and Qualcomm IM SDK factories. Standard GStreamer factories (tee, compositor, etc.) handle request pad linking internally and do not need to be listed.

User Configuration

Users can provide their own configuration file to customize filtering:

pp = PipelineParser()
pp.configure(user_config="path/to/user_config.yaml")
output = pp.gst_launch(pipeline)

configure() Parameters

Parameter Default Description
user_config None Path to user YAML configuration file
merge True True: merge with defaults. False: use only user config
merge_policy PipelineParserConfig.MERGE_POLICY_SPECIFICITY Conflict resolution strategy. Supported values in PipelineParserConfig.MERGE_POLICIES

User Config File Format

Same format as the defaults file:

excluded_property_filter:
    "*":
        - some-global-prop
    "in-house-element":
        - "!parent"

explicit_request_pads:

traversed_bins:

Merge Behavior (merge=True)

When merging, default and user configurations are interleaved by specificity tier:

default *  ->  user *  ->  default globs  ->  user globs  ->  default exact  ->  user exact

At each step, additions and negations (!prop) apply to the accumulated set. This means:

  • More specific patterns always beat less specific ones, regardless of source
  • At the same specificity level, user entries override defaults
  • A user glob cannot override a default exact match (use an exact match instead)

No Merge (merge=False)

Defaults are ignored entirely. Only the user configuration is used.

Subclass Customization

Override force_exclude_property to add programmatic exclusion logic beyond the YAML configuration:

class CustomPipelineParser(PipelineParser):
    @classmethod
    def force_exclude_property(cls, prop, val=None):
        if super().force_exclude_property(prop, val):
            return True
        # Custom logic here
        return prop.name.startswith("internal-")

This method is called twice per property: once before fetching the value (val=None, for early rejection based on property metadata) and once after (val is the actual value, for value-based filtering). The base implementation excludes non-writable properties and properties equal to their default value.

Known Limitations

Accumulating properties

Some GStreamer elements use properties where calling set_property multiple times accumulates internal state, but get_property only returns the last value set. Since the parser reads property values via get_property, it cannot reconstruct the full sequence of set_property calls. The generated gst-launch-1.0 command will be missing earlier values, which may cause the pipeline to crash or behave differently from the original.

Known elements affected:

  • nvdsvideotemplate and nvdsaudiotemplate (NVIDIA DeepStream): the customlib-props property accepts one key:value pair per call and pushes it to an internal vector, but get_property returns only the last string.

Example — Python sets three properties:

element.set_property("customlib-props", "property0:value0")
element.set_property("customlib-props", "property1:value1")
element.set_property("customlib-props", "property2:value2")

The parser output will only contain:

customlib-props=property2:value2

The first two properties are silently lost.

Changelog

See CHANGELOG for a full list of changes.

Contributing

Contributions are welcome. Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License.

Metadata

Release files for pycfgst 2026.6.16

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pycfgst 2026.6.16
File Size Uploaded Provenance Actions
pycfgst-2026.6.16.tar.gz 22.1 kB Without provenance Details for pycfgst-2026.6.16.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pycfgst 2026.6.16
File Interpreter ABI Platform Actions
pycfgst-2026.6.16-py3-none-any.whl Python 3 none any Details for pycfgst-2026.6.16-py3-none-any.whl

Total release size: 43.1 kB

Release files / pycfgst-2026.6.16.tar.gz

Download URL pycfgst-2026.6.16.tar.gz
Size 22.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c7acaafc265c4723d2593f6ec02e595b8d32f87a2c2504ea323beaed5064cc16
BLAKE2b-256 checksum
How to use checksums
2fb0ca55c5c84039da8e6f9594c10b77db3c38c31a52d665414848c0c9a9fe02
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.3

Release files / pycfgst-2026.6.16-py3-none-any.whl

Download URL pycfgst-2026.6.16-py3-none-any.whl
Size 21.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
023d0ecc05bfbafd72383f2e671b32813f197b1dd674ca2174d6875c1502baf0
BLAKE2b-256 checksum
How to use checksums
6d04f48738b7c25c77f4696cefb7993d8699a2978e985a0204a99d63fb1e66f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.3

Security for pycfgst 2026.6.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2026.6.16 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page