GStreamer Metal Plugin
GPU-accelerated video processing for GStreamer on Apple platforms. Seven Metal-based elements replace CPU-bound operations with zero-copy, single-pass GPU processing.
What is GStreamer Metal?
GStreamer Metal (gst-vf-metal) is a professional-grade GStreamer plugin that provides Metal-based implementations of common CPU-bound video elements for macOS and iOS. It delivers significant performance improvements through Apple's Metal framework with compute shaders, enabling real-time video processing with minimal CPU overhead.
Zero-Copy Architecture
CVMetalTextureCache eliminates redundant CPU-GPU copies. Elements automatically skip GPU work when configured at identity/default values.
Single-Pass GPU Processing
All filter effects (brightness, contrast, hue, chroma key, LUT, etc.) applied in one GPU dispatch — no intermediate frame buffers between effects.
Mixed Format Compositing
Compositor accepts heterogeneous input formats (e.g., BGRA + NV12 simultaneously) with automatic format conversion.
6 Pixel Formats
Supports BGRA, RGBA, NV12, I420, UYVY, and YUY2 pixel formats across the element suite.
GPU-Accelerated Elements
vfmetalcompositor
Multi-input video mixing and compositing
- Per-pad positioning, scaling, alpha, and z-order
- Blend modes: source, over, add
- Mixed format inputs (BGRA + NV12 simultaneously)
- Sizing policies with aspect ratio preservation
vfmetalvideosink
Hardware-accelerated video renderer and display
- GstVideoOverlay and GstNavigation support
- Auto window creation with aspect ratio preservation
- Mouse/keyboard event forwarding
- BGRA, RGBA, NV12, and I420 formats
vfmetalvideofilter
15 GPU-accelerated visual effects in a single element
- Color: brightness, contrast, saturation, hue, gamma
- Effects: sharpness/blur, sepia, invert, noise, vignette
- Chroma key (green screen) with tolerance controls
- 3D LUT color grading (.cube and .png formats)
vfmetalconvertscale
Format conversion and scaling combined
- All 6 format pairs supported (e.g., NV12→BGRA, UYVY→I420)
- Bilinear and nearest-neighbor interpolation
- Letterboxing with custom border colors
- Replaces both videoconvert and videoscale
vfmetaltransform
Geometric transformations
- 8 rotation and flip methods
- Per-edge cropping
- Identity passthrough when no transform needed
- BGRA, RGBA, NV12, and I420 formats
vfmetaldeinterlace
GPU-accelerated interlace removal
- Bob, weave, linear, and greedy-H algorithms
- Motion-adaptive deinterlacing (greedy-H)
- Auto/manual field order detection
- BGRA, RGBA, NV12, and I420 formats
vfmetaloverlay
Image compositing overlay
- PNG and JPEG overlay support
- Absolute and relative positioning
- Custom sizing with alpha blending
- BGRA, RGBA, NV12, and I420 formats
15 Video Effects
All effects are applied in a single GPU pass and can be animated via GstController:
Brightness adjustment (-1 to 1)
Contrast control (0 to 2)
Color saturation (0 to 2)
Hue rotation (-1 to 1)
Gamma correction (0.01 to 10)
Sharpness and blur (-1 to 1)
Sepia tone effect (0 to 1)
Color inversion
Noise/grain overlay (0 to 1)
Vignette darkening (0 to 1)
Chroma key (green screen removal)
Chroma key edge tolerance
Chroma key edge smoothness
3D LUT grading via .cube files (DaVinci Resolve/Adobe)
3D LUT grading via .png strip files
Platform Support
macOS
13.0+ (Ventura)
Dynamic library (gstvfmetal.dylib)
iOS
14.0+
Static library (libgstvfmetal.a)
Frequently Asked Questions
What is GStreamer Metal?
GStreamer Metal is an open-source GStreamer plugin that provides GPU-accelerated video processing elements for macOS and iOS. It uses Apple's Metal framework and compute shaders to replace CPU-bound video operations, delivering significantly better performance for tasks like compositing, color correction, format conversion, and deinterlacing.
What platforms are supported?
GStreamer Metal supports macOS 13.0 (Ventura) and later and iOS 14.0 and later. On macOS it builds as a dynamic library (gstvfmetal.dylib), while on iOS it builds as a static library (libgstvfmetal.a) with a registration header.
What pixel formats are supported?
The plugin supports six pixel formats: BGRA, RGBA, NV12, I420, UYVY, and YUY2. Most elements support BGRA, RGBA, NV12, and I420, while vfmetalconvertscale supports all six formats for maximum conversion flexibility.
How do I install the plugin?
Clone the GitHub repository and run the included build script (./build.sh) for macOS. For iOS, use the CMake-based cross-compilation setup. The resulting library can be placed in your GStreamer plugin path for automatic discovery.
Is it free to use? What is the license?
Yes, GStreamer Metal is completely free and open-source, released under the GNU Library General Public License v2 (LGPL v2). You can use it in both open-source and commercial applications without licensing fees.
What GStreamer elements are included?
The plugin provides seven GPU-accelerated elements: vfmetalcompositor (video mixing), vfmetalvideosink (display), vfmetalvideofilter (15 visual effects), vfmetalconvertscale (format conversion and scaling), vfmetaltransform (rotation/flip/crop), vfmetaldeinterlace (interlace removal), and vfmetaloverlay (image compositing).
Can I use it in iOS apps?
Yes. For iOS, the plugin builds as a static library (libgstvfmetal.a) with a gstvfmetal_static.h header for static registration. It integrates with the GStreamer iOS SDK and supports the video formats commonly used on iOS.
How does GPU processing compare to CPU-based elements?
GPU-accelerated processing provides significant performance improvements over CPU-based GStreamer elements. The zero-copy architecture and single-pass processing minimize data transfers and frame buffering. Elements automatically bypass GPU work when configured at identity values, ensuring no overhead when processing is not needed.
Get Started with GStreamer Metal
Accelerate your video processing pipeline on Apple platforms with GPU-powered GStreamer elements.