[vlc-devel] [PATCH] libvlc: rename media slave to associated media

Thomas Guillem thomas at gllm.fr
Tue Sep 11 11:49:30 CEST 2018


This term is not technically correct. Indeed, it refers to the current
implementation detail where the associated input is driven by the main input
thread. We already discussed about using a thread for each associated inputs.
In that case, it won't be driven by the main input thread anymore.
Furthermore, with the future vlc_clock, the audio track (that could come from
an associated media) is very likely to drive the clock and have an impact on
the video track (that could come from the main input).

The old slave API is deprecated but still available in VLC 4.0 (but will be
gone after).

There are still references of slave in the input_thread.h CORE API. But this
API will be replaced by the future vlc_player.
---
 include/vlc/deprecated.h          | 124 ++++++++++++++++++++++++++++++
 include/vlc/libvlc_media.h        |  81 +++++++++----------
 include/vlc/libvlc_media_player.h |  22 +++---
 lib/libvlc.sym                    |   5 ++
 lib/media.c                       |  87 +++++++++++++--------
 lib/media_player.c                |  15 +++-
 6 files changed, 250 insertions(+), 84 deletions(-)

diff --git a/include/vlc/deprecated.h b/include/vlc/deprecated.h
index bc73e493c2..27ec80b944 100644
--- a/include/vlc/deprecated.h
+++ b/include/vlc/deprecated.h
@@ -90,6 +90,130 @@ libvlc_media_parse_async( libvlc_media_t *p_md );
 LIBVLC_DEPRECATED LIBVLC_API int
    libvlc_media_is_parsed( libvlc_media_t *p_md );
 
