refactor to unify data fetching and define abstract API for re-use

2025-12-06 17:29:05 +01:00 · 2025-12-06 17:29:05 +01:00 · a0e7663323
commit a0e7663323
parent 0fea57a4f9
26 changed files with 595 additions and 254 deletions
--- a/Jellyfin.Plugin.SRFPlay/Api/ISRFApiClientFactory.cs
+++ b/Jellyfin.Plugin.SRFPlay/Api/ISRFApiClientFactory.cs
@ -0,0 +1,13 @@
+namespace Jellyfin.Plugin.SRFPlay.Api;
+
+/// <summary>
+/// Factory interface for creating SRF API clients.
+/// </summary>
+public interface ISRFApiClientFactory
+{
+    /// <summary>
+    /// Creates a new instance of the SRF API client.
+    /// </summary>
+    /// <returns>A new SRFApiClient instance.</returns>
+    SRFApiClient CreateClient();
+}
--- a/Jellyfin.Plugin.SRFPlay/Api/SRFApiClientFactory.cs
+++ b/Jellyfin.Plugin.SRFPlay/Api/SRFApiClientFactory.cs
@ -0,0 +1,26 @@
+using Microsoft.Extensions.Logging;
+
+namespace Jellyfin.Plugin.SRFPlay.Api;
+
+/// <summary>
+/// Factory for creating SRF API clients.
+/// </summary>
+public class SRFApiClientFactory : ISRFApiClientFactory
+{
+    private readonly ILoggerFactory _loggerFactory;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SRFApiClientFactory"/> class.
+    /// </summary>
+    /// <param name="loggerFactory">The logger factory.</param>
+    public SRFApiClientFactory(ILoggerFactory loggerFactory)
+    {
+        _loggerFactory = loggerFactory;
+    }
+
+    /// <inheritdoc />
+    public SRFApiClient CreateClient()
+    {
+        return new SRFApiClient(_loggerFactory);
+    }
+}
--- a/Jellyfin.Plugin.SRFPlay/Channels/SRFPlayChannel.cs
+++ b/Jellyfin.Plugin.SRFPlay/Channels/SRFPlayChannel.cs
@ -6,7 +6,7 @@ using System.Security.Cryptography;
 using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Controller;
 using MediaBrowser.Controller.Channels;
 using MediaBrowser.Controller.Providers;
