Merge pull request #3137 from mark-monteiro/external-id-type

Correctly Support Translating External Ids

MediaBrowser.Controller/Providers/IExternalId.cs

@@ -1,15 +1,45 @@
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 
 namespace MediaBrowser.Controller.Providers
 {
+    /// <summary>
+    /// Represents an identifier for an external provider.
+    /// </summary>
     public interface IExternalId
     {
-        string Name { get; }
+        /// <summary>
+        /// Gets the display name of the provider associated with this ID type.
+        /// </summary>
+        string ProviderName { get; }
 
+        /// <summary>
+        /// Gets the unique key to distinguish this provider/type pair. This should be unique across providers.
+        /// </summary>
+        // TODO: This property is not actually unique across the concrete types at the moment. It should be updated to be unique.
         string Key { get; }
 
+        /// <summary>
+        /// Gets the specific media type for this id. This is used to distinguish between the different
+        /// external id types for providers with multiple ids.
+        /// A null value indicates there is no specific media type associated with the external id, or this is the
+        /// default id for the external provider so there is no need to specify a type.
+        /// </summary>
+        /// <remarks>
+        /// This can be used along with the <see cref="ProviderName"/> to localize the external id on the client.
+        /// </remarks>
+        ExternalIdMediaType? Type { get; }
+
+        /// <summary>
+        /// Gets the URL format string for this id.
+        /// </summary>
         string UrlFormatString { get; }
 
+        /// <summary>
+        /// Determines whether this id supports a given item type.
+        /// </summary>
+        /// <param name="item">The item.</param>
+        /// <returns>True if this item is supported, otherwise false.</returns>
         bool Supports(IHasProviderIds item);
     }
 }

MediaBrowser.LocalMetadata/Parsers/BaseItemXmlParser.cs

@@ -81,7 +81,7 @@ namespace MediaBrowser.LocalMetadata.Parsers
                 var id = info.Key + "Id";
                 if (!_validProviderIds.ContainsKey(id))
                 {
-                    _validProviderIds.Add(id, info.Key);
+                    _validProviderIds.Add(id, info.Key!);
                 }
             }
 

MediaBrowser.Model/Providers/ExternalIdInfo.cs

@@ -1,26 +1,36 @@
-#nullable disable
-#pragma warning disable CS1591
-
 namespace MediaBrowser.Model.Providers
 {
+    /// <summary>
+    /// Represents the external id information for serialization to the client.
+    /// </summary>
     public class ExternalIdInfo
     {
         /// <summary>
-        /// Gets or sets the name.
+        /// Gets or sets the display name of the external id provider (IE: IMDB, MusicBrainz, etc).
         /// </summary>
-        /// <value>The name.</value>
+        // TODO: This should be renamed to ProviderName
-        public string Name { get; set; }
+        public string? Name { get; set; }
 
         /// <summary>
-        /// Gets or sets the key.
+        /// Gets or sets the unique key for this id. This key should be unique across all providers.
         /// </summary>
-        /// <value>The key.</value>
+        // TODO: This property is not actually unique across the concrete types at the moment. It should be updated to be unique.
-        public string Key { get; set; }
+        public string? Key { get; set; }
+
+        /// <summary>
+        /// Gets or sets the specific media type for this id. This is used to distinguish between the different
+        /// external id types for providers with multiple ids.
+        /// A null value indicates there is no specific media type associated with the external id, or this is the
+        /// default id for the external provider so there is no need to specify a type.
+        /// </summary>
+        /// <remarks>
+        /// This can be used along with the <see cref="Name"/> to localize the external id on the client.
+        /// </remarks>
+        public ExternalIdMediaType? Type { get; set; }
 
         /// <summary>
         /// Gets or sets the URL format string.
         /// </summary>
-        /// <value>The URL format string.</value>
+        public string? UrlFormatString { get; set; }
-        public string UrlFormatString { get; set; }
     }
 }

MediaBrowser.Model/Providers/ExternalIdMediaType.cs