+/**
+ * Type of a media slave: subtitle or audio.
+ * @deprecated Use @ref libvlc_associated_media_type_t instead.
+ */
+typedef enum libvlc_media_slave_type_t
+{
+    libvlc_media_slave_type_subtitle,
+    libvlc_media_slave_type_audio,
+} libvlc_media_slave_type_t;
+
+/**
+ * A slave of a libvlc_media_t
+ * @deprecated Use @ref libvlc_associated_media_t instead.
+ * \see libvlc_media_slaves_get
+ */
+typedef struct libvlc_media_slave_t
+{
+    char *                          psz_uri;
+    libvlc_media_slave_type_t       i_type;
+    unsigned int                    i_priority;
+} libvlc_media_slave_t;
+
+/**
+ * Add a slave to the current media.
+ *
+ * A slave is an external input source that may contains an additional subtitle
+ * track (like a .srt) or an additional audio track (like a .ac3).
+ *
+ * \note This function must be called before the media is parsed (via
+ * libvlc_media_parse_with_options()) or before the media is played (via
+ * libvlc_media_player_play())
+ *
+ * @deprecated Use @ref libvlc_media_add_associated_media instead.
+ * \version LibVLC 3.0.0 and later.
+ *
+ * \param p_md media descriptor object
+ * \param i_type subtitle or audio
+ * \param i_priority from 0 (low priority) to 4 (high priority)
+ * \param psz_uri Uri of the slave (should contain a valid scheme).
+ *
+ * \return 0 on success, -1 on error.
+ */
+LIBVLC_DEPRECATED LIBVLC_API
+int libvlc_media_slaves_add( libvlc_media_t *p_md,
+                             libvlc_media_slave_type_t i_type,
+                             unsigned int i_priority,
+                             const char *psz_uri );
+
+/**
+ * Clear all slaves previously added by libvlc_media_slaves_add() or
+ * internally.
+ *
+ * @deprecated Use @ref libvlc_media_clear_associated_medias instead.
+ * \version LibVLC 3.0.0 and later.
+ *
+ * \param p_md media descriptor object
+ */
+LIBVLC_DEPRECATED LIBVLC_API
+void libvlc_media_slaves_clear( libvlc_media_t *p_md );
+
+/**
+ * Get a media descriptor's slave list
+ *
+ * The list will contain slaves parsed by VLC or previously added by
+ * libvlc_media_slaves_add(). The typical use case of this function is to save
+ * a list of slave in a database for a later use.
+ *
+ * @deprecated Use @ref libvlc_media_get_associated_medias instead.
+ * \version LibVLC 3.0.0 and later.
+ *
+ * \see libvlc_media_slaves_add
+ *
+ * \param p_md media descriptor object
+ * \param ppp_slaves address to store an allocated array of slaves (must be
+ * freed with libvlc_media_slaves_release()) [OUT]
+ *
+ * \return the number of slaves (zero on error)
+ */
+LIBVLC_DEPRECATED LIBVLC_API
+unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
+                                      libvlc_media_slave_t ***ppp_slaves );
+
+/**
+ * Release a media descriptor's slave list
+ *
+ * @deprecated Use @ref libvlc_media_get_associated_medias instead.
+ * \version LibVLC 3.0.0 and later.
+ *
+ * \param pp_slaves slave array to release
+ * \param i_count number of elements in the array
+ */
+LIBVLC_DEPRECATED LIBVLC_API
+void libvlc_media_slaves_release( libvlc_media_slave_t **pp_slaves,
+                                  unsigned int i_count );
+
+/** @}*/
+
+/**
+ * \ingroup libvlc libvlc_media_player
+ */
+
+/**
+ * Add a slave to the current media player.
+ *
+ * \note If the player is playing, the slave will be added directly. This call
+ * will also update the slave list of the attached libvlc_media_t.
+ *
+ * @deprecated Use @ref libvlc_media_player_add_associated_media instead.
+ * \version LibVLC 3.0.0 and later.
+ *
+ * \see libvlc_media_slaves_add
+ *
+ * \param p_mi the media player
+ * \param i_type subtitle or audio
+ * \param psz_uri Uri of the slave (should contain a valid scheme).
+ * \param b_select True if this slave should be selected when it's loaded
+ *
+ * \return 0 on success, -1 on error.
+ */
+LIBVLC_DEPRECATED LIBVLC_API
+int libvlc_media_player_add_slave( libvlc_media_player_t *p_mi,
+                                   libvlc_media_slave_type_t i_type,
+                                   const char *psz_uri, bool b_select );
+
 /** @}*/
 
 /**
diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index 314d5c20b8..03b11e2a56 100644
--- a/include/vlc/libvlc_media.h
+++ b/include/vlc/libvlc_media.h
@@ -294,24 +294,24 @@ typedef enum libvlc_media_parsed_status_t
 } libvlc_media_parsed_status_t;
 
 /**
- * Type of a media slave: subtitle or audio.
+ * Type of an associated media: subtitle or audio.
  */
-typedef enum libvlc_media_slave_type_t
+typedef enum libvlc_associated_media_type_t
 {
-    libvlc_media_slave_type_subtitle,
-    libvlc_media_slave_type_audio,
-} libvlc_media_slave_type_t;
+    libvlc_associated_media_type_subtitle,
+    libvlc_associated_media_type_audio,
+} libvlc_associated_media_type_t;
 
 /**
- * A slave of a libvlc_media_t
- * \see libvlc_media_slaves_get
+ * A media associated with of a libvlc_media_t
+ * \see libvlc_media_get_associated_medias
  */
