play: Include pipeline dump in error details structure

This can be useful for debugging purposes. It can't be done on application side
because the on_error callback tears down the pipeline.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/5828>

girs/GstPlay-1.0.gir

@@ -357,6 +357,20 @@ performed.</doc>
           </parameter>
         </parameters>
       </constructor>
+      <function name="config_get_pipeline_dump_in_error_details" c:identifier="gst_play_config_get_pipeline_dump_in_error_details" version="1.24">
+        <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.h"/>
+        <return-value transfer-ownership="none">
+          <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">%TRUE if pipeline dumps are included in #GstPlay error message
+details.</doc>
+          <type name="gboolean" c:type="gboolean"/>
+        </return-value>
+        <parameters>
+          <parameter name="config" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">a #GstPlay configuration</doc>
+            <type name="Gst.Structure" c:type="const GstStructure*"/>
+          </parameter>
+        </parameters>
+      </function>
       <function name="config_get_position_update_interval" c:identifier="gst_play_config_get_position_update_interval" version="1.20">
         <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.h"/>
         <return-value transfer-ownership="none">
@@ -398,6 +412,27 @@ gst_play_config_set_user_agent() if any.</doc>
           </parameter>
         </parameters>
       </function>
+      <function name="config_set_pipeline_dump_in_error_details" c:identifier="gst_play_config_set_pipeline_dump_in_error_details" version="1.24">
+        <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">When enabled, the error message emitted by #GstPlay will include a pipeline
+dump (in Graphviz DOT format) in the error details #GstStructure. The field
+name is `pipeline-dump`.
+
+This option is disabled by default.</doc>
+        <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.h"/>
+        <return-value transfer-ownership="none">
+          <type name="none" c:type="void"/>
+        </return-value>
+        <parameters>
+          <parameter name="config" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">a #GstPlay configuration</doc>
+            <type name="Gst.Structure" c:type="GstStructure*"/>
+          </parameter>
+          <parameter name="value" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Include pipeline dumps in error details, or not.</doc>
+            <type name="gboolean" c:type="gboolean"/>
+          </parameter>
+        </parameters>
+      </function>
       <function name="config_set_position_update_interval" c:identifier="gst_play_config_set_position_update_interval" version="1.20">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">set desired interval in milliseconds between two position-updated messages.
 pass 0 to stop updating the position.</doc>

subprojects/gst-docs/symbols/symbol_index.json

@@ -40699,9 +40699,11 @@
   "gst_play_audio_info_get_max_bitrate",
   "gst_play_audio_info_get_sample_rate",
   "gst_play_color_balance_type_get_name",
+  "gst_play_config_get_pipeline_dump_in_error_details",
   "gst_play_config_get_position_update_interval",
   "gst_play_config_get_seek_accurate",
   "gst_play_config_get_user_agent",
+  "gst_play_config_set_pipeline_dump_in_error_details",
   "gst_play_config_set_position_update_interval",
   "gst_play_config_set_seek_accurate",
   "gst_play_config_set_user_agent",

subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c

@@ -125,6 +125,7 @@ typedef enum
   CONFIG_QUARK_USER_AGENT = 0,
   CONFIG_QUARK_POSITION_INTERVAL_UPDATE,
   CONFIG_QUARK_ACCURATE_SEEK,
+  CONFIG_QUARK_PIPELINE_DUMP_IN_ERROR_DETAILS,
 
   CONFIG_QUARK_MAX
 } ConfigQuarkId;
@@ -133,6 +134,7 @@ static const gchar *_config_quark_strings[] = {
   "user-agent",
   "position-interval-update",
   "accurate-seek",
+  "pipeline-dump-in-error-details",
 };
 
 static GQuark _config_quark_table[CONFIG_QUARK_MAX];
@@ -316,6 +318,7 @@ gst_play_init (GstPlay * self)
   self->config = gst_structure_new_id (QUARK_CONFIG,
       CONFIG_QUARK (POSITION_INTERVAL_UPDATE), G_TYPE_UINT, DEFAULT_POSITION_UPDATE_INTERVAL_MS,
       CONFIG_QUARK (ACCURATE_SEEK), G_TYPE_BOOLEAN, FALSE,
+      CONFIG_QUARK (PIPELINE_DUMP_IN_ERROR_DETAILS), G_TYPE_BOOLEAN, FALSE,
       NULL);
   /* *INDENT-ON* */
 