@@ -0,0 +1,71 @@
+namespace MediaBrowser.Model.Providers
+{
+    /// <summary>
+    /// The specific media type of an <see cref="ExternalIdInfo"/>.
+    /// </summary>
+    /// <remarks>
+    /// Client applications may use this as a translation key.
+    /// </remarks>
+    public enum ExternalIdMediaType
+    {
+        /// <summary>
+        /// A music album.
+        /// </summary>
+        Album = 1,
+
+        /// <summary>
+        /// The artist of a music album.
+        /// </summary>
+        AlbumArtist = 2,
+
+        /// <summary>
+        /// The artist of a media item.
+        /// </summary>
+        Artist = 3,
+
+        /// <summary>
+        /// A boxed set of media.
+        /// </summary>
+        BoxSet = 4,
+
+        /// <summary>
+        /// A series episode.
+        /// </summary>
+        Episode = 5,
+
+        /// <summary>
+        /// A movie.
+        /// </summary>
+        Movie = 6,
+
+        /// <summary>
+        /// An alternative artist apart from the main artist.
+        /// </summary>
+        OtherArtist = 7,
+
+        /// <summary>
+        /// A person.
+        /// </summary>
+        Person = 8,
+
+        /// <summary>
+        /// A release group.
+        /// </summary>
+        ReleaseGroup = 9,
+
+        /// <summary>
+        /// A single season of a series.
+        /// </summary>
+        Season = 10,
+
+        /// <summary>
+        /// A series.
+        /// </summary>
+        Series = 11,
+
+        /// <summary>
+        /// A music track.
+        /// </summary>
+        Track = 12
+    }
+}

MediaBrowser.Providers/Manager/ProviderManager.cs

@@ -102,7 +102,7 @@ namespace MediaBrowser.Providers.Manager
 
             _metadataServices = metadataServices.OrderBy(i => i.Order).ToArray();
             _metadataProviders = metadataProviders.ToArray();