-typedef struct libvlc_media_slave_t
+typedef struct libvlc_associated_media_t
 {
     char *                          psz_uri;
-    libvlc_media_slave_type_t       i_type;
+    libvlc_associated_media_type_t  i_type;
     unsigned int                    i_priority;
-} libvlc_media_slave_t;
+} libvlc_associated_media_t;
 
 /**
  * Callback prototype to open a custom bitstream input media.
@@ -789,7 +789,7 @@ void libvlc_media_tracks_release( libvlc_media_track_t **p_tracks,
 /**
  * Get the media type of the media descriptor object
  *
- * \version LibVLC 3.0.0 and later.
+ * \version LibVLC 4.0.0 and later.
  *
  * \see libvlc_media_type_t
  *
@@ -801,73 +801,74 @@ LIBVLC_API
 libvlc_media_type_t libvlc_media_get_type( libvlc_media_t *p_md );
 
 /**
- * Add a slave to the current media.
+ * Add a media associated with the current media.
  *
- * A slave is an external input source that may contains an additional subtitle
- * track (like a .srt) or an additional audio track (like a .ac3).
+ * An associated is an external input source that may contains an additional
+ * subtitle track (like a .srt) or an additional audio track (like a .ac3).
  *
  * \note This function must be called before the media is parsed (via
  * libvlc_media_parse_with_options()) or before the media is played (via
  * libvlc_media_player_play())
  *
- * \version LibVLC 3.0.0 and later.
+ * \version LibVLC 4.0.0 and later.
  *
  * \param p_md media descriptor object
  * \param i_type subtitle or audio
  * \param i_priority from 0 (low priority) to 4 (high priority)
- * \param psz_uri Uri of the slave (should contain a valid scheme).
+ * \param psz_uri Uri of the associated media (should contain a valid scheme).
  *
  * \return 0 on success, -1 on error.
  */
 LIBVLC_API
-int libvlc_media_slaves_add( libvlc_media_t *p_md,
-                             libvlc_media_slave_type_t i_type,
-                             unsigned int i_priority,
-                             const char *psz_uri );
+int libvlc_media_add_associated_media( libvlc_media_t *p_md,
+                                       libvlc_associated_media_type_t i_type,
+                                       unsigned int i_priority,
+                                       const char *psz_uri );
 
 /**
- * Clear all slaves previously added by libvlc_media_slaves_add() or
- * internally.
+ * Clear all associated media previously added by
+ * libvlc_media_add_associated_media() or internally.
  *
- * \version LibVLC 3.0.0 and later.
+ * \version LibVLC 4.0.0 and later.
  *
  * \param p_md media descriptor object
  */
 LIBVLC_API
-void libvlc_media_slaves_clear( libvlc_media_t *p_md );
+void libvlc_media_clear_associated_medias( libvlc_media_t *p_md );
 
 /**
- * Get a media descriptor's slave list
+ * Get the list of associated medias
  *
- * The list will contain slaves parsed by VLC or previously added by
- * libvlc_media_slaves_add(). The typical use case of this function is to save
- * a list of slave in a database for a later use.
+ * The list will contain associated medias parsed by VLC or previously added by
+ * libvlc_media_add_associated_media(). The typical use case of this function
+ * is to save a list of associated medias in a database for a later use.
  *
- * \version LibVLC 3.0.0 and later.
+ * \version LibVLC 4.0.0 and later.
  *
- * \see libvlc_media_slaves_add
+ * \see libvlc_media_add_associated_media
  *
  * \param p_md media descriptor object
- * \param ppp_slaves address to store an allocated array of slaves (must be
- * freed with libvlc_media_slaves_release()) [OUT]
+ * \param ppp_amedias address to store an allocated array of associated medias
+ * (must be freed with libvlc_associated_medias_release()) [OUT]
  *
- * \return the number of slaves (zero on error)
+ * \return the number of associated medias (zero on error)
  */
 LIBVLC_API
-unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
-                                      libvlc_media_slave_t ***ppp_slaves );
+unsigned int libvlc_media_get_associated_medias( libvlc_media_t *p_md,
+                                      libvlc_associated_media_t ***ppp_amedias );
 
 /**
- * Release a media descriptor's slave list
+ * Release a list of associated medias
  *
- * \version LibVLC 3.0.0 and later.
+ * \version LibVLC 4.0.0 and later.
  *
- * \param pp_slaves slave array to release
+ * \param pp_medias associated media array to release (returned by
+ * libvlc_media_get_associated_medias())
  * \param i_count number of elements in the array
  */
 LIBVLC_API
-void libvlc_media_slaves_release( libvlc_media_slave_t **pp_slaves,
-                                  unsigned int i_count );
+void libvlc_associated_medias_release( libvlc_associated_media_t **pp_medias,
+                                       unsigned int i_count );
 
 /** @}*/
 
diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h
index 73dadda3ba..babd1e0f91 100644
--- a/include/vlc/libvlc_media_player.h
+++ b/include/vlc/libvlc_media_player.h
@@ -1087,26 +1087,28 @@ LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi,
 LIBVLC_API void libvlc_media_player_set_video_title_display( libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout );
 
 /**
- * Add a slave to the current media player.
+ * Add an associated media to the current media player.
  *
- * \note If the player is playing, the slave will be added directly. This call
- * will also update the slave list of the attached libvlc_media_t.
+ * \note If the player is playing, the associated media will be added directly.
+ * This call will also update the associated media list of the attached
+ * libvlc_media_t.
  *
- * \version LibVLC 3.0.0 and later.
+ * \version LibVLC 4.0.0 and later.
  *
- * \see libvlc_media_slaves_add
+ * \see libvlc_media_add_associated_media
  *
  * \param p_mi the media player
  * \param i_type subtitle or audio
- * \param psz_uri Uri of the slave (should contain a valid scheme).
- * \param b_select True if this slave should be selected when it's loaded
+ * \param psz_uri Uri of the associated media (should contain a valid scheme).
+ * \param b_select True if this associated media should be selected when it's
+ * loaded
  *
  * \return 0 on success, -1 on error.
  */
 LIBVLC_API
-int libvlc_media_player_add_slave( libvlc_media_player_t *p_mi,
-                                   libvlc_media_slave_type_t i_type,
-                                   const char *psz_uri, bool b_select );
+int libvlc_media_player_add_associated_media( libvlc_media_player_t *p_mi,
+                                              libvlc_associated_media_type_t i_type,
+                                              const char *psz_uri, bool b_select );
 
 /**
  * Release (free) libvlc_track_description_t
diff --git a/lib/libvlc.sym b/lib/libvlc.sym
index 9a896ce7b2..1311e5cfac 100644
--- a/lib/libvlc.sym
+++ b/lib/libvlc.sym
@@ -3,6 +3,7 @@ libvlc_clearerr
 libvlc_printerr
 libvlc_vprinterr
 libvlc_add_intf
+libvlc_associated_medias_release
 libvlc_audio_equalizer_get_amp_at_index
 libvlc_audio_equalizer_get_band_count
 libvlc_audio_equalizer_get_band_frequency
@@ -60,8 +61,10 @@ libvlc_log_get_object
 libvlc_log_set
 libvlc_log_set_file
 libvlc_log_unset
+libvlc_media_add_associated_media
 libvlc_media_add_option
 libvlc_media_add_option_flag
+libvlc_media_clear_associated_medias
 libvlc_media_discoverer_is_running
 libvlc_media_discoverer_media_list
 libvlc_media_discoverer_new
@@ -72,6 +75,7 @@ libvlc_media_discoverer_start
 libvlc_media_discoverer_stop
 libvlc_media_duplicate
 libvlc_media_event_manager
+libvlc_media_get_associated_medias
 libvlc_media_get_codec_description
 libvlc_media_get_duration
 libvlc_media_get_meta
@@ -131,6 +135,7 @@ libvlc_media_parse_async
 libvlc_media_parse_with_options
 libvlc_media_parse_stop
 libvlc_media_player_add_slave
+libvlc_media_player_add_associated_media
 libvlc_media_player_can_pause
 libvlc_media_player_program_scrambled
 libvlc_media_player_next_frame
diff --git a/lib/media.c b/lib/media.c
index 17deae436e..e907af37a5 100644
--- a/lib/media.c
+++ b/lib/media.c
@@ -1092,10 +1092,10 @@ libvlc_media_type_t libvlc_media_get_type( libvlc_media_t *p_md )
     }
 }
 
-int libvlc_media_slaves_add( libvlc_media_t *p_md,
-                             libvlc_media_slave_type_t i_type,
-                             unsigned int i_priority,
-                             const char *psz_uri )
+int libvlc_media_add_associated_media( libvlc_media_t *p_md,
+                                       libvlc_associated_media_type_t i_type,
+                                       unsigned int i_priority,
+                                       const char *psz_uri )
 {
     assert( p_md && psz_uri );
     input_item_t *p_input_item = p_md->p_input_item;
@@ -1143,7 +1143,7 @@ int libvlc_media_slaves_add( libvlc_media_t *p_md,
     return input_item_AddSlave( p_input_item, p_slave ) == VLC_SUCCESS ? 0 : -1;
 }
 
-void libvlc_media_slaves_clear( libvlc_media_t *p_md )
+void libvlc_media_clear_associated_medias( libvlc_media_t *p_md )
 {
     assert( p_md );
     input_item_t *p_input_item = p_md->p_input_item;
@@ -1155,12 +1155,12 @@ void libvlc_media_slaves_clear( libvlc_media_t *p_md )
     vlc_mutex_unlock( &p_input_item->lock );
 }
 
-unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
-                                      libvlc_media_slave_t ***ppp_slaves )
+unsigned int libvlc_media_get_associated_medias( libvlc_media_t *p_md,
+                                    libvlc_associated_media_t ***ppp_amedias )
 {
-    assert( p_md && ppp_slaves );
+    assert( p_md && ppp_amedias );
     input_item_t *p_input_item = p_md->p_input_item;
-    *ppp_slaves = NULL;
+    *ppp_amedias = NULL;
 
     vlc_mutex_lock( &p_input_item->lock );
 
@@ -1168,8 +1168,8 @@ unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
     if( i_count <= 0 )
         return vlc_mutex_unlock( &p_input_item->lock ), 0;
 
-    libvlc_media_slave_t **pp_slaves = calloc( i_count, sizeof(*pp_slaves) );
-    if( pp_slaves == NULL )
+    libvlc_associated_media_t **pp_amedias = calloc( i_count, sizeof(*pp_amedias) );
+    if( pp_amedias == NULL )
         return vlc_mutex_unlock( &p_input_item->lock ), 0;
 
     for( int i = 0; i < i_count; ++i )
@@ -1178,24 +1178,24 @@ unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
         assert( p_item_slave->i_priority >= SLAVE_PRIORITY_MATCH_NONE );
 
         /* also allocate psz_uri buffer at the end of the struct */
