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:**
   ```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.