feat(camera): add intelligent OEM fallback stream detection

GhostTypes · GhostTypes · commit 6c1a0fea21f1 · 2026-03-21T15:50:55.000-04:00
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -71,7 +71,7 @@
   "author": "Parallel-7",
   "license": "MIT",
   "dependencies": {
-    "@ghosttypes/ff-api": "^1.2.0",
+    "@ghosttypes/ff-api": "^1.3.0",
     "@parallel-7/slicer-meta": "1.1.0-20251121155836",
     "axios": "^1.8.4",
     "express": "^5.1.0",
diff --git a/src/printer-backends/AD5XBackend.ts b/src/printer-backends/AD5XBackend.ts
@@ -48,6 +48,7 @@ export class AD5XBackend extends DualAPIBackend {
     return {
       camera: {
         oemStreamUrl: '',
+        fallbackStreamUrl: '',
         customUrl: null,
         customEnabled: false,
       },
diff --git a/src/printer-backends/Adventurer5MBackend.ts b/src/printer-backends/Adventurer5MBackend.ts
@@ -34,6 +34,7 @@ export class Adventurer5MBackend extends DualAPIBackend {
     return {
       camera: {
         oemStreamUrl: '',
+        fallbackStreamUrl: '',
         customUrl: null,
         customEnabled: false,
       },
diff --git a/src/printer-backends/Adventurer5MProBackend.ts b/src/printer-backends/Adventurer5MProBackend.ts
@@ -34,6 +34,7 @@ export class Adventurer5MProBackend extends DualAPIBackend {
     return {
       camera: {
         oemStreamUrl: '',
+        fallbackStreamUrl: '',
         customUrl: null,
         customEnabled: false,
       },
diff --git a/src/printer-backends/BasePrinterBackend.ts b/src/printer-backends/BasePrinterBackend.ts
@@ -81,6 +81,7 @@ export abstract class BasePrinterBackend extends EventEmitter {
   protected customLedsEnabled: boolean;
   protected forceLegacyMode: boolean;
   protected oemCameraStreamUrl: string = '';
+  protected fallbackCameraStreamUrl: string = '';
 
   constructor(options: BackendInitOptions) {
     super();
@@ -165,6 +166,18 @@ export abstract class BasePrinterBackend extends EventEmitter {
     return true;
   }
 
+  protected updateFallbackCameraStreamUrl(streamUrl: string | null | undefined): boolean {
+    const nextFallbackCameraStreamUrl = typeof streamUrl === 'string' ? streamUrl.trim() : '';
+
+    if (this.fallbackCameraStreamUrl === nextFallbackCameraStreamUrl) {
+      return false;
+    }
+
+    this.fallbackCameraStreamUrl = nextFallbackCameraStreamUrl;
+    this.rebuildFeatureSet(true, ['fallbackCameraStreamUrl']);
+    return true;
+  }
+
   /**
    * Emit backend event
    */
@@ -252,6 +265,7 @@ export abstract class BasePrinterBackend extends EventEmitter {
     return {
       camera: {
         oemStreamUrl: baseFeatures.camera.oemStreamUrl || this.oemCameraStreamUrl,
+        fallbackStreamUrl: baseFeatures.camera.fallbackStreamUrl || this.fallbackCameraStreamUrl,
         customUrl: settingsOverrides.customCameraEnabled
           ? String(settingsOverrides.customCameraUrl)
           : null,
@@ -329,6 +343,7 @@ export abstract class BasePrinterBackend extends EventEmitter {
       case 'camera':
         return (
           this.features.camera.oemStreamUrl.trim() !== '' ||
+          this.features.camera.fallbackStreamUrl.trim() !== '' ||
           (this.features.camera.customEnabled &&
             this.features.camera.customUrl !== null &&
             this.features.camera.customUrl.trim() !== '')
diff --git a/src/printer-backends/DualAPIBackend.ts b/src/printer-backends/DualAPIBackend.ts
@@ -39,9 +39,12 @@ import { BasePrinterBackend } from './BasePrinterBackend';
  * Provides common implementation for printers using both FiveMClient and FlashForgeClient
  */
 export abstract class DualAPIBackend extends BasePrinterBackend {
+  private static readonly FALLBACK_CAMERA_RETRY_MS = 60_000;
+
   protected fiveMClient!: FiveMClient;
   protected legacyClient!: FlashForgeClient;
   protected productInfo: Product | null = null;
+  private lastFallbackCameraProbeAt = 0;
 
   /**
    * Cache for last known filament usage data while printing
@@ -861,6 +864,25 @@ export abstract class DualAPIBackend extends BasePrinterBackend {
     const info = _machineInfo as { CameraStreamUrl?: unknown } | null;
     const cameraStreamUrl = typeof info?.CameraStreamUrl === 'string' ? info.CameraStreamUrl : '';
     this.updateOEMCameraStreamUrl(cameraStreamUrl);
+
+    if (cameraStreamUrl.trim() !== '') {
+      this.updateFallbackCameraStreamUrl('');
+      this.lastFallbackCameraProbeAt = 0;
+      return;
+    }
+
+    if (this.fallbackCameraStreamUrl.trim() !== '') {
+      return;
+    }
+
+    const now = Date.now();
+    if (now - this.lastFallbackCameraProbeAt < DualAPIBackend.FALLBACK_CAMERA_RETRY_MS) {
+      return;
+    }
+
+    this.lastFallbackCameraProbeAt = now;
+    const detectedCameraStreamUrl = await this.fiveMClient.detectCameraStream();
+    this.updateFallbackCameraStreamUrl(detectedCameraStreamUrl);
   }
 
   /**
@@ -889,6 +911,7 @@ export abstract class DualAPIBackend extends BasePrinterBackend {
   public async dispose(): Promise<void> {
     // Clear filament usage cache on disconnect
     this.lastFilamentUsageCache = null;
+    this.lastFallbackCameraProbeAt = 0;
 
     // Call parent dispose to clean up clients
     await super.dispose();
diff --git a/src/printer-backends/GenericLegacyBackend.ts b/src/printer-backends/GenericLegacyBackend.ts
@@ -65,6 +65,7 @@ export class GenericLegacyBackend extends BasePrinterBackend {
     return {
       camera: {
         oemStreamUrl: '',
+        fallbackStreamUrl: '',
         customUrl: null,
         customEnabled: false,
       },
diff --git a/src/services/CameraStreamCoordinator.ts b/src/services/CameraStreamCoordinator.ts
@@ -21,8 +21,10 @@ export interface EnsuredCameraStream {
   readonly streamConfig: CameraStreamConfig;
 }
 
-function isGo2rtcSourceType(sourceType: CameraSourceType): sourceType is 'oem' | 'custom' {
-  return sourceType === 'oem' || sourceType === 'custom';
+function isGo2rtcSourceType(
+  sourceType: CameraSourceType
+): sourceType is 'oem' | 'custom' | 'intelligent-fallback' {
+  return sourceType === 'oem' || sourceType === 'custom' || sourceType === 'intelligent-fallback';
 }
 
 export async function resolveAndEnsureCameraStream(
diff --git a/src/services/Go2rtcService.ts b/src/services/Go2rtcService.ts
@@ -18,7 +18,7 @@ interface ManagedStream {
   contextId: string;
   streamName: string;
   sourceUrl: string;
-  sourceType: 'oem' | 'custom';
+  sourceType: 'oem' | 'custom' | 'intelligent-fallback';
   streamType: 'mjpeg' | 'rtsp';
   addedAt: number;
 }
@@ -146,7 +146,7 @@ export class Go2rtcService extends EventEmitter<Go2rtcServiceEvents> {
   public hasMatchingStream(
     contextId: string,
     sourceUrl: string,
-    sourceType: 'oem' | 'custom',
+    sourceType: 'oem' | 'custom' | 'intelligent-fallback',
     streamType: 'mjpeg' | 'rtsp'
   ): boolean {
     const stream = this.streams.get(contextId);
@@ -163,7 +163,7 @@ export class Go2rtcService extends EventEmitter<Go2rtcServiceEvents> {
   public async addStream(
     contextId: string,
     sourceUrl: string,
-    sourceType: 'oem' | 'custom',
+    sourceType: 'oem' | 'custom' | 'intelligent-fallback',
     streamType: 'mjpeg' | 'rtsp'
   ): Promise<void> {
     if (!this.isRunning()) {
diff --git a/src/types/camera.ts b/src/types/camera.ts
@@ -4,7 +4,7 @@
 
 import type { PrinterFeatureSet } from './printer-backend';
 
-export type CameraSourceType = 'oem' | 'custom' | 'none';
+export type CameraSourceType = 'oem' | 'custom' | 'intelligent-fallback' | 'none';
 
 export type CameraStreamType = 'mjpeg' | 'rtsp';
 
diff --git a/src/types/go2rtc.types.ts b/src/types/go2rtc.types.ts
@@ -156,7 +156,7 @@ export interface CameraStreamConfig {
   /** WebSocket URL for stream negotiation. */
   wsUrl: string;
   /** Original source type. */
-  sourceType: 'oem' | 'custom';
+  sourceType: 'oem' | 'custom' | 'intelligent-fallback';
   /** Original stream type (before go2rtc conversion). */
   streamType: 'mjpeg' | 'rtsp';
   /** Preferred playback modes. */
diff --git a/src/types/printer-backend/printer-features.ts b/src/types/printer-backend/printer-features.ts
@@ -31,6 +31,7 @@ export type PrinterFeatureType =
  */
 export interface CameraFeature {
   readonly oemStreamUrl: string;
+  readonly fallbackStreamUrl: string;
   readonly customUrl: string | null;
   readonly customEnabled: boolean;
 }
diff --git a/src/utils/camera-utils.test.ts b/src/utils/camera-utils.test.ts
@@ -6,6 +6,7 @@ function createFeatures(oemStreamUrl = ''): PrinterFeatureSet {
   return {
     camera: {
       oemStreamUrl,
+      fallbackStreamUrl: '',
       customUrl: null,
       customEnabled: false,
     },
@@ -101,4 +102,28 @@ describe('resolveCameraConfig', () => {
       isAvailable: false,
     });
   });
+
+  it('uses the intelligent fallback camera URL when firmware omits the OEM stream', () => {
+    expect(
+      resolveCameraConfig({
+        printerIpAddress: '192.168.1.50',
+        printerFeatures: {
+          ...createFeatures(''),
+          camera: {
+            ...createFeatures('').camera,
+            fallbackStreamUrl: 'http://192.168.1.50:8080/?action=stream',
+          },
+        },
+        userConfig: {
+          customCameraEnabled: false,
+          customCameraUrl: null,
+        },
+      })
+    ).toMatchObject({
+      sourceType: 'intelligent-fallback',
+      streamType: 'mjpeg',
+      streamUrl: 'http://192.168.1.50:8080/?action=stream',
+      isAvailable: true,
+    });
+  });
 });
diff --git a/src/utils/camera-utils.ts b/src/utils/camera-utils.ts
@@ -5,7 +5,7 @@
  * URL validation, and human-readable status messaging.
  *
  * Key Features:
- * - Priority-based camera resolution: custom camera > OEM camera > none
+ * - Priority-based camera resolution: custom camera > OEM camera > intelligent fallback > none
  * - MJPEG and RTSP stream type detection and validation
  * - Context-aware camera configuration (per-printer or global settings)
  * - Settings normalization for stale custom-camera configurations
@@ -15,7 +15,8 @@
  * Resolution Priority:
  * 1. Custom camera (if enabled): Uses explicit user-provided URL only
  * 2. OEM camera: Uses the runtime stream URL reported by the printer
- * 3. No camera: Returns unavailable status with reason
+ * 3. Intelligent fallback: Uses the known OEM MJPEG endpoint when firmware omits the URL
+ * 4. No camera: Returns unavailable status with reason
  *
  * Stream Types Supported:
  * - MJPEG (Motion JPEG over HTTP/HTTPS)
@@ -143,7 +144,17 @@ export function resolveCameraConfig(params: CameraUrlResolutionParams): Resolved
     };
   }
 
-  // Priority 3: No camera available
+  // Priority 3: Check intelligent fallback camera URL
+  if (printerFeatures.camera.fallbackStreamUrl.trim() !== '') {
+    return {
+      sourceType: 'intelligent-fallback',
+      streamType: 'mjpeg',
+      streamUrl: printerFeatures.camera.fallbackStreamUrl,
+      isAvailable: true,
+    };
+  }
+
+  // Priority 4: No camera available
   return {
     sourceType: 'none',
     streamUrl: null,
@@ -203,6 +214,8 @@ export function getCameraStatusMessage(config: ResolvedCameraConfig): string {
     switch (config.sourceType) {
       case 'oem':
         return 'Using printer OEM camera';
+      case 'intelligent-fallback':
+        return 'Camera auto-detected';
       case 'custom':
         return 'Using custom camera URL';
       default:
diff --git a/src/webui/server/routes/camera-routes.ts b/src/webui/server/routes/camera-routes.ts
@@ -42,7 +42,7 @@ export function registerCameraRoutes(router: Router, deps: RouteDependencies): v
         cameraConfig.isAvailable &&
         !!cameraConfig.streamUrl &&
         !!cameraConfig.streamType &&
-        (cameraConfig.sourceType === 'oem' || cameraConfig.sourceType === 'custom') &&
+        cameraConfig.sourceType !== 'none' &&
         go2rtcService.hasMatchingStream(
           contextResult.contextId,
           cameraConfig.streamUrl,
diff --git a/src/webui/static/app.ts b/src/webui/static/app.ts
@@ -181,7 +181,7 @@ export interface CameraProxyConfigResponse extends ApiResponse {
   /** Original stream type (before go2rtc conversion) */
   streamType?: 'mjpeg' | 'rtsp';
   /** Original source type */
-  sourceType?: 'oem' | 'custom';
+  sourceType?: 'oem' | 'custom' | 'intelligent-fallback';
   /** Stream name in go2rtc */
   streamName?: string;
   /** go2rtc API port */

Original file line number	Diff line number	Diff line change
`@@ -21,8 +21,10 @@ export interface EnsuredCameraStream {`
`21`	`21`	`readonly streamConfig: CameraStreamConfig;`
`22`	`22`	`}`
`23`	`23`
`24`		`-function isGo2rtcSourceType(sourceType: CameraSourceType): sourceType is 'oem' \| 'custom' {`
`25`		`- return sourceType === 'oem' \|\| sourceType === 'custom';`
	`24`	`+function isGo2rtcSourceType(`
	`25`	`+ sourceType: CameraSourceType`
	`26`	`+): sourceType is 'oem' \| 'custom' \| 'intelligent-fallback' {`
	`27`	`+ return sourceType === 'oem' \|\| sourceType === 'custom' \|\| sourceType === 'intelligent-fallback';`
`26`	`28`	`}`
`27`	`29`
`28`	`30`	`export async function resolveAndEnsureCameraStream(`