jellyfin-srfPlay/DEBUG_GUIDE.md

Debugging Guide for SRF Play Plugin

This guide helps you debug issues with the SRF Play plugin, including proxy configuration and content fetching problems.

Enhanced Logging

The plugin now includes detailed logging to help diagnose issues. After installing the updated version, check your Jellyfin logs for these key messages.

Key Log Messages to Look For

1. Proxy Configuration Status

When the plugin initializes, you'll see:

Without proxy:

[INF] SRFApiClient initializing without proxy

With proxy:

[INF] SRFApiClient initializing with proxy enabled: http://your-proxy:port
[INF] Proxy configured: http://your-proxy:port (Authentication: True/False)

Proxy configuration errors:

[ERR] Failed to configure proxy: http://your-proxy:port

2. Media Composition Fetching

For each video URN, you'll see detailed logs:

[INF] Fetching media composition for URN: urn:srf:video:12345 from https://il.srgssr.ch/integrationlayer/2.0/mediaComposition/byUrn/urn:srf:video:12345.json
[INF] Media composition response for URN urn:srf:video:12345: StatusCode=OK
[INF] Successfully fetched media composition for URN: urn:srf:video:12345 - Chapters: 1

If there are no chapters:

[WRN] Media composition for URN urn:srf:video:12345 has no chapters

HTTP errors:

[ERR] HTTP error fetching media composition for URN: urn:srf:video:12345 - StatusCode: 404

3. Stream URL Resolution

For each chapter, you'll see detailed resource processing:

[INF] Processing chapter abc123 with 5 resources
[INF] Chapter abc123: Total resources=5, Non-DRM resources=2
[INF] Chapter abc123: HLS resources found=1

DRM-protected content:

[WRN] All resources for chapter abc123 require DRM
[DBG] DRM resource: Protocol=HLS, Streaming=HLS, DRM=WIDEVINE

No HLS streams:

[WRN] No HLS resources found for chapter: abc123
[DBG] Non-HLS resource: Protocol=HTTP, Streaming=PROGRESSIVE, URL=https://...
[INF] Using fallback resource for chapter abc123: https://...

Common Issues and Solutions

Issue 1: Videos Not Loading (Conversion Failures)

Symptoms:

Conversion complete: 0 successful, 18 failed, 0 expired, 0 no stream

Debugging steps:

1. Check for DRM content:

   • Look for: All resources for chapter XXX require DRM
   • Solution: This content cannot be played (Widevine DRM protection)

2. Check for HTTP errors:

   • Look for: HTTP error fetching media composition with status codes
   • Common codes:
     • 403 Forbidden: Geo-restriction or blocked
     • 404 Not Found: Content removed or URN invalid
     • 429 Too Many Requests: Rate limiting
   • Solution: Check if proxy is needed for geo-restrictions

3. Check for missing chapters:

   • Look for: Media composition for URN XXX has no chapters
   • Solution: This video metadata is incomplete or invalid

Issue 2: Proxy Not Being Used

Symptoms:

• Plugin says "initializing without proxy" even though configured
• Getting geo-restriction errors (403)

Debugging steps:

1. Check the initialization log:

   [INF] SRFApiClient initializing with proxy enabled: http://...
   

2. If it says "without proxy", check:

   • Is "Use Proxy" checkbox enabled in plugin settings?
   • Is the Proxy Address field filled in?
   • Did you restart Jellyfin after saving?

