fix: proper media element cleanup when switching stream types (fixes #101, #98)

[alexbj75]

Summary

Fixes #101 - Non-WebRTC streams now load correctly after WebRTC streams
Also fixes #98 - Standardized error reporting across all tech adapters

Problems Solved

1. Issue #101: Stream Switching Failure 🔴 CRITICAL

When users switched from WebRTC-based streams (WebRTC/WHEP/WHPP) to non-WebRTC streams (HLS/DASH), playback would fail completely. This was a critical bug preventing users from switching between different stream types.

Root Cause: Tech adapters weren't properly resetting the HTML media element state after clearing srcObject.

2. Issue #98: Inconsistent Error Reporting 🟡 MEDIUM

Different tech adapters (Shaka, HLS.js, dash.js) emitted errors in different formats, making it difficult for applications to handle errors consistently.

Solutions

Media Element Cleanup (Issue #101)

All tech adapters now properly reset the media element in destroy():

destroy(): void {
  // ... tech-specific cleanup
  this.videoElement.srcObject = null; // Only for WebRTC techs
  this.videoElement.removeAttribute("src");
  this.videoElement.load(); // ← Critical: resets media element state
}

This ensures the video element is fully reset and ready to accept new sources of any type.

Files Updated:

• WebRTCTech.ts, WHEPTech.ts, WHPPTech.ts: Added full cleanup pattern including load() call
• HlsJsTech.ts, DashJsTech.ts, ShakaTech.ts: Added load() call for consistency

Standardized Error Reporting (Issue #98)

Created shared error formatting utilities in util/errors.ts:

// All errors now follow this shape:
{
  errorData: {
    category: string, // e.g., "NETWORK", "MEDIA"
    code: string,     // e.g., HTTP status code or error code
    message: string,  // Human-readable message
    data: any        // Raw error data
  },
  fatal: boolean
}

Formatters provided:

• formatShakaError(): Shaka Player errors
• formatHlsError(): HLS.js errors
• formatDashError(): dash.js errors
• formatPlayerError(): Generic formatter

Benefits:

• ✅ Consistent error structure across all tech adapters
• ✅ Easier to implement error handling in applications
• ✅ Better debugging experience for developers

Comprehensive Test Coverage

Added robust unit tests for all tech adapters:

• BaseTech.test.ts: Base class behavior tests
• ShakaTech.test.ts: Shaka Player integration (comprehensive)
• HlsJsTech.test.ts: HLS.js integration tests
• DashJsTech.test.ts: dash.js integration tests
• errors.test.ts: Error formatting utility tests

Testing Results

✅ Test Suites: 8 passed, 8 total
✅ Tests: 133 passed, 133 total
✅ Build: Successful (all packages)
✅ No regressions

Technical Details

Why load() is Critical

According to the HTML5 specification, when a media element has been using srcObject, calling load() after clearing it is necessary to properly reset the element's network state and media resource. Without this, the element may remain in an invalid state where it cannot accept new sources via src attribute or media libraries.

Error Format Rationale

The standardized error format was designed to:

1. Be consistent across all streaming technologies
2. Provide actionable information (category, code, message)
3. Preserve raw data for advanced debugging
4. Indicate severity with the fatal flag

Files Changed

Tech Adapters (6 files):

• packages/core/src/tech/WebRTCTech.ts
• packages/core/src/tech/WHEPTech.ts
• packages/core/src/tech/WHPPTech.ts
• packages/core/src/tech/HlsJsTech.ts
• packages/core/src/tech/DashJsTech.ts
• packages/core/src/tech/ShakaTech.ts

New Utilities (2 files):

• packages/core/src/util/errors.ts - Error formatting utilities
• packages/core/src/util/errors.test.ts - Error utility tests

New Tests (4 files):

• packages/core/src/tech/BaseTech.test.ts
• packages/core/src/tech/ShakaTech.test.ts
• packages/core/src/tech/HlsJsTech.test.ts
• packages/core/src/tech/DashJsTech.test.ts

Impact

• 🔧 Fixes critical stream switching bug affecting all users who switch between WebRTC and non-WebRTC streams
• 📊 Improves error handling for application developers
• ✅ Adds comprehensive test coverage to prevent future regressions
• 🛡️ Backward compatible - no breaking changes to public API

Migration Notes

No action required for existing applications. The changes are internal improvements that maintain backward compatibility.

Applications can optionally start using the standardized error format for better error handling:

player.on(PlayerEvent.ERROR, (error) => {
  const { errorData, fatal } = error;
  console.log(`[${errorData.category}] ${errorData.message} (code: ${errorData.code})`);
  if (fatal) {
    // Handle fatal error
  }
});

🤖 Generated with Claude Code