move.gl 0.0.1 → 0.0.2

package/src/ts/Screensaver.ts

@@ -0,0 +1,192 @@
+// ============================================================================
+// move.gl | Screensaver
+// ============================================================================
+// Copyright 2025 Scape Agency BV
+// Licensed under MIT License
+// ============================================================================
+
+/**
+ * Screensaver Configuration Options
+ */
+export interface ScreensaverOptions {
+    /** Inactivity timeout in milliseconds */
+    timeout: number;
+    /** URL for the video to play */
+    videoUrl?: string;
+    /** URL for the audio to play */
+    audioUrl?: string;
+    /** ID of the screensaver container element */
+    containerId?: string;
+    /** ID of the video element */
+    videoId?: string;
+    /** ID of the audio element */
+    audioId?: string;
+}
+
+/**
+ * Screensaver Class
+ *
+ * Handles the activation and deactivation of a screensaver based on
+ * user inactivity. Provides methods to start and stop the screensaver,
+ * manage media sources, and handle user interactions.
+ *
+ * @example
+ * ```typescript
+ * const screensaver = new Screensaver({
+ *     timeout: 300000, // 5 minutes
+ *     videoUrl: 'path/to/video.mp4',
+ *     audioUrl: 'path/to/audio.mp3'
+ * });
+ * screensaver.setVolume(0.5);
+ * ```
+ */
+export class Screensaver {
+    private timeoutId: number | undefined;
+    private readonly timeout: number;
+    private screensaverElement: HTMLElement | null = null;
+    private videoElement: HTMLVideoElement | null = null;
+    private audioElement: HTMLAudioElement | null = null;
+    private isActive: boolean = false;
+    private readonly options: ScreensaverOptions;
+
+    /**
+     * Creates a new Screensaver instance.
+     * @param options - Configuration options for the screensaver.
+     */
+    constructor(options: ScreensaverOptions) {
+        this.options = {
+            containerId: 'screensaver',
+            videoId: 'screensaverVideo',
+            audioId: 'screensaverAudio',
+            ...options
+        };
+        this.timeout = options.timeout;
+        this.initializeElements();
+        if (options.videoUrl && options.audioUrl) {
+            this.loadMedia(options.videoUrl, options.audioUrl);
+        }
+        this.setupEventListeners();
+        this.startScreensaverTimeout();
+    }
+
+    /**
+     * Initializes HTML elements from the DOM.
+     */
+    private initializeElements(): void {
+        this.screensaverElement = document.getElementById(this.options.containerId!);
+        this.videoElement = document.getElementById(this.options.videoId!) as HTMLVideoElement | null;
+        this.audioElement = document.getElementById(this.options.audioId!) as HTMLAudioElement | null;
+    }
+
+    /**
+     * Loads media sources into the video and audio elements.
+     * @param videoUrl - The source URL of the video.
+     * @param audioUrl - The source URL of the audio.
+     */
+    private loadMedia(videoUrl: string, audioUrl: string): void {
+        if (this.videoElement) {
+            this.videoElement.src = videoUrl;
+        }
+        if (this.audioElement) {
+            this.audioElement.src = audioUrl;
+        }
+    }
+
+    /**
+     * @notice Sets up event listeners for user interaction to prevent
+     * screensaver activation.
+     * @dev Listens for 'mousemove', 'keydown', and 'touchstart' events
+     * to reset the screensaver timer.
+     */
+    private setupEventListeners() {
+        ['mousemove', 'keydown', 'touchstart'].forEach(event => {
+            document.addEventListener(event, this.resetScreensaver);
+        });
+    }
+
+    /**
+     * @notice Starts or restarts the screensaver timeout.
+     * @dev Resets any existing timeout and sets a new timeout to activate
+     * the screensaver.
+     */
+    private startScreensaverTimeout() {
+        this.stopScreensaver(); // Stop existing screensaver if active
+        this.timeoutId = window.setTimeout(
+            () => this.activateScreensaver(), this.timeout
+        );
+    }
+
+    /**
+     * @notice Resets the screensaver timer and stops the screensaver if
+     * active.
+     * @dev Called upon user interactions detected by event listeners.
+     */
+    private resetScreensaver = () => {
+        if (this.isActive) {
+            this.stopScreensaver();
+        }
+        this.startScreensaverTimeout();
+    };
+
+    /**
+     * Activates the screensaver, displaying elements and playing media.
+     */
+    private activateScreensaver = (): void => {
+        if (this.screensaverElement) {
+            this.screensaverElement.style.display = 'block';
+        }
+        this.videoElement?.play();
+        this.audioElement?.play();
+        this.isActive = true;
+    };
+
+    /**
+     * Stops the screensaver and hides its elements.
+     */
+    public stopScreensaver(): void {
+        if (this.screensaverElement) {
+            this.screensaverElement.style.display = 'none';
+        }
+        this.videoElement?.pause();
+        this.audioElement?.pause();
+        this.isActive = false;
+
+        if (this.timeoutId !== undefined) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = undefined;
+        }
+    }
+
+    /**
+     * Sets the volume for both video and audio elements.
+     * @param volume - A number between 0.0 and 1.0 indicating the volume level.
+     */
+    public setVolume(volume: number): void {
+        const clampedVolume = Math.max(0, Math.min(1, volume));
+        if (this.videoElement) {
+            this.videoElement.volume = clampedVolume;
+        }
+        if (this.audioElement) {
+            this.audioElement.volume = clampedVolume;
+        }
+    }
+
+    /**
+     * Returns whether the screensaver is currently active.
+     */
+    public getIsActive(): boolean {
+        return this.isActive;
+    }
+
+    /**
+     * Cleans up event listeners and stops the screensaver.
+     */
+    public destroy(): void {
+        this.stopScreensaver();
+        ['mousemove', 'keydown', 'touchstart'].forEach(event => {
+            document.removeEventListener(event, this.resetScreensaver);
+        });
+    }
+}
+
+export default Screensaver;

