fix(media): say why a video-only file will not play instead of blaming a missing plug-in

Playing a file with no audio track on an item whose video output is disabled --
or whose display is unplugged, which drops FPP into the same fallback -- produced
three messages, each pointing somewhere the problem was not:

  GStreamer sync error (src=decodebin0): Your GStreamer installation is missing a plug-in.
  GStreamer sync error (src=qtdemux0): Internal data stream error.
  GStreamer: pipeline never reached PLAYING within 15000ms — A PipeWire restart
             under a running fppd does this; fppd must be restarted to reconnect.

Nothing was missing, the stream was not corrupt, and PipeWire was uninvolved.  The
audio-only fallback pins decodebin to caps="audio/x-raw", so a file with no audio
gives it nothing to expose and the autoplug failure surfaces as a missing plug-in.
Reported as #2839, where it cost the reporter a hunt for absent packages.

Only that fallback is affected.  The video pipeline links its pads by hand and
OnNoMorePads already tears down the unconnected audio chain for video-only media,
so with a display attached these files play silently and correctly -- confirmed on
a Pi with an HDMI display, where the same file plays clean with the video output
set and fails the moment it is disabled.

So name the fallback's decodebin and watch pad-added.  GStreamer itself then
answers whether the file yielded decodable audio: no probe, no TagLib guess (its
zero-channel answer cannot distinguish "no audio track" from "container I cannot
parse"), and nothing added to the normal start path.  The demuxer's follow-on
error is folded into the same event rather than logged as a second, unrelated
failure, and the raw GStreamer wording is kept at debug level.

A missing audio pad is not on its own evidence about the file, which the first
version of this got wrong: stop PipeWire under a running fppd, play a plain WAV,
and pwsink errors before decodebin ever gets that far -- reporting a backend
outage as "this file has no audio" is a worse lie than the one being fixed.  The
error has to come from inside the decode chain too, so the source is walked up
GST_OBJECT_PARENT to the named decodebin before the file is blamed.

Separately, the preroll check reported GST_STATE_CHANGE_FAILURE and a genuine
timeout identically.  An element that errors returns FAILURE at once, so the
message claimed a 15-second wait it never made and named a PipeWire restart that
never happened -- for any failure at all.  Split the two: FAILURE points at the
error the bus handler has already logged, and only a real timeout keeps the
stale-connection advice.  Both paths verified on a single-core AM335x board,
which is slow enough to lose the race to the bus handler and take that branch.

The entry still ends rather than holding its duration, so a playlist advances
early past such an item; making it consume the full duration means synthesising
playback timing and is left alone here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: dkulp

src/mediaoutput/GStreamerOut.cpp

@@ -1666,7 +1666,7 @@ int GStreamerOutput::Start(int msTime) {
         }
         std::string rateCaps = decodeRate ? ",rate=" + std::to_string(decodeRate) : "";
         std::string pipelineStr =
-            "filesrc location=\"" + fullPath + "\" ! decodebin expose-all-streams=false caps=\"audio/x-raw\" ! audioconvert ! audioresample ! "
+            "filesrc location=\"" + fullPath + "\" ! decodebin name=decoder expose-all-streams=false caps=\"audio/x-raw\" ! audioconvert ! audioresample ! "
             "audio/x-raw" + rateCaps + chOrderCaps + " ! " + chOrderPermute +
             "tee name=t "
             "t. ! queue ! volume name=vol ! " + sinkStr + " "
@@ -1685,6 +1685,18 @@ int GStreamerOutput::Start(int msTime) {
             return 0;
         }
 
+        // This pipeline's only sink is audio, so a file with nothing decodable
+        // to feed it cannot play at all -- and the caps filter above turns that
+        // into an autoplug failure decodebin reports as a missing plug-in, which
+        // sends people off installing packages that were never the problem.
+        // Watch the pads so the real reason can be given instead; the linking
+        // itself stays with gst_parse_launch's own delayed-link handler.
+        m_audioOnlyPipeline = true;
+        if (GstElement* fbDecoder = gst_bin_get_by_name(GST_BIN(m_pipeline), "decoder")) {
+            g_signal_connect(fbDecoder, "pad-added", G_CALLBACK(OnPadAdded), this);
+            gst_object_unref(fbDecoder);
+        }
+
         // Get the volume element for later control
         m_volume = gst_bin_get_by_name(GST_BIN(m_pipeline), "vol");
 
@@ -1911,17 +1923,34 @@ int GStreamerOutput::Start(int msTime) {
             // the failure is completely invisible.
             if (!cancel->load()) {
                 GstState startedState = GST_STATE_NULL;
-                if (gst_element_get_state(pipeline, &startedState, nullptr,
-                                          (GstClockTime)PREROLL_TIMEOUT_MS * GST_MSECOND) != GST_STATE_CHANGE_SUCCESS ||
-                    startedState != GST_STATE_PLAYING) {
+                GstStateChangeReturn scr = gst_element_get_state(pipeline, &startedState, nullptr,
+                                                                 (GstClockTime)PREROLL_TIMEOUT_MS * GST_MSECOND);
+                if (scr != GST_STATE_CHANGE_SUCCESS || startedState != GST_STATE_PLAYING) {
                     if (!cancel->load()) {
-                        LogErr(VB_MEDIAOUT,
-                               "GStreamer: pipeline never reached PLAYING within %dms (state=%d) — output will be "
-                               "silent. A PipeWire restart under a running fppd does this; fppd must be restarted "
-                               "to reconnect.\n",
-                               PREROLL_TIMEOUT_MS, startedState);
-                        WarningHolder::AddWarningTimeout(60, 30,
-                                                        "Media playback did not start (audio backend connection lost — restart FPPD)");
+                        // FAILURE and "still not there after the timeout" are
+                        // different faults and want different advice, but this
+                        // reported both as the stale-PipeWire-connection case.
+                        // An element that errors out returns FAILURE straight
+                        // away, so the message claimed a 15-second timeout it
+                        // had not waited for and blamed a PipeWire restart that
+                        // had not happened -- for any failure at all, including
+                        // a media file the pipeline simply could not play.  The
+                        // bus error handler has already logged the real cause in
+                        // that case, so say nothing more than the outcome here.
+                        if (scr == GST_STATE_CHANGE_FAILURE) {
+                            LogErr(VB_MEDIAOUT,
+                                   "GStreamer: pipeline failed to start (state=%s) — see the error logged above "
+                                   "for the cause.\n",
+                                   gst_element_state_get_name(startedState));
+                        } else {
+                            LogErr(VB_MEDIAOUT,
+                                   "GStreamer: pipeline never reached PLAYING within %dms (state=%s) — output will "
+                                   "be silent. A PipeWire restart under a running fppd does this; fppd must be "
+                                   "restarted to reconnect.\n",
+                                   PREROLL_TIMEOUT_MS, gst_element_state_get_name(startedState));
+                            WarningHolder::AddWarningTimeout(60, 30,
+                                                            "Media playback did not start (audio backend connection lost — restart FPPD)");
+                        }
                     }
                 }
             }
@@ -2963,7 +2992,60 @@ GstBusSyncReply GStreamerOutput::BusSyncHandler(GstBus* bus, GstMessage* msg, gp
         // disconnected during playback — treat as non-fatal.
         bool isDirectKmsSink = (strncmp(srcName, "dkms_", 5) == 0);
 
-        if (isAES67Branch || isVideoPWSink || isDirectKmsSink) {
+        // A file with nothing decodable to feed the audio-only pipeline fails
+        // here, and the raw GStreamer wording is actively misleading: decodebin
+        // reports its autoplug failure as "your installation is missing a
+        // plug-in" (nothing is missing -- there is simply no audio to plug), and
+        // the demuxer then follows with a generic "Internal data stream error".
+        // A video-only clip played on an item whose video output is disabled or
+        // whose display is unplugged lands exactly here, so say what actually
+        // happened and what to do about it.  Everything else keeps the raw
+        // message -- this only claims the case it can prove, which is that
+        // decodebin never produced an audio pad.
+        // "No audio pad yet" is not on its own evidence that the file has no
+        // audio: anything that fails before decodebin gets that far leaves the
+        // flag clear too.  Stopping PipeWire under a running fppd and playing a
+        // plain WAV does exactly that -- pwsink errors first, and blaming the
+        // file for an audio-backend outage is a worse lie than the one being
+        // fixed.  So the source has to be the decode chain as well.
+        bool errorFromDecoder = false;
+        for (GstObject* o = GST_MESSAGE_SRC(msg); o; o = GST_OBJECT_PARENT(o)) {
+            const gchar* n = GST_OBJECT_NAME(o);
+            if (n && strcmp(n, "decoder") == 0) {
+                errorFromDecoder = true;
+                break;
+            }
+        }
+        if (self->m_audioOnlyPipeline && errorFromDecoder &&
+            !self->m_sawAudioPad.load(std::memory_order_acquire)) {
+            if (!self->m_reportedNoAudio.exchange(true, std::memory_order_acq_rel)) {
+                LogErr(VB_MEDIAOUT,
+                       "GStreamer: '%s' has no playable audio stream, and no video output is "
+                       "configured for it, so there is nothing to play.  If this is a video-only "
+                       "file, set the item's Video Output to a connected display; FPP falls back to "
+                       "audio-only whenever the chosen display is disabled or unplugged.\n",
+                       self->m_mediaFilename.c_str());
+                WarningHolder::AddWarningTimeout(60, 30,
+                                                "No playable audio in " + self->m_mediaFilename +
+                                                    " and no video output — nothing to play");
+                LogDebug(VB_MEDIAOUT, "GStreamer no-audio underlying error (src=%s): %s\n",
+                         srcName, err->message);
+#ifdef HAS_AES67_GSTREAMER
+                self->DetachAES67Branches();
+#endif
+                self->m_playing = false;
+                if (self->m_mediaOutputStatus) {
+                    self->m_mediaOutputStatus->status = MEDIAOUTPUTSTATUS_IDLE;
+                }
+                self->Stopping();
+                self->Stopped();
+            } else {
+                // The demuxer's follow-on error describes the same event; logging
+                // it again reads as a second, unrelated failure.
+                LogDebug(VB_MEDIAOUT, "GStreamer no-audio follow-on error (src=%s): %s\n",
+                         srcName, err->message);
+            }
+        } else if (isAES67Branch || isVideoPWSink || isDirectKmsSink) {
             LogWarn(VB_MEDIAOUT, "GStreamer non-fatal error (src=%s): %s\n",
                     srcName, err->message);
             LogDebug(VB_MEDIAOUT, "GStreamer AES67 branch debug: %s\n",
@@ -3567,6 +3649,15 @@ void GStreamerOutput::OnPadAdded(GstElement* element, GstPad* pad, gpointer user
     const gchar* name = gst_structure_get_name(gst_caps_get_structure(caps, 0));
     LogDebug(VB_MEDIAOUT, "GStreamer decodebin pad-added: %s\n", name);
 
+    // Record that the file yielded decodable audio, independently of whether
+    // this pipeline has an audio chain to link it into.  The audio-only fallback
+    // links its pads through gst_parse_launch rather than here, so m_audioChain
+    // is null there and the branch below is skipped -- but that pipeline is
+    // exactly the one that needs to know, so the flag is set before the check.
+    if (g_str_has_prefix(name, "audio/")) {
+        self->m_sawAudioPad.store(true, std::memory_order_release);
+    }
+
     if (g_str_has_prefix(name, "audio/") && self->m_audioChain) {
         GstPad* sinkPad = gst_element_get_static_pad(self->m_audioChain, "sink");
         if (sinkPad && !gst_pad_is_linked(sinkPad)) {

src/mediaoutput/GStreamerOut.h

@@ -226,6 +226,18 @@ class GStreamerOutput : public MediaOutputBase {
     bool m_audioLinked = false;            // true when audio pad was connected
     bool m_videoLinked = false;            // true when video pad was connected
 
+    // True when Start() built the audio-only fallback (no video output for this
+    // item), which is the one pipeline shape that cannot survive a file with no
+    // playable audio -- see the no-audio handling in BusSyncHandler().
+    bool m_audioOnlyPipeline = false;
+    // Whether decodebin ever exposed a decoded audio pad.  Written on the
+    // streaming thread from OnPadAdded, read on the bus thread.
+    std::atomic<bool> m_sawAudioPad{false};
+    // Set once the "file has no playable audio" case has been reported, so the
+    // demuxer's follow-on "Internal data stream error" is not logged as a second,
+    // unrelated-looking failure.
+    std::atomic<bool> m_reportedNoAudio{false};
+
 #ifdef HAS_AES67_GSTREAMER
     // Zero-hop AES67 RTP branches attached to the audio tee (Phase 7.9)
     std::vector<AES67Manager::InlineRTPBranch> m_aes67Branches;