first commit

2025-11-12 22:05:36 +01:00
parent d544b71939
commit ac6a3842dd
46 changed files with 5891 additions and 499 deletions
@@ -0,0 +1,254 @@
+# 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:**
+   ```bash
+   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:**
+   ```bash
+   # 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.