3. Check for proxy errors:

   [ERR] Failed to configure proxy: http://...
   

   • Verify the proxy URL format (must include http:// or socks5://)
   • Test proxy connectivity: curl --proxy http://proxy:port https://il.srgssr.ch

Issue 3: Proxy Connection Failures

Symptoms:

[ERR] HTTP error fetching media composition for URN: ... - StatusCode: null

or timeout errors

Debugging steps:

1. Verify proxy is reachable from Jellyfin server:

   curl --proxy http://your-proxy:port https://il.srgssr.ch
   

2. Check proxy authentication:

   • If proxy requires auth, ensure username/password are configured
   • Look for: Proxy configured: ... (Authentication: True)

3. Check proxy supports HTTPS:

   • The SRF API uses HTTPS, ensure your proxy can handle it

4. Test with a simple HTTP proxy:

   # Test with SSH tunnel as SOCKS5 proxy
   ssh -D 1080 -N user@gateway-server
   # Then configure: socks5://127.0.0.1:1080
   

Issue 4: Content Expiration

Symptoms:

Conversion complete: 0 successful, 0 failed, 10 expired, 0 no stream

Solution:

• Content has expired and is no longer available
• Check the expiration task runs regularly
• Some content is time-limited by SRF

Enabling Debug Logs

To see even more detailed logs (like [DBG] messages), modify your Jellyfin logging configuration:

1. Go to Dashboard → Logs
2. Click Settings
3. Set log level to Debug for troubleshooting
4. Restart Jellyfin

Warning: Debug logging can be very verbose and consume disk space quickly. Only enable temporarily.

Testing Proxy Configuration

To verify your proxy is working:

1. Enable Proxy in Plugin Settings

• Dashboard → Plugins → SRF Play
• Check "Use Proxy"
• Enter your proxy address
• Save and restart Jellyfin

2. Check Initialization Logs

Look for:

[INF] SRFApiClient initializing with proxy enabled: http://your-proxy:port
[INF] Proxy configured: http://your-proxy:port (Authentication: False)

3. Trigger Content Refresh

• Dashboard → Scheduled Tasks → "Refresh SRF Play Content"
• Run task manually
• Watch logs for media composition requests

4. Verify Requests Go Through Proxy

You can monitor proxy logs (if available) or use network monitoring tools to confirm traffic routes through the proxy.

Getting Help

When reporting issues, include:

1. Plugin version:

   • Dashboard → Plugins → SRF Play → Version

2. Relevant log entries:

   • The initialization message (with/without proxy)
   • Any error messages
   • The "Conversion complete" summary
   • Resource processing details for failed items

3. Configuration:

   • Business unit selected
   • Proxy enabled? (yes/no, don't share credentials)
   • Where Jellyfin is running (local network, VPS, etc.)

4. Network environment:

   • Are you behind a geo-restriction?
   • Is the proxy on the same network or remote?
   • Any firewalls or network policies?

Example of Good Debug Output

When everything works correctly with proxy:

[INF] SRFApiClient initializing with proxy enabled: http://192.168.1.1:3128
[INF] Proxy configured: http://192.168.1.1:3128 (Authentication: False)
[INF] Fetching media composition for URN: urn:srf:video:12345 from https://il.srgssr.ch/...
[INF] Media composition response for URN urn:srf:video:12345: StatusCode=OK
[INF] Successfully fetched media composition for URN: urn:srf:video:12345 - Chapters: 1
[INF] Processing chapter abc123 with 3 resources
[INF] Chapter abc123: Total resources=3, Non-DRM resources=2
[INF] Chapter abc123: HLS resources found=1
[DBG] Selected stream for chapter abc123: Quality=HD, Protocol=HLS, URL=https://...m3u8

Example of Failed Conversion (DRM Issue)

[INF] Fetching media composition for URN: urn:srf:video:67890 from https://il.srgssr.ch/...
[INF] Media composition response for URN urn:srf:video:67890: StatusCode=OK
[INF] Successfully fetched media composition for URN: urn:srf:video:67890 - Chapters: 1
[INF] Processing chapter def456 with 2 resources
[INF] Chapter def456: Total resources=2, Non-DRM resources=0
[WRN] All resources for chapter def456 require DRM
[DBG] DRM resource: Protocol=HLS, Streaming=HLS, DRM=WIDEVINE

This means the content requires Widevine DRM and cannot be played by Jellyfin.