@micrio/client 5.4.17 → 5.4.18

package/micrio.min.d.ts

@@ -4,7 +4,7 @@ declare module '@micrio/client' {
 	 * Defines the current version of the Micrio library.
 	 * This constant is used internally and exposed statically via `HTMLMicrioElement.VERSION`.
 	 */
-	export const VERSION = "5.4.17";
+	export const VERSION = "5.4.18";
 	/**
 	 * Loads an image texture asynchronously. Adds the request to the queue
 	 * and returns a Promise that resolves with the TextureBitmap or rejects on error.
@@ -34,6 +34,55 @@ declare module '@micrio/client' {
 		Vimeo = 2
 	}
 	export { isLegacyViews };
+	/**
+	 * Media utilities for source parsing, type detection, and player management.
+	 * @author Marcel Duin <marcel@micr.io>
+	 */
+	/** YouTube no-cookies host */
+	export const YOUTUBE_HOST = "https://www.youtube-nocookie.com";
+	/**
+	 * Parsed media source information.
+	 */
+	export interface ParsedMediaSource {
+		/** The detected media type */
+		type: MediaType;
+		/** The frame type for iframe embeds (YouTube/Vimeo) */
+		frameType?: FrameType;
+		/** The normalized/processed source URL */
+		src?: string;
+		/** Original source URL */
+		originalSrc?: string;
+		/** YouTube video ID (if applicable) */
+		youtubeId?: string;
+		/** Vimeo video ID (if applicable) */
+		vimeoId?: string;
+		/** Vimeo hash token (if applicable) */
+		vimeoToken?: string;
+		/** Cloudflare video ID (if applicable) */
+		cloudflareId?: string;
+		/** Micrio embed data [id, width?, height?, lang?] */
+		micrioEmbed?: string[];
+		/** Start time extracted from URL (seconds) */
+		startTime?: number;
+		/** Whether the source is a Cloudflare stream */
+		isCloudflare: boolean;
+		/** M3U8 URL for HLS streams */
+		hlsSrc?: string;
+	}
+	/**
+	 * Parses a media source URL and determines its type and configuration.
+	 */
+	export function parseMediaSource(src: string | undefined, tour: Models.ImageData.VideoTour | null, useNativeFrames?: boolean, currentTime?: number): ParsedMediaSource;
+	/**
+	 * Checks if the browser natively supports HLS playback.
+	 */
+	export function hasNativeHLS(el?: HTMLMediaElement): boolean;
+	/**
+	 * Returns a shared Audio element instance for iOS.
+	 * This is a workaround for iOS audio playback restrictions where user
+	 * interaction is required per audio element.
+	 */
+	export function getIOSAudioElement(): HTMLAudioElement;
 	/**
 	 * Global utility functions used throughout the Micrio application.
 	 * Re-exports all utility modules for convenient importing.
@@ -52,7 +101,8 @@ declare module '@micrio/client' {
 	export { loadSerialTour } from "ts/utils/tour";
 	export { getIdVal, idIsV5 } from "ts/utils/id";
 	export { getSpaceVector } from "ts/utils/space";
-	export { hasNativeHLS } from "ts/utils/media";
+	export { hasNativeHLS, parseMediaSource, getIOSAudioElement, YOUTUBE_HOST } from "ts/utils/media";
+	export type { ParsedMediaSource } from "ts/utils/media";
 	/**
 	 * Global utility functions used throughout the Micrio application.
 	 * This file re-exports all utilities from the modular utils/ directory.
@@ -2952,6 +3002,176 @@ declare module '@micrio/client' {
 		/** Cleans up resources when the parent Embed component is unmounted. */
 		unmount(): void;
 	}