-        libvlc_media_slave_t *p_slave = malloc( sizeof(*p_slave) +
+        libvlc_associated_media_t *p_amedia = malloc( sizeof(*p_amedia) +
                                                 strlen( p_item_slave->psz_uri )
                                                 + 1 );
-        if( p_slave == NULL )
+        if( p_amedia == NULL )
         {
-            libvlc_media_slaves_release(pp_slaves, i);
+            libvlc_associated_medias_release(pp_amedias, i);
             return vlc_mutex_unlock( &p_input_item->lock ), 0;
         }
-        p_slave->psz_uri = (char *) ((uint8_t *)p_slave) + sizeof(*p_slave);
-        strcpy( p_slave->psz_uri, p_item_slave->psz_uri );
+        p_amedia->psz_uri = (char *) ((uint8_t *)p_amedia) + sizeof(*p_amedia);
+        strcpy( p_amedia->psz_uri, p_item_slave->psz_uri );
 
         switch( p_item_slave->i_type )
         {
         case SLAVE_TYPE_SPU:
-            p_slave->i_type = libvlc_media_slave_type_subtitle;
+            p_amedia->i_type = libvlc_media_slave_type_subtitle;
             break;
         case SLAVE_TYPE_AUDIO:
-            p_slave->i_type = libvlc_media_slave_type_audio;
+            p_amedia->i_type = libvlc_media_slave_type_audio;
             break;
         default:
             vlc_assert_unreachable();
@@ -1204,39 +1204,66 @@ unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
         switch( p_item_slave->i_priority )
         {
         case SLAVE_PRIORITY_MATCH_NONE:
-            p_slave->i_priority = 0;
+            p_amedia->i_priority = 0;
             break;
         case SLAVE_PRIORITY_MATCH_RIGHT:
-            p_slave->i_priority = 1;
+            p_amedia->i_priority = 1;
             break;
         case SLAVE_PRIORITY_MATCH_LEFT:
-            p_slave->i_priority = 2;
+            p_amedia->i_priority = 2;
             break;
         case SLAVE_PRIORITY_MATCH_ALL:
-            p_slave->i_priority = 3;
+            p_amedia->i_priority = 3;
             break;
         case SLAVE_PRIORITY_USER:
-            p_slave->i_priority = 4;
+            p_amedia->i_priority = 4;
             break;
         default:
             vlc_assert_unreachable();
         }
-        pp_slaves[i] = p_slave;
+        pp_amedias[i] = p_amedia;
     }
     vlc_mutex_unlock( &p_input_item->lock );
 
-    *ppp_slaves = pp_slaves;
+    *ppp_amedias = pp_amedias;
     return i_count;
 }
 
