@thestatic-tv/dcl-sdk 2.4.0 → 2.5.0

package/dist/index.d.mts

@@ -45,6 +45,12 @@ interface StaticTVConfig {
      * ```
      */
     videoScreen?: Entity;
+    /**
+     * Fallback video URL to play when no stream is active or stopVideo() is called.
+     * Prevents "broken screen" appearance. Set to empty string to disable.
+     * @default 'https://media.thestatic.tv/fallback-loop.mp4'
+     */
+    fallbackVideoUrl?: string;
     /**
      * Scene ID for Admin Panel API calls.
      * Optional - defaults to API key ID if not provided.
@@ -998,9 +1004,15 @@ declare class StaticTVClient {
     playVideo(url: string): void;
     /**
      * Stop video playback on the configured videoScreen entity.
+     * If fallbackVideoUrl is configured (default), plays the fallback loop.
      * Called by Admin Panel.
      */
     stopVideo(): void;
+    /**
+     * Internal video player - handles both regular videos and fallback
+     * @internal
+     */
+    private _playVideoInternal;
     /**
      * Get the currently playing video URL
      */

package/dist/index.d.ts

@@ -45,6 +45,12 @@ interface StaticTVConfig {
      * ```
      */
     videoScreen?: Entity;
+    /**
+     * Fallback video URL to play when no stream is active or stopVideo() is called.
+     * Prevents "broken screen" appearance. Set to empty string to disable.
+     * @default 'https://media.thestatic.tv/fallback-loop.mp4'
+     */
+    fallbackVideoUrl?: string;
     /**
      * Scene ID for Admin Panel API calls.
      * Optional - defaults to API key ID if not provided.
@@ -998,9 +1004,15 @@ declare class StaticTVClient {
     playVideo(url: string): void;
     /**
      * Stop video playback on the configured videoScreen entity.
+     * If fallbackVideoUrl is configured (default), plays the fallback loop.
      * Called by Admin Panel.
      */
     stopVideo(): void;
+    /**
+     * Internal video player - handles both regular videos and fallback
+     * @internal
+     */
+    private _playVideoInternal;
     /**
      * Get the currently playing video URL
      */

package/dist/index.js

@@ -3494,6 +3494,7 @@ function setupStaticUI(client) {
 // src/StaticTVClient.ts
 var import_ecs3 = require("@dcl/sdk/ecs");
 var DEFAULT_BASE_URL = "https://thestatic.tv/api/v1/dcl";
+var DEFAULT_FALLBACK_VIDEO = "https://media.thestatic.tv/fallback-loop.mp4";
 var KEY_TYPE_CHANNEL = "channel";
 var KEY_TYPE_SCENE = "scene";
 var StaticTVClient = class {
@@ -3731,17 +3732,7 @@ var StaticTVClient = class {
     if (screen !== void 0) {
       this.log(`Playing video: ${url}`);
       this._currentVideoUrl = url;
-      if (import_ecs3.VideoPlayer.has(screen)) {
-        import_ecs3.VideoPlayer.deleteFrom(screen);
-      }
-      import_ecs3.VideoPlayer.create(screen, {
-        src: url,
-        playing: true,
-        volume: 1
-      });
-      import_ecs3.Material.setBasicMaterial(screen, {
-        texture: import_ecs3.Material.Texture.Video({ videoPlayerEntity: screen })
-      });
+      this._playVideoInternal(url, false);
       if (this.guideUI) {
         const videos = this.guideUI.getVideos();
         const video = videos.find((v) => v.src === url);
@@ -3756,22 +3747,55 @@ var StaticTVClient = class {
   }
   /**
    * Stop video playback on the configured videoScreen entity.
+   * If fallbackVideoUrl is configured (default), plays the fallback loop.
    * Called by Admin Panel.
    */
   stopVideo() {
     const screen = this.config.videoScreen;
-    if (screen !== void 0 && import_ecs3.VideoPlayer.has(screen)) {
-      this.log("Stopping video");
-      import_ecs3.VideoPlayer.getMutable(screen).playing = false;
-      this._currentVideoUrl = "";
+    if (screen !== void 0) {
       if (this.guideUI) {
         this.guideUI.currentVideoId = null;
       }
+      const fallbackUrl = this.config.fallbackVideoUrl;
+      const fallbackDisabled = fallbackUrl === "";
+      if (fallbackDisabled) {
+        if (import_ecs3.VideoPlayer.has(screen)) {
+          this.log("Stopping video (no fallback)");
+          import_ecs3.VideoPlayer.getMutable(screen).playing = false;
+        }
+        this._currentVideoUrl = "";
+      } else {
+        const url = fallbackUrl || DEFAULT_FALLBACK_VIDEO;
+        this.log(`Playing fallback: ${url}`);
+        this._currentVideoUrl = "";
+        this._playVideoInternal(url, true);
+      }
     }
     if (this.config.onVideoStop) {
       this.config.onVideoStop();
     }
   }
+  /**
+   * Internal video player - handles both regular videos and fallback
+   * @internal
+   */
+  _playVideoInternal(url, isFallback = false) {
+    const screen = this.config.videoScreen;
+    if (screen === void 0) return;
+    if (import_ecs3.VideoPlayer.has(screen)) {
+      import_ecs3.VideoPlayer.deleteFrom(screen);
+    }
+    import_ecs3.VideoPlayer.create(screen, {
+      src: url,
+      playing: true,
+      loop: isFallback,
+      // Loop fallback videos
+      volume: 1
+    });
+    import_ecs3.Material.setBasicMaterial(screen, {
+      texture: import_ecs3.Material.Texture.Video({ videoPlayerEntity: screen })
+    });
+  }
   /**
    * Get the currently playing video URL
    */

package/dist/index.mjs

@@ -3451,6 +3451,7 @@ function setupStaticUI(client) {
 // src/StaticTVClient.ts
 import { VideoPlayer, Material } from "@dcl/sdk/ecs";
 var DEFAULT_BASE_URL = "https://thestatic.tv/api/v1/dcl";
+var DEFAULT_FALLBACK_VIDEO = "https://media.thestatic.tv/fallback-loop.mp4";
 var KEY_TYPE_CHANNEL = "channel";
 var KEY_TYPE_SCENE = "scene";
 var StaticTVClient = class {
@@ -3688,17 +3689,7 @@ var StaticTVClient = class {
     if (screen !== void 0) {
       this.log(`Playing video: ${url}`);
       this._currentVideoUrl = url;
-      if (VideoPlayer.has(screen)) {
-        VideoPlayer.deleteFrom(screen);
-      }
-      VideoPlayer.create(screen, {
-        src: url,
-        playing: true,
-        volume: 1
-      });
-      Material.setBasicMaterial(screen, {
-        texture: Material.Texture.Video({ videoPlayerEntity: screen })
-      });
+      this._playVideoInternal(url, false);
       if (this.guideUI) {
         const videos = this.guideUI.getVideos();
         const video = videos.find((v) => v.src === url);
@@ -3713,22 +3704,55 @@ var StaticTVClient = class {
   }
   /**
    * Stop video playback on the configured videoScreen entity.
+   * If fallbackVideoUrl is configured (default), plays the fallback loop.
    * Called by Admin Panel.
    */
   stopVideo() {
     const screen = this.config.videoScreen;
-    if (screen !== void 0 && VideoPlayer.has(screen)) {
-      this.log("Stopping video");
-      VideoPlayer.getMutable(screen).playing = false;
-      this._currentVideoUrl = "";
+    if (screen !== void 0) {
       if (this.guideUI) {
         this.guideUI.currentVideoId = null;
       }
+      const fallbackUrl = this.config.fallbackVideoUrl;
+      const fallbackDisabled = fallbackUrl === "";
+      if (fallbackDisabled) {
+        if (VideoPlayer.has(screen)) {
+          this.log("Stopping video (no fallback)");
+          VideoPlayer.getMutable(screen).playing = false;
+        }
+        this._currentVideoUrl = "";
+      } else {
+        const url = fallbackUrl || DEFAULT_FALLBACK_VIDEO;
+        this.log(`Playing fallback: ${url}`);
+        this._currentVideoUrl = "";
+        this._playVideoInternal(url, true);
+      }
     }
     if (this.config.onVideoStop) {
       this.config.onVideoStop();
     }
   }
+  /**
+   * Internal video player - handles both regular videos and fallback
+   * @internal
+   */
+  _playVideoInternal(url, isFallback = false) {
+    const screen = this.config.videoScreen;
+    if (screen === void 0) return;
+    if (VideoPlayer.has(screen)) {
+      VideoPlayer.deleteFrom(screen);
+    }
+    VideoPlayer.create(screen, {
+      src: url,
+      playing: true,
+      loop: isFallback,
+      // Loop fallback videos
+      volume: 1
+    });
+    Material.setBasicMaterial(screen, {
+      texture: Material.Texture.Video({ videoPlayerEntity: screen })
+    });
+  }
   /**
    * Get the currently playing video URL
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thestatic-tv/dcl-sdk",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Connect your Decentraland scene to thestatic.tv - full channel lineup, metrics tracking, and interactions",
   "main": "dist/index.js",
   "module": "dist/index.mjs",