package/src/ts/VideoOverlay.ts

@@ -0,0 +1,205 @@
+// ============================================================================
+// move.gl | Video Overlay
+// ============================================================================
+// Copyright 2025 Scape Agency BV
+// Licensed under MIT License
+// ============================================================================
+
+/**
+ * Video overlay options
+ */
+export interface VideoOverlayOptions {
+    /** Fade transition duration in milliseconds */
+    fadeTransitionDuration?: number;
+    /** Whether to loop the video */
+    loop?: boolean;
+    /** Initial video source URL */
+    initialSource?: string;
+}
+
+/**
+ * Transparent Video Overlay Handler
+ *
+ * Manages a transparent video overlay, controlling its visibility,
+ * playback, and effects.
+ *
+ * @example
+ * ```typescript
+ * const overlay = new TransparentVideoOverlay('myVideo', {
+ *     fadeTransitionDuration: 500,
+ *     loop: true
+ * });
+ * overlay.showOverlay();
+ * ```
+ */
+export class TransparentVideoOverlay {
+    private videoElement: HTMLVideoElement | null = null;
+    private isVisible: boolean = false;
+    private fadeTransitionDuration: number;
+    private loop: boolean;
+
+    /**
+     * Creates a new TransparentVideoOverlay instance.
+     * @param videoElementId - The ID of the video element to manage.
+     * @param options - Optional configuration options.
+     */
+    constructor(videoElementId: string, options: VideoOverlayOptions = {}) {
+        const element = document.getElementById(videoElementId);
+        if (element instanceof HTMLVideoElement) {
+            this.videoElement = element;
+        } else {
+            console.warn(`Element with id "${videoElementId}" is not a video element`);
+        }
+
+        this.fadeTransitionDuration = options.fadeTransitionDuration ?? 500;
+        this.loop = options.loop ?? true;
+
+        if (this.videoElement) {
+            this.setupVideo();
+            if (options.initialSource) {
+                this.changeVideoSource(options.initialSource, false);
+            }
+        }
+    }
+
+    /**
+     * Initializes video settings and event listeners.
+     */
+    private setupVideo(): void {
+        if (!this.videoElement) return;
+
+        if (this.loop) {
+            this.videoElement.addEventListener('ended', () => {
+                this.videoElement?.play();
+            });
+        }
+
+        this.videoElement.addEventListener('loadeddata', () => {
+            console.log('Video loaded successfully.');
+        });
+
+        this.videoElement.addEventListener('error', (e) => {
+            console.error('Error loading video:', e);
+        });
+
+        // Set initial style for smooth transitions
+        this.videoElement.style.transition = `opacity ${this.fadeTransitionDuration}ms ease`;
+    }
+
+    /**
+     * Shows the video overlay with a fade-in effect.
+     */
+    public showOverlay(): void {
+        if (!this.videoElement) return;
+
+        this.videoElement.style.display = 'block';
+        this.videoElement.style.opacity = '0';
+
+        // Use requestAnimationFrame for smoother transition
+        requestAnimationFrame(() => {
+            if (this.videoElement) {
+                this.videoElement.style.opacity = '1';
+                this.videoElement.play().catch(err => {
+                    console.warn('Auto-play prevented:', err);
+                });
+            }
+        });
+
+        this.isVisible = true;
+    }
+
+    /**
+     * Hides the video overlay with a fade-out effect.
+     */
+    public hideOverlay(): void {
+        if (!this.videoElement) return;
+
+        this.videoElement.style.opacity = '0';
+
+        setTimeout(() => {
+            if (this.videoElement) {
+                this.videoElement.style.display = 'none';
+                this.videoElement.pause();
+            }
+        }, this.fadeTransitionDuration);
+
+        this.isVisible = false;
+    }
+
+    /**
+     * Toggles the visibility of the video overlay.
+     */
+    public toggleOverlay(): void {
+        if (this.isVisible) {
+            this.hideOverlay();
+        } else {
+            this.showOverlay();
+        }
+    }
+
+    /**
+     * Changes the video source and optionally plays it immediately.
+     * @param videoUrl - The URL of the new video source.
+     * @param autoPlay - Whether the video should play immediately after loading.
+     */
+    public changeVideoSource(videoUrl: string, autoPlay: boolean = true): void {
+        if (!this.videoElement) return;
+
+        this.videoElement.src = videoUrl;
+        this.videoElement.load();
+
+        if (autoPlay) {
+            this.showOverlay();
+        }
+    }
+
+    /**
+     * Gets the visibility state of the overlay.
+     */
+    public getIsVisible(): boolean {
+        return this.isVisible;
+    }
+
+    /**
+     * Cleans up the video overlay instance.
+     */
+    public destroy(): void {
+        if (this.videoElement) {
+            this.videoElement.pause();
+            this.videoElement.src = '';
+            this.videoElement = null;
+        }
+    }
+}
+
+/**
+ * Checks if the browser supports HEVC alpha channel videos.
+ * This is primarily supported in Safari.
+ * @returns Whether HEVC alpha is supported.
+ */
+export function supportsHEVCAlpha(): boolean {
+    const navigator = window.navigator;
+    const ua = navigator.userAgent.toLowerCase();
+    const hasMediaCapabilities = !!(
+        navigator.mediaCapabilities &&
+        navigator.mediaCapabilities.decodingInfo
+    );
+    const isSafari = (
+        ua.indexOf('safari') !== -1 &&
+        ua.indexOf('chrome') === -1 &&
+        ua.indexOf('version/') !== -1
+    );
+    return isSafari && hasMediaCapabilities;
+}
+
+/**
+ * Gets the appropriate video source based on browser support.
+ * @param hevcSource - The HEVC/MOV source for Safari.
+ * @param webmSource - The WebM source for other browsers.
+ * @returns The appropriate video source URL.
+ */
+export function getOptimalVideoSource(hevcSource: string, webmSource: string): string {
+    return supportsHEVCAlpha() ? hevcSource : webmSource;
+}
+
+export default TransparentVideoOverlay;