-void libvlc_media_slaves_release( libvlc_media_slave_t **pp_slaves,
-                                  unsigned int i_count )
+void libvlc_associated_medias_release( libvlc_associated_media_t **pp_amedias,
+                                       unsigned int i_count )
 {
     if( i_count > 0 )
     {
-        assert( pp_slaves );
+        assert( pp_amedias );
         for( unsigned int i = 0; i < i_count; ++i )
-            free( pp_slaves[i] );
+            free( pp_amedias[i] );
     }
-    free( pp_slaves );
+    free( pp_amedias );
+}
+
+int libvlc_media_slaves_add( libvlc_media_t *p_md,
+                             libvlc_media_slave_type_t i_type,
+                             unsigned int i_priority,
+                             const char *psz_uri )
+{
+    return libvlc_media_add_associated_media( p_md, i_type, i_priority, psz_uri );
+}
+
+void libvlc_media_slaves_clear( libvlc_media_t *p_md )
+{
+    libvlc_media_clear_associated_medias( p_md );
+}
+
+unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
+                                      libvlc_media_slave_t ***ppp_amedias )
+{
+    return libvlc_media_get_associated_medias( p_md,
+                                              (libvlc_associated_media_t ***)ppp_amedias );
+}
+
+void libvlc_media_slaves_release( libvlc_media_slave_t **pp_amedias,
+                                  unsigned int i_count )
+{
+    libvlc_associated_medias_release( (libvlc_associated_media_t **)pp_amedias,
+                                      i_count );
 }
diff --git a/lib/media_player.c b/lib/media_player.c
index e299f823b3..e7cbe27c35 100644
--- a/lib/media_player.c
+++ b/lib/media_player.c
@@ -1934,9 +1934,9 @@ void libvlc_media_player_set_video_title_display( libvlc_media_player_t *p_mi, l
     }
 }
 
-int libvlc_media_player_add_slave( libvlc_media_player_t *p_mi,
-                                   libvlc_media_slave_type_t i_type,
-                                   const char *psz_uri, bool b_select )
+int libvlc_media_player_add_associated_media( libvlc_media_player_t *p_mi,
+                                              libvlc_associated_media_type_t i_type,
+                                              const char *psz_uri, bool b_select )
 {
     input_thread_t *p_input_thread = libvlc_get_input_thread ( p_mi );
 
@@ -1946,7 +1946,8 @@ int libvlc_media_player_add_slave( libvlc_media_player_t *p_mi,
         if( p_media == NULL )
             return -1;
 
-        int i_ret = libvlc_media_slaves_add( p_media, i_type, 4, psz_uri );
+        int i_ret = libvlc_media_add_associated_media( p_media, i_type, 4,
+                                                       psz_uri );
         libvlc_media_release( p_media );
         return i_ret;
     }
@@ -1959,6 +1960,12 @@ int libvlc_media_player_add_slave( libvlc_media_player_t *p_mi,
         return i_ret == VLC_SUCCESS ? 0 : -1;
     }
 }
+int libvlc_media_player_add_slave( libvlc_media_player_t *p_mi,
+                                   libvlc_media_slave_type_t i_type,
+                                   const char *psz_uri, bool b_select )
+{
+    return libvlc_media_player_add_associated_media( p_mi, i_type, psz_uri, b_select );
+}
 
 /**
  * Maximum size of a formatted equalizer amplification band frequency value.
-- 
2.18.0



More information about the vlc-devel mailing list