gstreamer

name	gstreamer
description	Use this skill for GStreamer pipeline development and debugging: graph design, caps negotiation issues, latency, synchronization, and runtime diagnostics.

GStreamer Skill

When to use

Use for tasks with gst-launch, pipeline graphs, plugin selection, caps negotiation, timing/sync, encoder/decoder tuning, or stream reliability.

Workflow

1. Define expected media contract first: codec, resolution, framerate, latency budget.
2. Build minimal pipeline that works end-to-end.
3. Add elements incrementally and validate after each addition.
4. Capture logs and DOT graphs when behavior diverges.
5. Lock in working caps and buffering strategy.

Core commands

• Quick run: gst-launch-1.0 ...
• Inspect plugin: gst-inspect-1.0 <element>
• Verbose logs: GST_DEBUG=2 gst-launch-1.0 ...
• Focused logs: GST_DEBUG=GST_CAPS:6,GST_PADS:6,GST_EVENT:5 gst-launch-1.0 ...
• Dump graphs: GST_DEBUG_DUMP_DOT_DIR=/tmp GST_DEBUG=3 gst-launch-1.0 ... then render with Graphviz (dot -Tpng file.dot -o graph.png).

Debug heuristics

• If no data flow: verify pad link compatibility and capsfilter placement.
• If negotiation fails: inspect upstream/downstream caps and force explicit caps near boundaries.
• If latency spikes: inspect queue sizes, leaky settings, and encoder tune/preset.
• If A/V drift: inspect timestamps, clock selection, and sync flags.
• If intermittent drops: check jitter buffer, network burst tolerance, and keyframe interval.

Reliability patterns

• Use queues between thread domains.
• Set explicit caps at critical boundaries.
• Prefer explicit parser/payloader/depayloader elements rather than implicit auto-plugging in production.
• Add watchdog/health probes for long-running pipelines.

Validation checklist

• Startup time and steady-state latency measured.
• Recovery behavior tested (source restart / network jitter).
• CPU and memory stable under expected load.
• Logs include enough signal for postmortem.