play: Add stream-id based selection of streams to match better playbin3's API

As part of this

  - Add accessors for the stream ID and selection API based on the
    stream ID
  - Deprecate the old index-based APIs
  - Remove playbin support
  - Implement the track enable API based on stream selection

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

girs/GstPlay-1.0.gir

@@ -981,7 +981,8 @@ in nanoseconds.</doc>
           </parameter>
         </parameters>
       </method>
-      <method name="set_audio_track" c:identifier="gst_play_set_audio_track" version="1.20">
+      <method name="set_audio_track" c:identifier="gst_play_set_audio_track" version="1.20" deprecated="1" deprecated-version="1.26">
+        <doc-deprecated xml:space="preserve">Use gst_play_set_audio_track_id() instead.</doc-deprecated>
         <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 or %FALSE
@@ -1017,6 +1018,25 @@ Sets the audio track @stream_index.</doc>
           </parameter>
         </parameters>
       </method>
+      <method name="set_audio_track_id" c:identifier="gst_play_set_audio_track_id" version="1.26">
+        <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 or %FALSE
+
+Sets the audio track @stream_id.</doc>
+          <type name="gboolean" c:type="gboolean"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="play" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">#GstPlay instance</doc>
+            <type name="Play" c:type="GstPlay*"/>
+          </instance-parameter>
+          <parameter name="stream_id" transfer-ownership="none" nullable="1" allow-none="1">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">stream id</doc>
+            <type name="utf8" c:type="const gchar*"/>
+          </parameter>
+        </parameters>
+      </method>
       <method name="set_audio_video_offset" c:identifier="gst_play_set_audio_video_offset" glib:set-property="audio-video-offset" version="1.20">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Sets audio-video-offset property by value of @offset</doc>
         <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.h"/>
@@ -1152,7 +1172,8 @@ value.</doc>
           </parameter>
         </parameters>
       </method>
-      <method name="set_subtitle_track" c:identifier="gst_play_set_subtitle_track" version="1.20">
+      <method name="set_subtitle_track" c:identifier="gst_play_set_subtitle_track" version="1.20" deprecated="1" deprecated-version="1.26">
+        <doc-deprecated xml:space="preserve">Use gst_play_set_subtitle_track_id() instead.</doc-deprecated>
         <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 or %FALSE
@@ -1188,6 +1209,25 @@ Sets the subtitle stack @stream_index.</doc>
           </parameter>
         </parameters>
       </method>
+      <method name="set_subtitle_track_id" c:identifier="gst_play_set_subtitle_track_id" version="1.26">
+        <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 or %FALSE
+
+Sets the subtitle track @stream_id.</doc>
+          <type name="gboolean" c:type="gboolean"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="play" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">#GstPlay instance</doc>
+            <type name="Play" c:type="GstPlay*"/>
+          </instance-parameter>
+          <parameter name="stream_id" transfer-ownership="none" nullable="1" allow-none="1">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">stream id</doc>
+            <type name="utf8" c:type="const gchar*"/>
+          </parameter>
+        </parameters>
+      </method>
       <method name="set_subtitle_uri" c:identifier="gst_play_set_subtitle_uri" version="1.20">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Sets the external subtitle URI. This should be combined with a call to
 gst_play_set_subtitle_track_enabled(@play, TRUE) so the subtitles are actually
@@ -1224,6 +1264,34 @@ rendered.</doc>
           </parameter>
         </parameters>
       </method>
+      <method name="set_track_ids" c:identifier="gst_play_set_track_ids" version="1.26">
+        <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 or %FALSE
+
+Sets the selected track stream ids. Setting %NULL as stream id disables the
+corresponding track.</doc>
+          <type name="gboolean" c:type="gboolean"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="play" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">#GstPlay instance</doc>
+            <type name="Play" c:type="GstPlay*"/>
+          </instance-parameter>
+          <parameter name="audio_stream_id" transfer-ownership="none" nullable="1" allow-none="1">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">audio stream id</doc>
+            <type name="utf8" c:type="const gchar*"/>
+          </parameter>
+          <parameter name="video_stream_id" transfer-ownership="none" nullable="1" allow-none="1">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">video stream id</doc>
+            <type name="utf8" c:type="const gchar*"/>
+          </parameter>
+          <parameter name="subtitle_stream_id" transfer-ownership="none" nullable="1" allow-none="1">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">subtitle stream id</doc>
+            <type name="utf8" c:type="const gchar*"/>
+          </parameter>
+        </parameters>
+      </method>
       <method name="set_uri" c:identifier="gst_play_set_uri" glib:set-property="uri" version="1.20">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Sets the next URI to play.</doc>
         <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.h"/>
@@ -1241,7 +1309,8 @@ rendered.</doc>
           </parameter>
         </parameters>
       </method>