+	/**
+	 * Media player type definitions and interfaces.
+	 * @author Marcel Duin <marcel@micr.io>
+	 */
+	/**
+	 * Common interface for all media player adapters.
+	 * Abstracts the differences between HTML5, YouTube, Vimeo, and HLS players.
+	 */
+	export interface MediaPlayerAdapter {
+		/** Play the media */
+		play(): Promise<void>;
+		/** Pause the media */
+		pause(): void;
+		/** Get current playback time in seconds */
+		getCurrentTime(): Promise<number>;
+		/** Set current playback time in seconds */
+		setCurrentTime(time: number): void;
+		/** Get total duration in seconds */
+		getDuration(): Promise<number>;
+		/** Check if media is currently paused */
+		isPaused(): Promise<boolean>;
+		/** Set muted state */
+		setMuted(muted: boolean): void;
+		/** Set volume (0-1) */
+		setVolume(volume: number): void;
+		/** Clean up resources */
+		destroy(): void;
+		/** Whether this adapter requires manual time updates via interval */
+		readonly requiresTimeTick: boolean;
+	}
+	/**
+	 * Event callbacks for player state changes.
+	 */
+	export interface PlayerEventCallbacks {
+		onPlay?: () => void;
+		onPause?: () => void;
+		onEnded?: () => void;
+		onSeeking?: () => void;
+		onSeeked?: () => void;
+		onTimeUpdate?: (time: number) => void;
+		onDurationChange?: (duration: number) => void;
+		onError?: (error: Error) => void;
+		onBuffering?: () => void;
+		onReady?: () => void;
+		onBlocked?: () => void;
+	}
+	/**
+	 * Configuration for creating a player adapter.
+	 */
+	export interface PlayerConfig {
+		width: number;
+		height: number;
+		autoplay?: boolean;
+		loop?: boolean;
+		muted?: boolean;
+		volume?: number;
+		startTime?: number;
+	}
+	/**
+	 * HTML5 Media Element adapter.
+	 * Wraps native <audio> and <video> elements with a common interface.
+	 * @author Marcel Duin <marcel@micr.io>
+	 */
+	/**
+	 * Adapter for native HTML5 audio/video elements.
+	 */
+	export class HTML5PlayerAdapter implements MediaPlayerAdapter {
+		private element;
+		private callbacks;
+		readonly requiresTimeTick = false;
+		constructor(element: HTMLMediaElement, callbacks?: PlayerEventCallbacks);
+		private attachEventListeners;
+		play(): Promise<void>;
+		pause(): void;
+		getCurrentTime(): Promise<number>;
+		setCurrentTime(time: number): void;
+		getDuration(): Promise<number>;
+		isPaused(): Promise<boolean>;
+		setMuted(muted: boolean): void;
+		setVolume(volume: number): void;
+		destroy(): void;
+	}
+	/**
+	 * Adapter for HLS.js streaming video.
+	 * Extends HTML5PlayerAdapter since HLS.js attaches to a video element.
+	 */
+	export class HLSPlayerAdapter implements MediaPlayerAdapter {
+		private element;
+		private hlsSrc;
+		private callbacks;
+		readonly requiresTimeTick = false;
+		private hls;
+		private html5Adapter;
+		private destroyed;
+		constructor(element: HTMLVideoElement, hlsSrc: string, callbacks?: PlayerEventCallbacks);
+		/**
+		 * Loads HLS.js and attaches to the video element.
+		 */
+		initialize(): Promise<void>;
+		play(): Promise<void>;
+		pause(): void;
+		getCurrentTime(): Promise<number>;
+		setCurrentTime(time: number): void;
+		getDuration(): Promise<number>;
+		isPaused(): Promise<boolean>;
+		setMuted(muted: boolean): void;
+		setVolume(volume: number): void;
+		destroy(): void;
+	}
+	/**
+	 * Adapter for YouTube IFrame Player API.
+	 */
+	export class YouTubePlayerAdapter implements MediaPlayerAdapter {
+		private frame;
+		private config;
+		private callbacks;
+		readonly requiresTimeTick = true;
+		private player;
+		private destroyed;
+		constructor(frame: HTMLIFrameElement, config: PlayerConfig, callbacks?: PlayerEventCallbacks);
+		/**
+		 * Loads the YouTube API and initializes the player.
+		 */
+		initialize(): Promise<void>;
+		private handleStateChange;
+		play(): Promise<void>;
+		pause(): void;
+		getCurrentTime(): Promise<number>;
+		setCurrentTime(time: number): void;
+		getDuration(): Promise<number>;
+		isPaused(): Promise<boolean>;
+		setMuted(muted: boolean): void;
+		setVolume(_volume: number): void;
+		destroy(): void;
+	}
+	/**
+	 * Adapter for Vimeo Player API.
+	 */
+	export class VimeoPlayerAdapter implements MediaPlayerAdapter {
+		private frame;
+		private config;
+		private callbacks;
+		readonly requiresTimeTick = false;
+		private player;
+		private destroyed;
+		constructor(frame: HTMLIFrameElement, config: PlayerConfig, callbacks?: PlayerEventCallbacks);
+		/**
+		 * Loads the Vimeo API and initializes the player.
+		 */
+		initialize(): Promise<void>;
+		play(): Promise<void>;
+		pause(): void;
+		getCurrentTime(): Promise<number>;
+		setCurrentTime(time: number): void;
+		getDuration(): Promise<number>;
+		isPaused(): Promise<boolean>;
+		setMuted(muted: boolean): void;
+		setVolume(volume: number): void;
+		destroy(): void;
+	}
+	/**
+	 * Media player adapters module.
+	 * Provides unified interfaces for different media player types.
+	 * @author Marcel Duin <marcel@micr.io>
+	 */
+	export type { MediaPlayerAdapter, PlayerEventCallbacks, PlayerConfig } from "ts/media/types";
+	export { HTML5PlayerAdapter } from "ts/media/html5-adapter";
+	export { YouTubePlayerAdapter } from "ts/media/youtube-adapter";
+	export { VimeoPlayerAdapter } from "ts/media/vimeo-adapter";
+	export { HLSPlayerAdapter } from "ts/media/hls-adapter";
 }declare module "svelte/store" {
 	/** Callback to inform of a value updates.
 	*/