The viewer finds the camera on the network, connects, even reports frames arriving — and the video window stays black. On one machine it works, on another the identical build shows nothing. That split is the signature of missing GStreamer runtime plugin packages, not a camera fault. This guide is for integrators driving GigE area scan cameras with GStreamer-based viewer software, especially viewers built or deployed on a hand-assembled Windows toolchain. You will confirm where the display pipeline dies, install the exact plugin packages the render path needs, and rule out the acquisition-side causes — packet size, driver mismatch, cabling — when the plugins are already present. The fix takes minutes and needs no recompile.
Why the viewer connects but shows no video
Discovery, connection and acquisition run inside the viewer's own GigE Vision libraries. The picture on screen is drawn by GStreamer elements that ship in separate runtime plugin packages — and an install list written for compiling leaves those packages out.
GStreamer ships as a core runtime plus four plugin sets. The core links and schedules elements; it draws nothing and decodes nothing on its own. A viewer's display path is a second pipeline: the acquisition library hands each frame over, a conversion element reformats it, and a system video sink paints the window. If one element in that chain is missing, linking fails before the first frame reaches the screen.
The camera keeps streaming and the acquisition counters keep rising, so the camera side looks healthy — because it is. The failure sits entirely between the received frame and your monitor. That is why reinstalling camera drivers or swapping network switches changes nothing.
How to tell missing plugins from a camera problem
Run the viewer from a terminal with its GStreamer debug output raised (one common flag is --gst-debug-level=4) and read where the log stops: frames arriving followed by a failure at the display element is the plugin signature, not a camera fault.
The log sorts into three patterns. Frames arrive, then linking fails with a no-such-element error, or the console prints an explicit missing-plugin warning: that is the render path, and the package list in the next section fixes it. The log stops before display with packet-size, test-packet or parameter-read errors: that is acquisition, and the camera-side checks near the end of this guide apply. The window updates but the image is grey: frames render fine and exposure or lighting is the real problem — see the grey-image checklist linked below.
Always diagnose from a terminal rather than a double-clicked launch: the missing-plugin warning is written to the console, and a windowed start gives the message nowhere to appear.
Which GStreamer plugin packages does a viewer need?
Install four plugin sets next to the core runtime — gst-plugins-base, gst-plugins-good, gst-plugins-bad and gst-plugins-ugly — because base carries the mandatory conversion and hand-off elements, good the everyday system elements, and bad and ugly most of the decoders and platform display sinks a viewer can pick.
- gst-plugins-base — the mandatory plumbing: capability negotiation, pixel-format conversion and the hand-off points between the viewer's acquisition code and the display pipeline.
- gst-plugins-good — the well-supported everyday set, including several system input and output elements.
- gst-plugins-bad — the larger, faster-moving set: extra codecs, filters and several platform-specific display sinks.
- gst-plugins-ugly — the codecs that licensing keeps out of the other sets.
A viewer that only displays raw camera frames sometimes runs on base and good alone. The moment it decodes a compressed stream — an H.264 or H.265 tap, for example — or selects a specific display sink, bad or ugly enters the path. Install all four in one pass: the sets coexist by design, and a partial install only moves the failure one element later. If your viewer decodes compressed video, also add your build environment's package that wraps the common decoder library; its name differs per platform.
What to install on a Windows mingw64 toolchain
Install five mingw64 packages by name with pacman — the GStreamer runtime plus the base, good, bad and ugly plugin sets — then close and reopen the viewer, because GStreamer scans and loads plugins only when the process starts.
pacman -S mingw-w64-x86_64-gstreamer
pacman -S mingw-w64-x86_64-gst-plugins-base
pacman -S mingw-w64-x86_64-gst-plugins-good
pacman -S mingw-w64-x86_64-gst-plugins-bad
pacman -S mingw-w64-x86_64-gst-plugins-ugly
These are the mingw-w64-x86_64 package names; other build environments prefix the same plugin-set names differently, and one pacman call accepts all five names at once. The plugin sets must come from the same environment as the GStreamer runtime the viewer links against — a second, unrelated GStreamer installation on the same machine is a classic way to end up with mismatched elements even after every package is present.
Why the plugin packages were missing after a successful build
Plugin packages are runtime dependencies rather than build dependencies. The compiler and the build system need only the core libraries, so an install list written for building compiles and links cleanly while leaving the machine with nothing that can render video.
Build systems track what the compiler needs: headers, import libraries, code generators. Plugin packages add nothing at link time, so they never enter that list, and a build job that compiles the viewer but never launches it cannot catch the gap. The result is a machine that builds, links, discovers cameras, negotiates a connection — and then has nothing to draw with.
Treat the plugin sets as part of deployment, not part of compilation. A viewer built from source, or received as a bare binary, needs its runtime element packages installed on every target PC it will run on.
Why the same viewer works on Linux out of the box
A desktop Linux distribution installs the GStreamer plugin sets automatically as dependencies of its desktop and media stack, so the display elements are already present. A hand-assembled Windows toolchain contains only the packages you named explicitly.
Linux can reproduce the failure too: a minimal server install or a container that runs just the viewer has no desktop media stack, and the same black window appears. The fix is identical, using that distribution's own plugin packages. The viewer did not behave differently on the two machines; the machines started from different baselines.
When a black window is not the plugins
Work down this list when the plugin packages are installed and the window is still black. Each of these causes fails in the log before any display element appears, so the debug output sorts them from the plugin case in seconds.
- Packet-size negotiation. Errors about the packet size, or a test packet that never arrives, mean the GigE link never stabilised. Fix the order of operations with set the packet size before starting acquisition; if the probe itself fails, follow the test-packet negotiation fix; and when the negotiated size exceeds the path MTU (a standard Ethernet frame carries 1500 bytes, a jumbo frame up to 9000), set the MTU cap.
- Link below gigabit. A switch or port that falls back to 100 Mbit/s carries roughly one tenth of a gigabit link's bandwidth and cannot hold a streaming camera; the symptom matches the below-gigabit packet-size error.
- Driver mismatch. Parameter reads failing immediately after connect point at the wrong filter driver; the failed-parameter fix walks the driver check.
- Frames render but the image is grey. A live, grey picture is exposure or lighting, not display — the grey-image checks.
- Frame-grabber set-ups. A connected Camera Link or analog camera with no image is usually cabling — the frame-grabber wiring checks.
- USB cameras with power but no enumeration are a cable or port matter — the USB link checks after a cable swap.
How to verify the fix and stop it recurring
Close and reopen the viewer after installing the packages — GStreamer scans its plugin directories only when the process starts — then connect and confirm the window updates in step with the acquisition counter before changing any camera setting.
- Install the five packages from the list above, in the same environment the viewer runs in.
- Close and reopen the viewer, so its plugin scan picks up the new elements.
- Connect to the camera and check that the window updates in step with the acquisition counter — at 30 fps, both advance by roughly 30 frames each second.
- Re-run the same command that failed, with debug output raised: the missing-plugin warning is gone and the window renders.
To keep the next machine from repeating this, add the five packages to your machine image or deployment script wherever the viewer itself is installed, and record them as runtime requirements in the deployment notes. A viewer shipped without its plugin sets shows this exact symptom on every fresh PC it touches.
If your checks point at the camera instead of the viewer, the packet-size and driver guides above are the usual next stops, and the systems topic page collects the rest. For help sizing or replacing a camera that genuinely fails acquisition, use the camera finder or the contact page.
Questions
Can I install only the plugin I am missing instead of all four packages?
You can, once the debug log has named the missing element. Querying that element with GStreamer's inspection tool tells you which package provides it. In practice, installing base, good, bad and ugly in one pass is faster: the sets coexist by design, and a second missing element an hour later costs more than the extra download does up front.
Does a missing plugin set also break recording and snapshot saving?
Yes. Encoders, multiplexers and file sinks are elements that live in the same plugin packages as the display sink, so a viewer can acquire and even show video while recording fails. If saving misbehaves after the live window works, check that the encoder element resolves with the inspection tool before suspecting the camera or the disk.
Why does the missing-plugin warning appear only in the console?
The warning is printed to the terminal the viewer was started from, and a viewer launched by double-clicking has no terminal, so the message has nowhere to go. Always start a misbehaving viewer from a command prompt with debug output raised; that is also where the exact element name for the inspection tool appears.
Does this fix apply the same way to a real camera and to a test camera?
Yes. Rendering happens after acquisition and is independent of where frames come from, so the same four plugin packages draw a virtual test camera and a real one. That is what makes a test camera a clean diagnostic: when it also shows a black window, your camera, lens, cable and network are already cleared.
Do the plugin packages change camera discovery or GigE Vision performance?
No. Discovery, packet negotiation and acquisition belong to the viewer's libraries and the network stack, which the plugin packages never touch. Installing them adds media elements only, so frame rate, latency and bandwidth stay as they were, and packet-size settings tuned earlier remain valid.