-      <method name="set_video_track" c:identifier="gst_play_set_video_track" version="1.20">
+      <method name="set_video_track" c:identifier="gst_play_set_video_track" version="1.20" deprecated="1" deprecated-version="1.26">
+        <doc-deprecated xml:space="preserve">Use gst_play_set_video_track_id() instead.</doc-deprecated>
         <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 or %FALSE
@@ -1277,6 +1346,25 @@ Sets the video track @stream_index.</doc>
           </parameter>
         </parameters>
       </method>
+      <method name="set_video_track_id" c:identifier="gst_play_set_video_track_id" version="1.26">
+        <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 or %FALSE
+
+Sets the video track @stream_id.</doc>
+          <type name="gboolean" c:type="gboolean"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="play" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">#GstPlay instance</doc>
+            <type name="Play" c:type="GstPlay*"/>
+          </instance-parameter>
+          <parameter name="stream_id" transfer-ownership="none" nullable="1" allow-none="1">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">stream id</doc>
+            <type name="utf8" c:type="const gchar*"/>
+          </parameter>
+        </parameters>
+      </method>
       <method name="set_visualization" c:identifier="gst_play_set_visualization" version="1.20">
         <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.h"/>
         <return-value transfer-ownership="none">
@@ -1883,7 +1971,7 @@ See also #gst_play_get_message_bus()</doc-version>
         </parameters>
       </function>
       <function name="parse_error" c:identifier="gst_play_message_parse_error" version="1.20">
-        <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Parse the given error @msg and extract the corresponding #GError</doc>
+        <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Parse the given error @msg and extract the corresponding #GError.</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"/>
@@ -2377,9 +2465,10 @@ unknown.</doc>
           </instance-parameter>
         </parameters>
       </method>
-      <method name="get_index" c:identifier="gst_play_stream_info_get_index" version="1.20">
+      <method name="get_index" c:identifier="gst_play_stream_info_get_index" version="1.20" deprecated="1" deprecated-version="1.26">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info.c">Function to get stream index from #GstPlayStreamInfo instance or -1 if
 unknown.</doc>
+        <doc-deprecated xml:space="preserve">Use gst_play_stream_info_get_stream_id().</doc-deprecated>
         <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info.h"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info.c">the stream index of this stream.</doc>
@@ -2392,6 +2481,20 @@ unknown.</doc>
           </instance-parameter>
         </parameters>
       </method>
+      <method name="get_stream_id" c:identifier="gst_play_stream_info_get_stream_id" version="1.26">
+        <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info.c">A string stream id identifying this #GstPlayStreamInfo.</doc>
+        <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info.h"/>
+        <return-value transfer-ownership="none">
+          <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info.c">stream id string.</doc>
+          <type name="utf8" c:type="const gchar*"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="info" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info.c">a #GstPlayStreamInfo</doc>
+            <type name="PlayStreamInfo" c:type="const GstPlayStreamInfo*"/>
+          </instance-parameter>
+        </parameters>
+      </method>
       <method name="get_stream_type" c:identifier="gst_play_stream_info_get_stream_type" version="1.20">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info.c">Function to return human readable name for the stream type
 of the given @info (ex: "audio", "video", "subtitle")</doc>
@@ -2896,7 +2999,7 @@ freed using gst_play_visualization_free().</doc>
       </parameters>
     </function>
     <function name="play_message_parse_error" c:identifier="gst_play_message_parse_error" moved-to="PlayMessage.parse_error" version="1.20">
-      <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Parse the given error @msg and extract the corresponding #GError</doc>
+      <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c">Parse the given error @msg and extract the corresponding #GError.</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"/>

subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay-media-info-private.h

@@ -119,7 +119,7 @@ G_GNUC_INTERNAL GstPlayMediaInfo*   gst_play_media_info_new
 G_GNUC_INTERNAL GstPlayMediaInfo*   gst_play_media_info_copy
                                       (GstPlayMediaInfo *ref);
 G_GNUC_INTERNAL GstPlayStreamInfo*  gst_play_stream_info_new
-                                      (gint stream_index, GType type);
+                                      (gint stream_index, const gchar *stream_id, GType type);
 G_GNUC_INTERNAL GstPlayStreamInfo*  gst_play_stream_info_copy
                                       (GstPlayStreamInfo *ref);
 

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

@@ -74,6 +74,9 @@ gst_play_stream_info_class_init (GstPlayStreamInfoClass * klass)
  * unknown.
  *
  * Returns: the stream index of this stream.
+ *
+ * Deprecated: 1.26: Use gst_play_stream_info_get_stream_id().
+ *
  * Since: 1.20
  */
 gint
@@ -103,8 +106,11 @@ gst_play_stream_info_get_stream_type (const GstPlayStreamInfo * info)
     return "video";
   else if (GST_IS_PLAY_AUDIO_INFO (info))
     return "audio";