@@ -968,12 +971,37 @@ remove_ready_timeout_source (GstPlay * self)
 static void
 on_error (GstPlay * self, GError * err, const GstStructure * details)
 {
+#ifndef GST_DISABLE_GST_DEBUG
+  GstStructure *extra_details = NULL;
+  gchar *dot_data = NULL;
+#endif
+
   GST_ERROR_OBJECT (self, "Error: %s (%s, %d)", err->message,
       g_quark_to_string (err->domain), err->code);
 
+#ifndef GST_DISABLE_GST_DEBUG
+  extra_details = gst_structure_copy (details);
+  if (gst_play_config_get_pipeline_dump_in_error_details (self->config)) {
+    dot_data = gst_debug_bin_to_dot_data (GST_BIN_CAST (self->playbin),
+        GST_DEBUG_GRAPH_SHOW_ALL);
+    gst_structure_set (extra_details, "pipeline-dump", G_TYPE_STRING, dot_data,
+        NULL);
+  }
+#endif
   api_bus_post_message (self, GST_PLAY_MESSAGE_ERROR,
       GST_PLAY_MESSAGE_DATA_ERROR, G_TYPE_ERROR, err,
-      GST_PLAY_MESSAGE_DATA_ERROR_DETAILS, GST_TYPE_STRUCTURE, details, NULL);
+      GST_PLAY_MESSAGE_DATA_ERROR_DETAILS, GST_TYPE_STRUCTURE,
+#ifndef GST_DISABLE_GST_DEBUG
+      extra_details
+#else
+      details
+#endif
+      , NULL);
+
+#ifndef GST_DISABLE_GST_DEBUG
+  g_free (dot_data);
+  gst_structure_free (extra_details);
+#endif
 
   g_error_free (err);
 
@@ -4495,6 +4523,51 @@ gst_play_config_get_seek_accurate (const GstStructure * config)
   return accurate;
 }
 
+/**
+ * gst_play_config_set_pipeline_dump_in_error_details:
+ * @config: a #GstPlay configuration
+ * @value: Include pipeline dumps in error details, or not.
+ *
+ * When enabled, the error message emitted by #GstPlay will include a pipeline
+ * dump (in Graphviz DOT format) in the error details #GstStructure. The field
+ * name is `pipeline-dump`.
+ *
+ * This option is disabled by default.
+ *
+ * Since: 1.24
+ */
+void
+gst_play_config_set_pipeline_dump_in_error_details (GstStructure * config,
+    gboolean value)
+{
+  g_return_if_fail (config != NULL);
+
+  gst_structure_id_set (config, CONFIG_QUARK (PIPELINE_DUMP_IN_ERROR_DETAILS),
+      G_TYPE_BOOLEAN, value, NULL);
+}
+
+/**
+ * gst_play_config_get_pipeline_dump_in_error_details:
+ * @config: a #GstPlay configuration
+ *
+ * Returns: %TRUE if pipeline dumps are included in #GstPlay error message
+ * details.
+ *
+ * Since: 1.24
+ */
+gboolean
+gst_play_config_get_pipeline_dump_in_error_details (const GstStructure * config)
+{
+  gboolean value = FALSE;
+
+  g_return_val_if_fail (config != NULL, FALSE);
+
+  gst_structure_id_get (config, CONFIG_QUARK (PIPELINE_DUMP_IN_ERROR_DETAILS),
+      G_TYPE_BOOLEAN, &value, NULL);
+
+  return value;
+}
+
 /**
  * gst_play_get_video_snapshot:
  * @play: #GstPlay instance

subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.h

@@ -378,6 +378,13 @@ void           gst_play_config_set_seek_accurate (GstStructure * config, gboolea
 GST_PLAY_API
 gboolean       gst_play_config_get_seek_accurate (const GstStructure * config);
 
+GST_PLAY_API
+void           gst_play_config_set_pipeline_dump_in_error_details (GstStructure * config,
+                                                                   gboolean       value);
+
+GST_PLAY_API
+gboolean       gst_play_config_get_pipeline_dump_in_error_details (const GstStructure * config);
+
 /**
  * GstPlaySnapshotFormat:
  * @GST_PLAY_THUMBNAIL_RAW_NATIVE: raw native format.