@ -24,10 +24,10 @@ public class SRFPlayChannel : IChannel, IHasCacheKey
 {
    private readonly ILogger<SRFPlayChannel> _logger;
    private readonly ILoggerFactory _loggerFactory;
-    private readonly ContentRefreshService _contentRefreshService;
-    private readonly StreamUrlResolver _streamResolver;
-    private readonly StreamProxyService _proxyService;
-    private readonly CategoryService? _categoryService;
+    private readonly IContentRefreshService _contentRefreshService;
+    private readonly IStreamUrlResolver _streamResolver;
+    private readonly IStreamProxyService _proxyService;
+    private readonly ICategoryService? _categoryService;
    private readonly IServerApplicationHost _appHost;

    /// <summary>
@ -41,11 +41,11 @@ public class SRFPlayChannel : IChannel, IHasCacheKey
    /// <param name="categoryService">The category service (optional).</param>
    public SRFPlayChannel(
        ILoggerFactory loggerFactory,
-        ContentRefreshService contentRefreshService,
-        StreamUrlResolver streamResolver,
-        StreamProxyService proxyService,
+        IContentRefreshService contentRefreshService,
+        IStreamUrlResolver streamResolver,
+        IStreamProxyService proxyService,
        IServerApplicationHost appHost,
-        CategoryService? categoryService = null)
+        ICategoryService? categoryService = null)
    {
        _loggerFactory = loggerFactory;
        _logger = loggerFactory.CreateLogger<SRFPlayChannel>();
--- a/Jellyfin.Plugin.SRFPlay/Controllers/StreamProxyController.cs
+++ b/Jellyfin.Plugin.SRFPlay/Controllers/StreamProxyController.cs
@ -2,7 +2,7 @@ using System;
 using System.Globalization;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
@ -18,14 +18,14 @@ namespace Jellyfin.Plugin.SRFPlay.Controllers;
 public class StreamProxyController : ControllerBase
 {
    private readonly ILogger<StreamProxyController> _logger;
-    private readonly StreamProxyService _proxyService;
+    private readonly IStreamProxyService _proxyService;

    /// <summary>
    /// Initializes a new instance of the <see cref="StreamProxyController"/> class.
    /// </summary>
    /// <param name="logger">The logger.</param>
    /// <param name="proxyService">The proxy service.</param>
-    public StreamProxyController(ILogger<StreamProxyController> logger, StreamProxyService proxyService)
+    public StreamProxyController(ILogger<StreamProxyController> logger, IStreamProxyService proxyService)
    {
        _logger = logger;
        _proxyService = proxyService;
--- a/Jellyfin.Plugin.SRFPlay/Providers/SRFEpisodeProvider.cs
+++ b/Jellyfin.Plugin.SRFPlay/Providers/SRFEpisodeProvider.cs
@ -4,8 +4,7 @@ using System.Linq;
 using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Api;
-using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Controller.Entities.TV;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
@ -20,25 +19,23 @@ namespace Jellyfin.Plugin.SRFPlay.Providers;
 public class SRFEpisodeProvider : IRemoteMetadataProvider<Episode, EpisodeInfo>
 {
    private readonly ILogger<SRFEpisodeProvider> _logger;
-    private readonly ILoggerFactory _loggerFactory;
    private readonly IHttpClientFactory _httpClientFactory;
-    private readonly MetadataCache _metadataCache;
+    private readonly IMediaCompositionFetcher _compositionFetcher;

    /// <summary>
    /// Initializes a new instance of the <see cref="SRFEpisodeProvider"/> class.
    /// </summary>
    /// <param name="loggerFactory">The logger factory.</param>
    /// <param name="httpClientFactory">The HTTP client factory.</param>
-    /// <param name="metadataCache">The metadata cache.</param>
+    /// <param name="compositionFetcher">The media composition fetcher.</param>
    public SRFEpisodeProvider(
        ILoggerFactory loggerFactory,
        IHttpClientFactory httpClientFactory,
-        MetadataCache metadataCache)
+        IMediaCompositionFetcher compositionFetcher)
    {
-        _loggerFactory = loggerFactory;
        _logger = loggerFactory.CreateLogger<SRFEpisodeProvider>();
        _httpClientFactory = httpClientFactory;
-        _metadataCache = metadataCache;
+        _compositionFetcher = compositionFetcher;
    }

    /// <inheritdoc />
@ -56,26 +53,7 @@ public class SRFEpisodeProvider : IRemoteMetadataProvider<Episode, EpisodeInfo>
            {
                _logger.LogDebug("Searching for episode with URN: {Urn}", urn);

-                var config = Plugin.Instance?.Configuration;
-                if (config == null)
-                {
-                    return results;
-                }
-
-                // Try cache first
-                var mediaComposition = _metadataCache.GetMediaComposition(urn, config.CacheDurationMinutes);
-
-                // If not in cache, fetch from API
-                if (mediaComposition == null)
-                {
-                    using var apiClient = new SRFApiClient(_loggerFactory);
-                    mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
-
-                    if (mediaComposition != null)
-                    {
-                        _metadataCache.SetMediaComposition(urn, mediaComposition);
-                    }
-                }
+                var mediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken).ConfigureAwait(false);

                if (mediaComposition?.ChapterList != null && mediaComposition.ChapterList.Count > 0)
                {
@ -118,26 +96,7 @@ public class SRFEpisodeProvider : IRemoteMetadataProvider<Episode, EpisodeInfo>

            _logger.LogDebug("Fetching metadata for episode URN: {Urn}", urn);

-            var config = Plugin.Instance?.Configuration;
-            if (config == null)
-            {
-                return result;
-            }
-
-            // Try cache first
-            var mediaComposition = _metadataCache.GetMediaComposition(urn, config.CacheDurationMinutes);
-
-            // If not in cache, fetch from API
-            if (mediaComposition == null)
-            {
-                using var apiClient = new SRFApiClient(_loggerFactory);
-                mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
-
-                if (mediaComposition != null)
-                {
-                    _metadataCache.SetMediaComposition(urn, mediaComposition);
-                }
-            }
+            var mediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken).ConfigureAwait(false);

            if (mediaComposition?.ChapterList == null || mediaComposition.ChapterList.Count == 0)
            {
--- a/Jellyfin.Plugin.SRFPlay/Providers/SRFImageProvider.cs
+++ b/Jellyfin.Plugin.SRFPlay/Providers/SRFImageProvider.cs
@ -1,10 +1,10 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
 using System.Net.Http;
+using System.Net.Http.Headers;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Api;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Common.Net;
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Controller.Providers;
@ -21,18 +21,22 @@ public class SRFImageProvider : IRemoteImageProvider, IHasOrder
 {
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<SRFImageProvider> _logger;
-    private readonly ILoggerFactory _loggerFactory;
+    private readonly IMediaCompositionFetcher _compositionFetcher;

    /// <summary>
    /// Initializes a new instance of the <see cref="SRFImageProvider"/> class.
    /// </summary>
    /// <param name="httpClientFactory">The HTTP client factory.</param>
    /// <param name="loggerFactory">The logger factory.</param>
-    public SRFImageProvider(IHttpClientFactory httpClientFactory, ILoggerFactory loggerFactory)
+    /// <param name="compositionFetcher">The media composition fetcher.</param>
+    public SRFImageProvider(
+        IHttpClientFactory httpClientFactory,
+        ILoggerFactory loggerFactory,
+        IMediaCompositionFetcher compositionFetcher)
    {
        _httpClientFactory = httpClientFactory;
-        _loggerFactory = loggerFactory;
        _logger = loggerFactory.CreateLogger<SRFImageProvider>();
+        _compositionFetcher = compositionFetcher;
    }

    /// <inheritdoc />
@ -78,8 +82,7 @@ public class SRFImageProvider : IRemoteImageProvider, IHasOrder
            _logger.LogDebug("Fetching images for SRF URN: {Urn}", urn);

            // Fetch media composition to get image URLs
-            using var apiClient = new SRFApiClient(_loggerFactory);
-            var mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
+            var mediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken).ConfigureAwait(false);

            if (mediaComposition == null)
            {
@ -151,9 +154,69 @@ public class SRFImageProvider : IRemoteImageProvider, IHasOrder
    }

    /// <inheritdoc />
-    public Task<HttpResponseMessage> GetImageResponse(string url, CancellationToken cancellationToken)
+    public async Task<HttpResponseMessage> GetImageResponse(string url, CancellationToken cancellationToken)
    {
        var httpClient = _httpClientFactory.CreateClient(NamedClient.Default);
-        return httpClient.GetAsync(new Uri(url), cancellationToken);
+
+        // Create request with proper headers - SRF CDN requires User-Agent
+        var request = new HttpRequestMessage(HttpMethod.Get, new Uri(url));
+        request.Headers.UserAgent.ParseAdd("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36");
+        request.Headers.Accept.ParseAdd("image/*");
+
+        var response = await httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
+
+        // Fix Content-Type if it's binary/octet-stream - SRF CDN returns wrong content type
+        // Jellyfin needs correct Content-Type to process images
+        if (response.IsSuccessStatusCode &&
+            response.Content.Headers.ContentType?.MediaType == "binary/octet-stream")
+        {
+            // Determine correct content type from URL extension
+            var contentType = GetContentTypeFromUrl(url);
+            if (!string.IsNullOrEmpty(contentType))
+            {
+                _logger.LogDebug("Fixing Content-Type from binary/octet-stream to {ContentType} for {Url}", contentType, url);
+                response.Content.Headers.ContentType = new MediaTypeHeaderValue(contentType);
+            }
+        }
+
+        return response;
+    }
+
+    /// <summary>
+    /// Determines the correct content type based on URL file extension.
+    /// </summary>
+    private static string? GetContentTypeFromUrl(string url)
+    {
+        if (string.IsNullOrEmpty(url))
+        {
+            return null;
+        }
+
+        // Get the file extension from the URL (ignore query string)
+        var uri = new Uri(url);
+        var path = uri.AbsolutePath.ToLowerInvariant();
+
+        if (path.EndsWith(".jpg", StringComparison.Ordinal) || path.EndsWith(".jpeg", StringComparison.Ordinal))
+        {
+            return "image/jpeg";
+        }
+
+        if (path.EndsWith(".png", StringComparison.Ordinal))
+        {
+            return "image/png";
+        }
+
+        if (path.EndsWith(".gif", StringComparison.Ordinal))
+        {
+            return "image/gif";
+        }
+
+        if (path.EndsWith(".webp", StringComparison.Ordinal))
+        {
+            return "image/webp";
+        }
+
+        // Default to JPEG for SRF images (most common)
+        return "image/jpeg";
    }
 }
--- a/Jellyfin.Plugin.SRFPlay/Providers/SRFLiveStream.cs
+++ b/Jellyfin.Plugin.SRFPlay/Providers/SRFLiveStream.cs
@ -2,7 +2,7 @@ using System;
 using System.IO;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Controller.Library;
 using MediaBrowser.Model.Dto;
 using Microsoft.Extensions.Logging;
@ -15,7 +15,7 @@ namespace Jellyfin.Plugin.SRFPlay.Providers;
 internal sealed class SRFLiveStream : ILiveStream
 {
    private readonly ILogger _logger;
-    private readonly StreamProxyService _proxyService;
+    private readonly IStreamProxyService _proxyService;
    private readonly string _originalItemId;
    private MediaSourceInfo? _mediaSource;

@ -26,13 +26,11 @@ internal sealed class SRFLiveStream : ILiveStream
    /// <param name="proxyService">The stream proxy service.</param>
    /// <param name="originalItemId">The original item ID.</param>
    /// <param name="openToken">The open token.</param>
-    /// <param name="loggerFactory">The logger factory.</param>
    public SRFLiveStream(
        ILogger logger,
-        StreamProxyService proxyService,
+        IStreamProxyService proxyService,
        string originalItemId,
-        string openToken,
-        ILoggerFactory loggerFactory)
+        string openToken)
    {
        _logger = logger;
        _proxyService = proxyService;
--- a/Jellyfin.Plugin.SRFPlay/Providers/SRFMediaProvider.cs
+++ b/Jellyfin.Plugin.SRFPlay/Providers/SRFMediaProvider.cs
@ -4,8 +4,8 @@ using System.IO;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Api;
-using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Configuration;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Controller;
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Controller.Library;
@ -23,9 +23,9 @@ public class SRFMediaProvider : IMediaSourceProvider
 {
    private readonly ILogger<SRFMediaProvider> _logger;
    private readonly ILoggerFactory _loggerFactory;
-    private readonly MetadataCache _metadataCache;
-    private readonly StreamUrlResolver _streamResolver;
-    private readonly StreamProxyService _proxyService;
+    private readonly IMediaCompositionFetcher _compositionFetcher;
+    private readonly IStreamUrlResolver _streamResolver;
+    private readonly IStreamProxyService _proxyService;
    private readonly IServerApplicationHost _appHost;
    private readonly Dictionary<string, string> _openTokenToItemId = new();

@ -33,20 +33,20 @@ public class SRFMediaProvider : IMediaSourceProvider
    /// Initializes a new instance of the <see cref="SRFMediaProvider"/> class.
    /// </summary>
    /// <param name="loggerFactory">The logger factory.</param>
-    /// <param name="metadataCache">The metadata cache.</param>
+    /// <param name="compositionFetcher">The media composition fetcher.</param>
    /// <param name="streamResolver">The stream URL resolver.</param>
    /// <param name="proxyService">The stream proxy service.</param>
    /// <param name="appHost">The server application host.</param>
    public SRFMediaProvider(
        ILoggerFactory loggerFactory,
-        MetadataCache metadataCache,
-        StreamUrlResolver streamResolver,
-        StreamProxyService proxyService,
+        IMediaCompositionFetcher compositionFetcher,
+        IStreamUrlResolver streamResolver,
+        IStreamProxyService proxyService,
        IServerApplicationHost appHost)
    {
        _loggerFactory = loggerFactory;
        _logger = loggerFactory.CreateLogger<SRFMediaProvider>();
-        _metadataCache = metadataCache;
+        _compositionFetcher = compositionFetcher;
        _streamResolver = streamResolver;
        _proxyService = proxyService;
        _appHost = appHost;
@ -88,32 +88,10 @@ public class SRFMediaProvider : IMediaSourceProvider

            _logger.LogInformation("Getting media sources for URN: {Urn}, Item: {ItemName}", urn, item.Name);

-            var config = Plugin.Instance?.Configuration;
-            if (config == null)
-            {
-                return sources;
-            }
-
            // For scheduled livestreams, use shorter cache TTL (5 minutes) so they refresh when they go live
-            // For regular content, use configured cache duration
-            var cacheDuration = urn.Contains("scheduled_livestream", StringComparison.OrdinalIgnoreCase)
-                ? 5
-                : config.CacheDurationMinutes;
+            var cacheDuration = urn.Contains("scheduled_livestream", StringComparison.OrdinalIgnoreCase) ? 5 : (int?)null;

-            // Try cache first
-            var mediaComposition = _metadataCache.GetMediaComposition(urn, cacheDuration);
-
-            // If not in cache, fetch from API
-            if (mediaComposition == null)
-            {
-                using var apiClient = new SRFApiClient(_loggerFactory);
-                mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
-
-                if (mediaComposition != null)
-                {
-                    _metadataCache.SetMediaComposition(urn, mediaComposition);
-                }
-            }
+            var mediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken, cacheDuration).ConfigureAwait(false);

            if (mediaComposition?.ChapterList == null || mediaComposition.ChapterList.Count == 0)
            {
@ -139,25 +117,25 @@ public class SRFMediaProvider : IMediaSourceProvider
            }

            // Get stream URL based on quality preference
-            var streamUrl = _streamResolver.GetStreamUrl(chapter, config.QualityPreference);
+            var config = Plugin.Instance?.Configuration;
+            var qualityPref = config?.QualityPreference ?? QualityPreference.HD;
+            var streamUrl = _streamResolver.GetStreamUrl(chapter, qualityPref);

            // For scheduled livestreams, always fetch fresh data to ensure stream URL is current
            if (chapter.Type == "SCHEDULED_LIVESTREAM" && string.IsNullOrEmpty(streamUrl))
            {
                _logger.LogDebug("URN {Urn}: Scheduled livestream has no stream URL, fetching fresh data", urn);

-                using var freshApiClient = new SRFApiClient(_loggerFactory);
-                var freshMediaComposition = await freshApiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
+                // Force fresh fetch with short cache duration
+                var freshMediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken, 1).ConfigureAwait(false);

                if (freshMediaComposition?.ChapterList != null && freshMediaComposition.ChapterList.Count > 0)
                {
                    var freshChapter = freshMediaComposition.ChapterList[0];
-                    streamUrl = _streamResolver.GetStreamUrl(freshChapter, config.QualityPreference);
+                    streamUrl = _streamResolver.GetStreamUrl(freshChapter, qualityPref);

                    if (!string.IsNullOrEmpty(streamUrl))
                    {
-                        // Update cache with fresh data
-                        _metadataCache.SetMediaComposition(urn, freshMediaComposition);
                        chapter = freshChapter;
                        _logger.LogInformation("URN {Urn}: Got fresh stream URL for scheduled livestream", urn);
                    }
@ -190,7 +168,7 @@ public class SRFMediaProvider : IMediaSourceProvider
            _proxyService.RegisterStream(itemIdStr, streamUrl, urn, isLiveStream);

            // Get the server URL for proxy - prefer configured public URL for remote clients
-            var serverUrl = !string.IsNullOrWhiteSpace(config.PublicServerUrl)
+            var serverUrl = config != null && !string.IsNullOrWhiteSpace(config.PublicServerUrl)
                ? config.PublicServerUrl.TrimEnd('/') // Use configured public URL (important for Android/remote clients)
                : _appHost.GetSmartApiUrl(string.Empty); // Fall back to Jellyfin's smart URL resolution

@ -207,7 +185,7 @@ public class SRFMediaProvider : IMediaSourceProvider
                "Using proxy URL for item {ItemId}: {ProxyUrl} (PublicServerUrl configured: {IsPublicConfigured})",
                itemIdStr,
                proxyUrl,
-                !string.IsNullOrWhiteSpace(config.PublicServerUrl));
+                config != null && !string.IsNullOrWhiteSpace(config.PublicServerUrl));

            // Create media source using proxy URL - enables DirectPlay!
            var mediaSource = new MediaSourceInfo
@ -311,8 +289,7 @@ public class SRFMediaProvider : IMediaSourceProvider
            _logger,
            _proxyService,
            originalItemId,
-            openToken,
-            _loggerFactory);
+            openToken);

        return await Task.FromResult<ILiveStream>(liveStream).ConfigureAwait(false);
    }
--- a/Jellyfin.Plugin.SRFPlay/Providers/SRFSeriesProvider.cs
+++ b/Jellyfin.Plugin.SRFPlay/Providers/SRFSeriesProvider.cs
@ -4,8 +4,7 @@ using System.Linq;
 using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Api;
-using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Controller.Entities.TV;
 using MediaBrowser.Controller.Providers;
 using MediaBrowser.Model.Entities;
@ -20,27 +19,23 @@ namespace Jellyfin.Plugin.SRFPlay.Providers;
 public class SRFSeriesProvider : IRemoteMetadataProvider<Series, SeriesInfo>
 {
    private readonly ILogger<SRFSeriesProvider> _logger;
-    private readonly ILoggerFactory _loggerFactory;
    private readonly IHttpClientFactory _httpClientFactory;
-    private readonly MetadataCache _metadataCache;
+    private readonly IMediaCompositionFetcher _compositionFetcher;

    /// <summary>
    /// Initializes a new instance of the <see cref="SRFSeriesProvider"/> class.
    /// </summary>
-    /// <param name="logger">The logger instance.</param>
    /// <param name="loggerFactory">The logger factory.</param>
    /// <param name="httpClientFactory">The HTTP client factory.</param>
-    /// <param name="metadataCache">The metadata cache.</param>
+    /// <param name="compositionFetcher">The media composition fetcher.</param>
    public SRFSeriesProvider(
-        ILogger<SRFSeriesProvider> logger,
        ILoggerFactory loggerFactory,
        IHttpClientFactory httpClientFactory,
-        MetadataCache metadataCache)
+        IMediaCompositionFetcher compositionFetcher)
    {
-        _logger = logger;
-        _loggerFactory = loggerFactory;
+        _logger = loggerFactory.CreateLogger<SRFSeriesProvider>();
        _httpClientFactory = httpClientFactory;
-        _metadataCache = metadataCache;
+        _compositionFetcher = compositionFetcher;
    }

    /// <inheritdoc />
@ -58,26 +53,7 @@ public class SRFSeriesProvider : IRemoteMetadataProvider<Series, SeriesInfo>
            {
                _logger.LogDebug("Searching for series with URN: {Urn}", urn);

-                var config = Plugin.Instance?.Configuration;
-                if (config == null)
-                {
-                    return results;
-                }
-
-                // Try cache first
-                var mediaComposition = _metadataCache.GetMediaComposition(urn, config.CacheDurationMinutes);
-
-                // If not in cache, fetch from API
-                if (mediaComposition == null)
-                {
-                    using var apiClient = new SRFApiClient(_loggerFactory);
-                    mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
-
-                    if (mediaComposition != null)
-                    {
-                        _metadataCache.SetMediaComposition(urn, mediaComposition);
-                    }
-                }
+                var mediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken).ConfigureAwait(false);

                if (mediaComposition?.Show != null)
                {
@ -125,26 +101,7 @@ public class SRFSeriesProvider : IRemoteMetadataProvider<Series, SeriesInfo>

            _logger.LogDebug("Fetching metadata for series URN: {Urn}", urn);

-            var config = Plugin.Instance?.Configuration;
-            if (config == null)
-            {
-                return result;
-            }
-
-            // Try cache first
-            var mediaComposition = _metadataCache.GetMediaComposition(urn, config.CacheDurationMinutes);
-
-            // If not in cache, fetch from API
-            if (mediaComposition == null)
-            {
-                using var apiClient = new SRFApiClient(_loggerFactory);
-                mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
-
-                if (mediaComposition != null)
-                {
-                    _metadataCache.SetMediaComposition(urn, mediaComposition);
-                }
-            }
+            var mediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken).ConfigureAwait(false);

            if (mediaComposition?.Show == null)
            {
--- a/Jellyfin.Plugin.SRFPlay/ScheduledTasks/ContentRefreshTask.cs
+++ b/Jellyfin.Plugin.SRFPlay/ScheduledTasks/ContentRefreshTask.cs
@ -2,7 +2,7 @@ using System;
 using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Model.Tasks;
 using Microsoft.Extensions.Logging;

@ -14,7 +14,7 @@ namespace Jellyfin.Plugin.SRFPlay.ScheduledTasks;
 public class ContentRefreshTask : IScheduledTask
 {
    private readonly ILogger<ContentRefreshTask> _logger;
-    private readonly ContentRefreshService _contentRefreshService;
+    private readonly IContentRefreshService _contentRefreshService;

    /// <summary>
    /// Initializes a new instance of the <see cref="ContentRefreshTask"/> class.
@ -23,7 +23,7 @@ public class ContentRefreshTask : IScheduledTask
    /// <param name="contentRefreshService">The content refresh service.</param>
    public ContentRefreshTask(
        ILogger<ContentRefreshTask> logger,
-        ContentRefreshService contentRefreshService)
+        IContentRefreshService contentRefreshService)
    {
        _logger = logger;
        _contentRefreshService = contentRefreshService;
--- a/Jellyfin.Plugin.SRFPlay/ScheduledTasks/ExpirationCheckTask.cs
+++ b/Jellyfin.Plugin.SRFPlay/ScheduledTasks/ExpirationCheckTask.cs
@ -2,7 +2,7 @@ using System;
 using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Model.Tasks;
 using Microsoft.Extensions.Logging;

@ -14,7 +14,7 @@ namespace Jellyfin.Plugin.SRFPlay.ScheduledTasks;
 public class ExpirationCheckTask : IScheduledTask
 {
    private readonly ILogger<ExpirationCheckTask> _logger;
-    private readonly ContentExpirationService _expirationService;
+    private readonly IContentExpirationService _expirationService;

    /// <summary>
    /// Initializes a new instance of the <see cref="ExpirationCheckTask"/> class.
@ -23,7 +23,7 @@ public class ExpirationCheckTask : IScheduledTask
    /// <param name="expirationService">The content expiration service.</param>
    public ExpirationCheckTask(
        ILogger<ExpirationCheckTask> logger,
-        ContentExpirationService expirationService)
+        IContentExpirationService expirationService)
    {
        _logger = logger;
        _expirationService = expirationService;
--- a/Jellyfin.Plugin.SRFPlay/ServiceRegistrator.cs
+++ b/Jellyfin.Plugin.SRFPlay/ServiceRegistrator.cs
@ -1,13 +1,14 @@
+using Jellyfin.Plugin.SRFPlay.Api;
 using Jellyfin.Plugin.SRFPlay.Channels;
 using Jellyfin.Plugin.SRFPlay.Providers;
 using Jellyfin.Plugin.SRFPlay.ScheduledTasks;
 using Jellyfin.Plugin.SRFPlay.Services;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Controller;
 using MediaBrowser.Controller.Channels;
 using MediaBrowser.Controller.Plugins;
 using MediaBrowser.Model.Tasks;
 using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Logging;

 namespace Jellyfin.Plugin.SRFPlay;

@ -19,13 +20,17 @@ public class ServiceRegistrator : IPluginServiceRegistrator
    /// <inheritdoc />
    public void RegisterServices(IServiceCollection serviceCollection, IServerApplicationHost applicationHost)
    {
-        // Register services as singletons
-        serviceCollection.AddSingleton<MetadataCache>();
-        serviceCollection.AddSingleton<StreamUrlResolver>();
-        serviceCollection.AddSingleton<ContentExpirationService>();
-        serviceCollection.AddSingleton<ContentRefreshService>();
-        serviceCollection.AddSingleton<CategoryService>();
-        serviceCollection.AddSingleton<StreamProxyService>(); // Stream proxy service
+        // Register API client factory
+        serviceCollection.AddSingleton<ISRFApiClientFactory, SRFApiClientFactory>();
+
+        // Register core services with interfaces
+        serviceCollection.AddSingleton<IMetadataCache, MetadataCache>();
+        serviceCollection.AddSingleton<IStreamUrlResolver, StreamUrlResolver>();
+        serviceCollection.AddSingleton<IMediaCompositionFetcher, MediaCompositionFetcher>();
+        serviceCollection.AddSingleton<IStreamProxyService, StreamProxyService>();
+        serviceCollection.AddSingleton<IContentExpirationService, ContentExpirationService>();
+        serviceCollection.AddSingleton<IContentRefreshService, ContentRefreshService>();
+        serviceCollection.AddSingleton<ICategoryService, CategoryService>();

        // Register metadata providers
        serviceCollection.AddSingleton<SRFSeriesProvider>();
--- a/Jellyfin.Plugin.SRFPlay/Services/CategoryService.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/CategoryService.cs
@ -6,6 +6,7 @@ using System.Threading;
 using System.Threading.Tasks;
 using Jellyfin.Plugin.SRFPlay.Api;
 using Jellyfin.Plugin.SRFPlay.Api.Models;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using Microsoft.Extensions.Logging;

 namespace Jellyfin.Plugin.SRFPlay.Services;
@ -13,7 +14,7 @@ namespace Jellyfin.Plugin.SRFPlay.Services;
 /// <summary>
 /// Service for managing topic/category data and filtering.
 /// </summary>
-public class CategoryService
+public class CategoryService : ICategoryService
 {
    private readonly ILogger _logger;
    private readonly ILoggerFactory _loggerFactory;
--- a/Jellyfin.Plugin.SRFPlay/Services/ContentExpirationService.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/ContentExpirationService.cs
@ -3,10 +3,9 @@ using System.Collections.Generic;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
-using Jellyfin.Plugin.SRFPlay.Api;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Controller.Library;
-using MediaBrowser.Model.IO;
 using Microsoft.Extensions.Logging;

 namespace Jellyfin.Plugin.SRFPlay.Services;
@ -14,13 +13,12 @@ namespace Jellyfin.Plugin.SRFPlay.Services;
 /// <summary>
 /// Service for managing content expiration.
 /// </summary>
-public class ContentExpirationService
+public class ContentExpirationService : IContentExpirationService
 {
    private readonly ILogger<ContentExpirationService> _logger;
-    private readonly ILoggerFactory _loggerFactory;
    private readonly ILibraryManager _libraryManager;
-    private readonly StreamUrlResolver _streamResolver;
-    private readonly MetadataCache _metadataCache;
+    private readonly IStreamUrlResolver _streamResolver;
+    private readonly IMediaCompositionFetcher _compositionFetcher;

    /// <summary>
    /// Initializes a new instance of the <see cref="ContentExpirationService"/> class.
@ -28,18 +26,17 @@ public class ContentExpirationService
    /// <param name="loggerFactory">The logger factory.</param>
    /// <param name="libraryManager">The library manager.</param>
    /// <param name="streamResolver">The stream URL resolver.</param>
-    /// <param name="metadataCache">The metadata cache.</param>
+    /// <param name="compositionFetcher">The media composition fetcher.</param>
    public ContentExpirationService(
        ILoggerFactory loggerFactory,
        ILibraryManager libraryManager,
-        StreamUrlResolver streamResolver,
-        MetadataCache metadataCache)
+        IStreamUrlResolver streamResolver,
+        IMediaCompositionFetcher compositionFetcher)
    {
-        _loggerFactory = loggerFactory;
        _logger = loggerFactory.CreateLogger<ContentExpirationService>();
        _libraryManager = libraryManager;
        _streamResolver = streamResolver;
-        _metadataCache = metadataCache;
+        _compositionFetcher = compositionFetcher;
    }

    /// <summary>
@ -119,26 +116,7 @@ public class ContentExpirationService
            return false;
        }

-        var config = Plugin.Instance?.Configuration;
-        if (config == null)
-        {
-            return false;
-        }
-
-        // Try cache first
-        var mediaComposition = _metadataCache.GetMediaComposition(urn, config.CacheDurationMinutes);
-
-        // If not in cache, fetch from API
-        if (mediaComposition == null)
-        {
-            using var apiClient = new SRFApiClient(_loggerFactory);
-            mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
-
-            if (mediaComposition != null)
-            {
-                _metadataCache.SetMediaComposition(urn, mediaComposition);
-            }
-        }
+        var mediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken).ConfigureAwait(false);

        if (mediaComposition?.ChapterList == null || mediaComposition.ChapterList.Count == 0)
        {
@ -196,24 +174,7 @@ public class ContentExpirationService
                        continue;
                    }

-                    var config = Plugin.Instance?.Configuration;
-                    if (config == null)
-                    {
-                        continue;
-                    }
-
-                    var mediaComposition = _metadataCache.GetMediaComposition(urn, config.CacheDurationMinutes);
-
-                    if (mediaComposition == null)
-                    {
-                        using var apiClient = new SRFApiClient(_loggerFactory);
-                        mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
-
-                        if (mediaComposition != null)
-                        {
-                            _metadataCache.SetMediaComposition(urn, mediaComposition);
-                        }
-                    }
+                    var mediaComposition = await _compositionFetcher.GetMediaCompositionAsync(urn, cancellationToken).ConfigureAwait(false);

                    if (mediaComposition?.ChapterList != null && mediaComposition.ChapterList.Count > 0)
                    {
--- a/Jellyfin.Plugin.SRFPlay/Services/ContentRefreshService.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/ContentRefreshService.cs
@ -4,7 +4,7 @@ using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using Jellyfin.Plugin.SRFPlay.Api;
-using Jellyfin.Plugin.SRFPlay.Api.Models;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using Microsoft.Extensions.Logging;

 namespace Jellyfin.Plugin.SRFPlay.Services;
@ -12,24 +12,22 @@ namespace Jellyfin.Plugin.SRFPlay.Services;
 /// <summary>
 /// Service for refreshing content from SRF API.
 /// </summary>
-public class ContentRefreshService
+public class ContentRefreshService : IContentRefreshService
 {
    private readonly ILogger<ContentRefreshService> _logger;
-    private readonly ILoggerFactory _loggerFactory;
-    private readonly MetadataCache _metadataCache;
+    private readonly ISRFApiClientFactory _apiClientFactory;

    /// <summary>
    /// Initializes a new instance of the <see cref="ContentRefreshService"/> class.
    /// </summary>
    /// <param name="loggerFactory">The logger factory.</param>
-    /// <param name="metadataCache">The metadata cache.</param>
+    /// <param name="apiClientFactory">The API client factory.</param>
    public ContentRefreshService(
        ILoggerFactory loggerFactory,
-        MetadataCache metadataCache)
+        ISRFApiClientFactory apiClientFactory)
    {
-        _loggerFactory = loggerFactory;
        _logger = loggerFactory.CreateLogger<ContentRefreshService>();
-        _metadataCache = metadataCache;
+        _apiClientFactory = apiClientFactory;
    }

    /// <summary>
@ -52,7 +50,7 @@ public class ContentRefreshService

            _logger.LogInformation("Refreshing latest content for business unit: {BusinessUnit}", config.BusinessUnit);

-            using var apiClient = new SRFApiClient(_loggerFactory);
+            using var apiClient = _apiClientFactory.CreateClient();
            var businessUnit = config.BusinessUnit.ToString().ToLowerInvariant();

            // Get all shows from Play v3 API
@ -167,7 +165,7 @@ public class ContentRefreshService

            _logger.LogInformation("Refreshing trending content for business unit: {BusinessUnit}", config.BusinessUnit);

-            using var apiClient = new SRFApiClient(_loggerFactory);
+            using var apiClient = _apiClientFactory.CreateClient();
            var businessUnit = config.BusinessUnit.ToString().ToLowerInvariant();

            // Get all shows from Play v3 API
--- a/Jellyfin.Plugin.SRFPlay/Services/Interfaces/ICategoryService.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/Interfaces/ICategoryService.cs
@ -0,0 +1,70 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Plugin.SRFPlay.Api.Models;
+
+namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;
+
+/// <summary>
+/// Interface for managing topic/category data and filtering.
+/// </summary>
+public interface ICategoryService
+{
+    /// <summary>
+    /// Gets all topics for a business unit.
+    /// </summary>
+    /// <param name="businessUnit">The business unit.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>List of topics.</returns>
+    Task<List<PlayV3Topic>> GetTopicsAsync(string businessUnit, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets a topic by ID.
+    /// </summary>
+    /// <param name="topicId">The topic ID.</param>
+    /// <param name="businessUnit">The business unit.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The topic, or null if not found.</returns>
+    Task<PlayV3Topic?> GetTopicByIdAsync(string topicId, string businessUnit, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Filters shows by topic ID.
+    /// </summary>
+    /// <param name="shows">The shows to filter.</param>
+    /// <param name="topicId">The topic ID to filter by.</param>
+    /// <returns>Filtered list of shows.</returns>
+    IReadOnlyList<PlayV3Show> FilterShowsByTopic(IReadOnlyList<PlayV3Show> shows, string topicId);
+
+    /// <summary>
+    /// Groups shows by their topics.
+    /// </summary>
+    /// <param name="shows">The shows to group.</param>
+    /// <returns>Dictionary mapping topic IDs to shows.</returns>
+    IReadOnlyDictionary<string, List<PlayV3Show>> GroupShowsByTopics(IReadOnlyList<PlayV3Show> shows);
+
+    /// <summary>
+    /// Gets shows for a specific topic, sorted by number of episodes.
+    /// </summary>
+    /// <param name="topicId">The topic ID.</param>
+    /// <param name="businessUnit">The business unit.</param>
+    /// <param name="maxResults">Maximum number of results to return.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>List of shows for the topic.</returns>
+    Task<List<PlayV3Show>> GetShowsByTopicAsync(
+        string topicId,
+        string businessUnit,
+        int maxResults = 50,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets video count for each topic.
+    /// </summary>
+    /// <param name="shows">The shows to analyze.</param>
+    /// <returns>Dictionary mapping topic IDs to video counts.</returns>
+    IReadOnlyDictionary<string, int> GetVideoCountByTopic(IReadOnlyList<PlayV3Show> shows);
+
+    /// <summary>
+    /// Clears the topics cache.
+    /// </summary>
+    void ClearCache();
+}
--- a/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IContentExpirationService.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IContentExpirationService.cs
@ -0,0 +1,24 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;
+
+/// <summary>
+/// Interface for managing content expiration.
+/// </summary>
+public interface IContentExpirationService
+{
+    /// <summary>
+    /// Checks for expired content and removes it from the library.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The number of items removed.</returns>
+    Task<int> CheckAndRemoveExpiredContentAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Gets statistics about content expiration.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>Tuple with total count, expired count, and items expiring soon.</returns>
+    Task<(int Total, int Expired, int ExpiringSoon)> GetExpirationStatisticsAsync(CancellationToken cancellationToken);
+}
--- a/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IContentRefreshService.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IContentRefreshService.cs
@ -0,0 +1,39 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;
+
+/// <summary>
+/// Interface for refreshing content from SRF API.
+/// </summary>
+public interface IContentRefreshService
+{
+    /// <summary>
+    /// Refreshes latest content from SRF API using Play v3.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>List of URNs for new content.</returns>
+    Task<List<string>> RefreshLatestContentAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Refreshes trending content from SRF API using Play v3.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>List of URNs for trending content.</returns>
+    Task<List<string>> RefreshTrendingContentAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Refreshes all content (latest and trending).
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>Tuple with counts of latest and trending items.</returns>
+    Task<(int LatestCount, int TrendingCount)> RefreshAllContentAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Gets content recommendations (combines latest and trending).
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>List of recommended URNs.</returns>
+    Task<List<string>> GetRecommendedContentAsync(CancellationToken cancellationToken);
+}
--- a/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IMediaCompositionFetcher.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IMediaCompositionFetcher.cs
@ -0,0 +1,23 @@
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Plugin.SRFPlay.Api.Models;
+
+namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;
+
+/// <summary>
+/// Interface for fetching media composition with caching support.
+/// </summary>
+public interface IMediaCompositionFetcher
+{
+    /// <summary>
+    /// Gets media composition by URN, using cache if available.
+    /// </summary>
+    /// <param name="urn">The URN to fetch.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <param name="cacheDurationOverride">Optional override for cache duration (e.g., 5 min for livestreams).</param>
+    /// <returns>The media composition, or null if not found.</returns>
+    Task<MediaComposition?> GetMediaCompositionAsync(
+        string urn,
+        CancellationToken cancellationToken,
+        int? cacheDurationOverride = null);
+}
--- a/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IMetadataCache.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IMetadataCache.cs
@ -0,0 +1,41 @@
+using Jellyfin.Plugin.SRFPlay.Api.Models;
+
+namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;
+
+/// <summary>
+/// Interface for caching metadata from SRF API.
+/// </summary>
+public interface IMetadataCache
+{
+    /// <summary>
+    /// Gets cached media composition by URN.
+    /// </summary>
+    /// <param name="urn">The URN.</param>
+    /// <param name="cacheDurationMinutes">The cache duration in minutes.</param>
+    /// <returns>The cached media composition, or null if not found or expired.</returns>
+    MediaComposition? GetMediaComposition(string urn, int cacheDurationMinutes);
+
+    /// <summary>
+    /// Sets media composition in cache.
+    /// </summary>
+    /// <param name="urn">The URN.</param>
+    /// <param name="mediaComposition">The media composition to cache.</param>
+    void SetMediaComposition(string urn, MediaComposition mediaComposition);
+
+    /// <summary>
+    /// Removes media composition from cache.
+    /// </summary>
+    /// <param name="urn">The URN.</param>
+    void RemoveMediaComposition(string urn);
+
+    /// <summary>
+    /// Clears all cached data.
+    /// </summary>
+    void Clear();
+
+    /// <summary>
+    /// Gets the cache statistics.
+    /// </summary>
+    /// <returns>A tuple with cache count and size estimate.</returns>
+    (int Count, long SizeEstimate) GetStatistics();
+}
--- a/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IStreamProxyService.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IStreamProxyService.cs
@ -0,0 +1,56 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;
+
+/// <summary>
+/// Interface for proxying SRF Play streams and managing authentication.
+/// </summary>
+public interface IStreamProxyService
+{
+    /// <summary>
+    /// Registers a stream for proxying.
+    /// </summary>
+    /// <param name="itemId">The item ID.</param>
+    /// <param name="authenticatedUrl">The authenticated stream URL.</param>
+    /// <param name="urn">The SRF URN for this content (used for re-fetching fresh URLs).</param>
+    /// <param name="isLiveStream">Whether this is a livestream (livestreams always fetch fresh URLs).</param>
+    void RegisterStream(string itemId, string authenticatedUrl, string? urn = null, bool isLiveStream = false);
+
+    /// <summary>
+    /// Gets stream metadata for an item (URN and isLiveStream flag).
+    /// </summary>
+    /// <param name="itemId">The item ID.</param>
+    /// <returns>A tuple of (URN, IsLiveStream), or null if not found.</returns>
+    (string? Urn, bool IsLiveStream)? GetStreamMetadata(string itemId);
+
+    /// <summary>
+    /// Gets the authenticated URL for an item.
+    /// </summary>
+    /// <param name="itemId">The item ID.</param>
+    /// <returns>The authenticated URL, or null if not found or expired.</returns>
+    string? GetAuthenticatedUrl(string itemId);
+
+    /// <summary>
+    /// Fetches and rewrites an HLS manifest to use proxy URLs.
+    /// </summary>
+    /// <param name="itemId">The item ID.</param>
+    /// <param name="baseProxyUrl">The base proxy URL.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The rewritten manifest content.</returns>
+    Task<string?> GetRewrittenManifestAsync(string itemId, string baseProxyUrl, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Fetches a segment from the original source.
+    /// </summary>
+    /// <param name="itemId">The item ID.</param>
+    /// <param name="segmentPath">The segment path.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The segment content as bytes.</returns>
+    Task<byte[]?> GetSegmentAsync(string itemId, string segmentPath, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Cleans up old and expired stream mappings.
+    /// </summary>
+    void CleanupOldMappings();
+}
--- a/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IStreamUrlResolver.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/Interfaces/IStreamUrlResolver.cs
@ -0,0 +1,42 @@
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Plugin.SRFPlay.Api.Models;
+using Jellyfin.Plugin.SRFPlay.Configuration;
+
+namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;
+
+/// <summary>
+/// Interface for resolving stream URLs from media composition resources.
+/// </summary>
+public interface IStreamUrlResolver
+{
+    /// <summary>
+    /// Gets the best stream URL from a chapter based on quality preference.
+    /// </summary>
+    /// <param name="chapter">The chapter containing resources.</param>
+    /// <param name="qualityPreference">The quality preference.</param>
+    /// <returns>The stream URL, or null if no suitable stream found.</returns>
+    string? GetStreamUrl(Chapter chapter, QualityPreference qualityPreference);
+
+    /// <summary>
+    /// Checks if a chapter has non-DRM playable content.
+    /// </summary>
+    /// <param name="chapter">The chapter to check.</param>
+    /// <returns>True if playable content is available.</returns>
+    bool HasPlayableContent(Chapter chapter);
+
+    /// <summary>
+    /// Checks if content is expired based on ValidTo date.
+    /// </summary>
+    /// <param name="chapter">The chapter to check.</param>
+    /// <returns>True if the content is expired.</returns>
+    bool IsContentExpired(Chapter chapter);
+
+    /// <summary>
+    /// Authenticates a stream URL by fetching an Akamai token.
+    /// </summary>
+    /// <param name="streamUrl">The unauthenticated stream URL.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The authenticated stream URL with token.</returns>
+    Task<string> GetAuthenticatedStreamUrlAsync(string streamUrl, CancellationToken cancellationToken = default);
+}
--- a/Jellyfin.Plugin.SRFPlay/Services/MediaCompositionFetcher.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/MediaCompositionFetcher.cs
@ -0,0 +1,82 @@
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Plugin.SRFPlay.Api;
+using Jellyfin.Plugin.SRFPlay.Api.Models;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
+using Microsoft.Extensions.Logging;
+
+namespace Jellyfin.Plugin.SRFPlay.Services;
+
+/// <summary>
+/// Service for fetching media composition with caching support.
+/// This consolidates the cache-check → API-fetch → cache-store pattern.
+/// </summary>
+public class MediaCompositionFetcher : IMediaCompositionFetcher
+{
+    private readonly ILogger<MediaCompositionFetcher> _logger;
+    private readonly IMetadataCache _metadataCache;
+    private readonly ISRFApiClientFactory _apiClientFactory;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MediaCompositionFetcher"/> class.
+    /// </summary>
+    /// <param name="logger">The logger.</param>
+    /// <param name="metadataCache">The metadata cache.</param>
+    /// <param name="apiClientFactory">The API client factory.</param>
+    public MediaCompositionFetcher(
+        ILogger<MediaCompositionFetcher> logger,
+        IMetadataCache metadataCache,
+        ISRFApiClientFactory apiClientFactory)
+    {
+        _logger = logger;
+        _metadataCache = metadataCache;
+        _apiClientFactory = apiClientFactory;
+    }
+
+    /// <inheritdoc />
+    public async Task<MediaComposition?> GetMediaCompositionAsync(
+        string urn,
+        CancellationToken cancellationToken,
+        int? cacheDurationOverride = null)
+    {
+        if (string.IsNullOrEmpty(urn))
+        {
+            _logger.LogDebug("GetMediaCompositionAsync called with null/empty URN");
+            return null;
+        }
+
+        var config = Plugin.Instance?.Configuration;
+        if (config == null)
+        {
+            _logger.LogWarning("Plugin configuration is null, cannot fetch media composition");
+            return null;
+        }
+
+        var cacheDuration = cacheDurationOverride ?? config.CacheDurationMinutes;
+
+        // Try cache first
+        var mediaComposition = _metadataCache.GetMediaComposition(urn, cacheDuration);
+        if (mediaComposition != null)
+        {
+            _logger.LogDebug("Cache hit for URN: {Urn}", urn);
+            return mediaComposition;
+        }
+
+        // Fetch from API
+        _logger.LogDebug("Cache miss for URN: {Urn}, fetching from API", urn);
+        using var apiClient = _apiClientFactory.CreateClient();
+        mediaComposition = await apiClient.GetMediaCompositionByUrnAsync(urn, cancellationToken).ConfigureAwait(false);
+
+        if (mediaComposition != null)
+        {
+            _metadataCache.SetMediaComposition(urn, mediaComposition);
+            _logger.LogDebug("Cached media composition for URN: {Urn}", urn);
+        }
+        else
+        {
+            _logger.LogWarning("Failed to fetch media composition for URN: {Urn}", urn);
+        }
+
+        return mediaComposition;
+    }
+}
--- a/Jellyfin.Plugin.SRFPlay/Services/MetadataCache.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/MetadataCache.cs
@ -2,6 +2,7 @@ using System;
 using System.Collections.Concurrent;
 using System.Threading;
 using Jellyfin.Plugin.SRFPlay.Api.Models;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using Microsoft.Extensions.Logging;

 namespace Jellyfin.Plugin.SRFPlay.Services;
@ -9,7 +10,7 @@ namespace Jellyfin.Plugin.SRFPlay.Services;
 /// <summary>
 /// Service for caching metadata from SRF API.
 /// </summary>
-public sealed class MetadataCache : IDisposable
+public sealed class MetadataCache : IMetadataCache, IDisposable
 {
    private readonly ILogger<MetadataCache> _logger;
    private readonly ConcurrentDictionary<string, CacheEntry<MediaComposition>> _mediaCompositionCache;
--- a/Jellyfin.Plugin.SRFPlay/Services/StreamProxyService.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/StreamProxyService.cs
@ -8,6 +8,7 @@ using System.Threading.Tasks;
 using System.Web;
 using Jellyfin.Plugin.SRFPlay.Api;
 using Jellyfin.Plugin.SRFPlay.Configuration;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using Microsoft.Extensions.Logging;

 namespace Jellyfin.Plugin.SRFPlay.Services;
@ -15,11 +16,11 @@ namespace Jellyfin.Plugin.SRFPlay.Services;
 /// <summary>
 /// Service for proxying SRF Play streams and managing authentication.
 /// </summary>
-public class StreamProxyService : IDisposable
+public class StreamProxyService : IStreamProxyService, IDisposable
 {
    private readonly ILogger<StreamProxyService> _logger;
-    private readonly ILoggerFactory _loggerFactory;
-    private readonly StreamUrlResolver _streamResolver;
+    private readonly IStreamUrlResolver _streamResolver;
+    private readonly IMediaCompositionFetcher _compositionFetcher;
    private readonly HttpClient _httpClient;
    private readonly ConcurrentDictionary<string, StreamInfo> _streamMappings;
    private bool _disposed;
@ -28,13 +29,16 @@ public class StreamProxyService : IDisposable
    /// Initializes a new instance of the <see cref="StreamProxyService"/> class.
    /// </summary>
    /// <param name="logger">The logger.</param>
-    /// <param name="loggerFactory">The logger factory (for creating API clients).</param>
    /// <param name="streamResolver">The stream URL resolver.</param>
-    public StreamProxyService(ILogger<StreamProxyService> logger, ILoggerFactory loggerFactory, StreamUrlResolver streamResolver)
+    /// <param name="compositionFetcher">The media composition fetcher.</param>
+    public StreamProxyService(
+        ILogger<StreamProxyService> logger,
+        IStreamUrlResolver streamResolver,
+        IMediaCompositionFetcher compositionFetcher)
    {
        _logger = logger;
-        _loggerFactory = loggerFactory;
        _streamResolver = streamResolver;
+        _compositionFetcher = compositionFetcher;
        _httpClient = new HttpClient
        {
            Timeout = TimeSpan.FromSeconds(30)
@ -306,8 +310,8 @@ public class StreamProxyService : IDisposable

        try
        {
-            using var apiClient = new SRFApiClient(_loggerFactory);
-            var mediaComposition = apiClient.GetMediaCompositionByUrnAsync(streamInfo.Urn, CancellationToken.None)
+            // Use short cache duration (5 min) for livestreams
+            var mediaComposition = _compositionFetcher.GetMediaCompositionAsync(streamInfo.Urn, CancellationToken.None, 5)
                .GetAwaiter().GetResult();

            if (mediaComposition?.ChapterList == null || mediaComposition.ChapterList.Count == 0)
--- a/Jellyfin.Plugin.SRFPlay/Services/StreamUrlResolver.cs
+++ b/Jellyfin.Plugin.SRFPlay/Services/StreamUrlResolver.cs
@ -6,6 +6,7 @@ using System.Threading;
 using System.Threading.Tasks;
 using Jellyfin.Plugin.SRFPlay.Api.Models;
 using Jellyfin.Plugin.SRFPlay.Configuration;
+using Jellyfin.Plugin.SRFPlay.Services.Interfaces;
 using Microsoft.Extensions.Logging;

 namespace Jellyfin.Plugin.SRFPlay.Services;
@ -13,7 +14,7 @@ namespace Jellyfin.Plugin.SRFPlay.Services;
 /// <summary>
 /// Service for resolving stream URLs from media composition resources.
 /// </summary>
-public class StreamUrlResolver : IDisposable
+public class StreamUrlResolver : IStreamUrlResolver, IDisposable
 {
    private readonly ILogger<StreamUrlResolver> _logger;
    private readonly HttpClient _httpClient;