-  else
+  else if (GST_IS_PLAY_SUBTITLE_INFO (info))
     return "subtitle";
+  else
+    g_assert_not_reached ();
+  return NULL;
 }
 
 /**
@@ -139,6 +145,24 @@ gst_play_stream_info_get_codec (const GstPlayStreamInfo * info)
   return info->codec;
 }
 
+/**
+ * gst_play_stream_info_get_stream_id:
+ * @info: a #GstPlayStreamInfo
+ *
+ * A string stream id identifying this #GstPlayStreamInfo.
+ *
+ * Returns: stream id string.
+ *
+ * Since: 1.26
+ */
+const gchar *
+gst_play_stream_info_get_stream_id (const GstPlayStreamInfo * info)
+{
+  g_return_val_if_fail (GST_IS_PLAY_STREAM_INFO (info), NULL);
+
+  return info->stream_id;
+}
+
 /**
  * gst_play_stream_info_get_caps:
  * @info: a #GstPlayStreamInfo
@@ -610,7 +634,8 @@ gst_play_media_info_copy (GstPlayMediaInfo * ref)
 }
 
 GstPlayStreamInfo *
-gst_play_stream_info_new (gint stream_index, GType type)
+gst_play_stream_info_new (gint stream_index, const gchar * stream_id,
+    GType type)
 {
   GstPlayStreamInfo *info = NULL;
 
@@ -618,10 +643,13 @@ gst_play_stream_info_new (gint stream_index, GType type)
     info = (GstPlayStreamInfo *) gst_play_audio_info_new ();
   else if (type == GST_TYPE_PLAY_VIDEO_INFO)
     info = (GstPlayStreamInfo *) gst_play_video_info_new ();
-  else
+  else if (type == GST_TYPE_PLAY_SUBTITLE_INFO)
     info = (GstPlayStreamInfo *) gst_play_subtitle_info_new ();
+  else
+    g_assert_not_reached ();
 
   info->stream_index = stream_index;
+  info->stream_id = g_strdup (stream_id);
 
   return info;
 }

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

@@ -55,7 +55,7 @@ typedef struct _GstPlayStreamInfoClass GstPlayStreamInfoClass;
 GST_PLAY_API
 GType         gst_play_stream_info_get_type (void);
 
-GST_PLAY_API
+GST_PLAY_DEPRECATED_FOR(gst_play_stream_info_get_stream_id)
 gint          gst_play_stream_info_get_index (const GstPlayStreamInfo *info);
 
 GST_PLAY_API
@@ -70,6 +70,9 @@ GstCaps*      gst_play_stream_info_get_caps  (const GstPlayStreamInfo *info);
 GST_PLAY_API
 const gchar*  gst_play_stream_info_get_codec (const GstPlayStreamInfo *info);
 
+GST_PLAY_API
+const gchar*  gst_play_stream_info_get_stream_id (const GstPlayStreamInfo *info);
+
 /**
  * GST_TYPE_PLAY_VIDEO_INFO:
  * Since: 1.20

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

@@ -273,17 +273,34 @@ GST_PLAY_API
 void         gst_play_set_subtitle_track_enabled    (GstPlay    * play,
                                                      gboolean enabled);
 
-GST_PLAY_API
+GST_PLAY_DEPRECATED_FOR(gst_play_set_audio_track_id)
 gboolean     gst_play_set_audio_track               (GstPlay    *play,
                                                      gint stream_index);
 
-GST_PLAY_API
+GST_PLAY_DEPRECATED_FOR(gst_play_set_video_track_id)
 gboolean     gst_play_set_video_track               (GstPlay    *play,
                                                      gint stream_index);
 
-GST_PLAY_API
+GST_PLAY_DEPRECATED_FOR(gst_play_set_subtitle_track_id)
 gboolean     gst_play_set_subtitle_track            (GstPlay    *play,
                                                      gint stream_index);
+GST_PLAY_API
+gboolean     gst_play_set_audio_track_id            (GstPlay     *play,
+                                                     const gchar *stream_id);
+
+GST_PLAY_API
+gboolean     gst_play_set_video_track_id            (GstPlay     *play,
+                                                     const gchar *stream_id);
+
+GST_PLAY_API
+gboolean     gst_play_set_subtitle_track_id         (GstPlay     *play,
+                                                     const gchar *stream_id);
+
+GST_PLAY_API
+gboolean     gst_play_set_track_ids                 (GstPlay     *play,
+                                                     const gchar *audio_stream_id,
+                                                     const gchar *video_stream_id,
+                                                     const gchar *subtitle_stream_id);
 
 GST_PLAY_API
 GstPlayMediaInfo *    gst_play_get_media_info     (GstPlay * play);