-            _externalIds = externalIds.OrderBy(i => i.Name).ToArray();
+            _externalIds = externalIds.OrderBy(i => i.ProviderName).ToArray();
 
             _savers = metadataSavers.Where(i =>
             {
@@ -900,7 +900,7 @@ namespace MediaBrowser.Providers.Manager
 
                 return new ExternalUrl
                 {
-                    Name = i.Name,
+                    Name = i.ProviderName,
                     Url = string.Format(
                         CultureInfo.InvariantCulture,
                         i.UrlFormatString,
@@ -914,8 +914,9 @@ namespace MediaBrowser.Providers.Manager
             return GetExternalIds(item)
                 .Select(i => new ExternalIdInfo
                 {
-                    Name = i.Name,
+                    Name = i.ProviderName,
                     Key = i.Key,
+                    Type = i.Type,
                     UrlFormatString = i.UrlFormatString
                 });
         }

MediaBrowser.Providers/Movies/MovieExternalIds.cs

@@ -6,17 +6,21 @@ using MediaBrowser.Controller.Entities.TV;
 using MediaBrowser.Controller.LiveTv;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 
 namespace MediaBrowser.Providers.Movies
 {
     public class ImdbExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "IMDb";
+        public string ProviderName => "IMDb";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Imdb.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => null;
+
         /// <inheritdoc />
         public string UrlFormatString => "https://www.imdb.com/title/{0}";
 
@@ -36,11 +40,14 @@ namespace MediaBrowser.Providers.Movies
     public class ImdbPersonExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "IMDb";
+        public string ProviderName => "IMDb";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Imdb.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Person;
+
         /// <inheritdoc />
         public string UrlFormatString => "https://www.imdb.com/name/{0}";
 

MediaBrowser.Providers/Music/MusicExternalIds.cs

@@ -3,17 +3,21 @@
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 
 namespace MediaBrowser.Providers.Music
 {
     public class ImvdbId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "IMVDb";
+        public string ProviderName => "IMVDb";
 
         /// <inheritdoc />
         public string Key => "IMVDb";
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => null;
+
         /// <inheritdoc />
         public string UrlFormatString => null;
 

MediaBrowser.Providers/Plugins/AudioDb/ExternalIds.cs

@@ -3,17 +3,21 @@
 using MediaBrowser.Controller.Entities.Audio;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 
 namespace MediaBrowser.Providers.Plugins.AudioDb
 {
     public class AudioDbAlbumExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "TheAudioDb";
+        public string ProviderName => "TheAudioDb";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.AudioDbAlbum.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => null;
+
         /// <inheritdoc />
         public string UrlFormatString => "https://www.theaudiodb.com/album/{0}";
 
@@ -24,11 +28,14 @@ namespace MediaBrowser.Providers.Plugins.AudioDb
     public class AudioDbOtherAlbumExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "TheAudioDb Album";
+        public string ProviderName => "TheAudioDb";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.AudioDbAlbum.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Album;
+
         /// <inheritdoc />
         public string UrlFormatString => "https://www.theaudiodb.com/album/{0}";
 
@@ -39,11 +46,14 @@ namespace MediaBrowser.Providers.Plugins.AudioDb
     public class AudioDbArtistExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "TheAudioDb";
+        public string ProviderName => "TheAudioDb";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.AudioDbArtist.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Artist;
+
         /// <inheritdoc />
         public string UrlFormatString => "https://www.theaudiodb.com/artist/{0}";
 
@@ -54,11 +64,14 @@ namespace MediaBrowser.Providers.Plugins.AudioDb
     public class AudioDbOtherArtistExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "TheAudioDb Artist";
+        public string ProviderName => "TheAudioDb";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.AudioDbArtist.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.OtherArtist;
+
         /// <inheritdoc />
         public string UrlFormatString => "https://www.theaudiodb.com/artist/{0}";
 

MediaBrowser.Providers/Plugins/MusicBrainz/ExternalIds.cs

@@ -3,6 +3,7 @@
 using MediaBrowser.Controller.Entities.Audio;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 using MediaBrowser.Providers.Plugins.MusicBrainz;
 
 namespace MediaBrowser.Providers.Music
@@ -10,11 +11,14 @@ namespace MediaBrowser.Providers.Music
     public class MusicBrainzReleaseGroupExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "MusicBrainz Release Group";
+        public string ProviderName => "MusicBrainz";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.MusicBrainzReleaseGroup.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.ReleaseGroup;
+
         /// <inheritdoc />
         public string UrlFormatString => Plugin.Instance.Configuration.Server + "/release-group/{0}";
 
@@ -25,11 +29,14 @@ namespace MediaBrowser.Providers.Music
     public class MusicBrainzAlbumArtistExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "MusicBrainz Album Artist";
+        public string ProviderName => "MusicBrainz";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.MusicBrainzAlbumArtist.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.AlbumArtist;
+
         /// <inheritdoc />
         public string UrlFormatString => Plugin.Instance.Configuration.Server + "/artist/{0}";
 
@@ -40,11 +47,14 @@ namespace MediaBrowser.Providers.Music
     public class MusicBrainzAlbumExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "MusicBrainz Album";
+        public string ProviderName => "MusicBrainz";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.MusicBrainzAlbum.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Album;
+
         /// <inheritdoc />
         public string UrlFormatString => Plugin.Instance.Configuration.Server + "/release/{0}";
 
@@ -55,11 +65,14 @@ namespace MediaBrowser.Providers.Music
     public class MusicBrainzArtistExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "MusicBrainz";
+        public string ProviderName => "MusicBrainz";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.MusicBrainzArtist.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Artist;
+
         /// <inheritdoc />
         public string UrlFormatString => Plugin.Instance.Configuration.Server + "/artist/{0}";
 
@@ -70,12 +83,15 @@ namespace MediaBrowser.Providers.Music
     public class MusicBrainzOtherArtistExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "MusicBrainz Artist";
+        public string ProviderName => "MusicBrainz";
 
         /// <inheritdoc />
 
         public string Key => MetadataProvider.MusicBrainzArtist.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.OtherArtist;
+
         /// <inheritdoc />
         public string UrlFormatString => Plugin.Instance.Configuration.Server + "/artist/{0}";
 
@@ -86,11 +102,14 @@ namespace MediaBrowser.Providers.Music
     public class MusicBrainzTrackId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "MusicBrainz Track";
+        public string ProviderName => "MusicBrainz";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.MusicBrainzTrack.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Track;
+
         /// <inheritdoc />
         public string UrlFormatString => Plugin.Instance.Configuration.Server + "/track/{0}";
 

MediaBrowser.Providers/Plugins/Tmdb/BoxSets/TmdbBoxSetExternalId.cs

@@ -1,20 +1,25 @@
-#pragma warning disable CS1591
-
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Controller.Entities.Movies;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 
 namespace MediaBrowser.Providers.Plugins.Tmdb.BoxSets
 {
+    /// <summary>
+    /// External ID for a TMDB box set.
+    /// </summary>
     public class TmdbBoxSetExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => TmdbUtils.ProviderName;
+        public string ProviderName => TmdbUtils.ProviderName;
 
         /// <inheritdoc />
         public string Key => MetadataProvider.TmdbCollection.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.BoxSet;
+
         /// <inheritdoc />
         public string UrlFormatString => TmdbUtils.BaseTmdbUrl + "collection/{0}";
 

MediaBrowser.Providers/Plugins/Tmdb/Movies/TmdbMovieExternalId.cs

@@ -1,21 +1,26 @@
-#pragma warning disable CS1591
-
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Controller.Entities.Movies;
 using MediaBrowser.Controller.LiveTv;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 
 namespace MediaBrowser.Providers.Plugins.Tmdb.Movies
 {
+    /// <summary>
+    /// External ID for a TMBD movie.
+    /// </summary>
     public class TmdbMovieExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => TmdbUtils.ProviderName;
+        public string ProviderName => TmdbUtils.ProviderName;
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Tmdb.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Movie;
+
         /// <inheritdoc />
         public string UrlFormatString => TmdbUtils.BaseTmdbUrl + "movie/{0}";
 

MediaBrowser.Providers/Plugins/Tmdb/People/TmdbPersonExternalId.cs

@@ -1,19 +1,24 @@
-#pragma warning disable CS1591
-
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 
 namespace MediaBrowser.Providers.Plugins.Tmdb.People
 {
+    /// <summary>
+    /// External ID for a TMDB person.
+    /// </summary>
     public class TmdbPersonExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => TmdbUtils.ProviderName;
+        public string ProviderName => TmdbUtils.ProviderName;
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Tmdb.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Person;
+
         /// <inheritdoc />
         public string UrlFormatString => TmdbUtils.BaseTmdbUrl + "person/{0}";
 

MediaBrowser.Providers/Plugins/Tmdb/TV/TmdbSeriesExternalId.cs

@@ -1,19 +1,24 @@
-#pragma warning disable CS1591
-
 using MediaBrowser.Controller.Entities.TV;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 
 namespace MediaBrowser.Providers.Plugins.Tmdb.TV
 {
+    /// <summary>
+    /// External ID for a TMDB series.
+    /// </summary>
     public class TmdbSeriesExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => TmdbUtils.ProviderName;
+        public string ProviderName => TmdbUtils.ProviderName;
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Tmdb.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Series;
+
         /// <inheritdoc />
         public string UrlFormatString => TmdbUtils.BaseTmdbUrl + "tv/{0}";
 

MediaBrowser.Providers/TV/TvExternalIds.cs

@@ -3,6 +3,7 @@
 using MediaBrowser.Controller.Entities.TV;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Providers;
 using MediaBrowser.Providers.Plugins.TheTvdb;
 
 namespace MediaBrowser.Providers.TV
@@ -10,11 +11,14 @@ namespace MediaBrowser.Providers.TV
     public class Zap2ItExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "Zap2It";
+        public string ProviderName => "Zap2It";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Zap2It.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => null;
+
         /// <inheritdoc />
         public string UrlFormatString => "http://tvlistings.zap2it.com/overview.html?programSeriesId={0}";
 
@@ -25,11 +29,14 @@ namespace MediaBrowser.Providers.TV
     public class TvdbExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "TheTVDB";
+        public string ProviderName => "TheTVDB";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Tvdb.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => null;
+
         /// <inheritdoc />
         public string UrlFormatString => TvdbUtils.TvdbBaseUrl + "?tab=series&id={0}";
 
@@ -40,11 +47,14 @@ namespace MediaBrowser.Providers.TV
     public class TvdbSeasonExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "TheTVDB";
+        public string ProviderName => "TheTVDB";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Tvdb.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Season;
+
         /// <inheritdoc />
         public string UrlFormatString => null;
 
@@ -55,11 +65,14 @@ namespace MediaBrowser.Providers.TV
     public class TvdbEpisodeExternalId : IExternalId
     {
         /// <inheritdoc />
-        public string Name => "TheTVDB";
+        public string ProviderName => "TheTVDB";
 
         /// <inheritdoc />
         public string Key => MetadataProvider.Tvdb.ToString();
 
+        /// <inheritdoc />
+        public ExternalIdMediaType? Type => ExternalIdMediaType.Episode;
+
         /// <inheritdoc />
         public string UrlFormatString => TvdbUtils.TvdbBaseUrl + "?tab=episode&id={0}";