@scarlett-player/media-session 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hackney Enterprises Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,289 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createMediaSessionPlugin: () => createMediaSessionPlugin,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_CONFIG = {
+  enablePlayPause: true,
+  enableSeek: true,
+  enableTrackNavigation: true,
+  seekOffset: 10,
+  updatePositionState: true
+};
+function isMediaSessionSupported() {
+  return typeof navigator !== "undefined" && "mediaSession" in navigator;
+}
+function createMediaSessionPlugin(config) {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  let api = null;
+  let currentMetadata = {};
+  const updateMetadata = () => {
+    if (!isMediaSessionSupported()) return;
+    const artwork = [];
+    const artworkSources = currentMetadata.artwork || mergedConfig.defaultArtwork || [];
+    for (const art of artworkSources) {
+      artwork.push({
+        src: art.src,
+        sizes: art.sizes || "512x512",
+        type: art.type || "image/png"
+      });
+    }
+    try {
+      navigator.mediaSession.metadata = new MediaMetadata({
+        title: currentMetadata.title || "Unknown",
+        artist: currentMetadata.artist || "",
+        album: currentMetadata.album || "",
+        artwork
+      });
+    } catch (e) {
+      api?.logger.warn("Failed to set media session metadata", e);
+    }
+  };
+  const updatePositionState = () => {
+    if (!isMediaSessionSupported() || !mergedConfig.updatePositionState) return;
+    const duration = api?.getState("duration") || 0;
+    const position = api?.getState("currentTime") || 0;
+    const playbackRate = api?.getState("playbackRate") || 1;
+    if (duration > 0 && isFinite(duration)) {
+      try {
+        navigator.mediaSession.setPositionState({
+          duration,
+          position: Math.min(position, duration),
+          playbackRate
+        });
+      } catch (e) {
+        api?.logger.debug("Failed to set position state", e);
+      }
+    }
+  };
+  const setupActionHandlers = () => {
+    if (!isMediaSessionSupported()) return;
+    const seekOffset = mergedConfig.seekOffset || 10;
+    if (mergedConfig.enablePlayPause) {
+      try {
+        navigator.mediaSession.setActionHandler("play", () => {
+          api?.logger.debug("Media session: play");
+          api?.emit("playback:play", void 0);
+        });
+        navigator.mediaSession.setActionHandler("pause", () => {
+          api?.logger.debug("Media session: pause");
+          api?.emit("playback:pause", void 0);
+        });
+        navigator.mediaSession.setActionHandler("stop", () => {
+          api?.logger.debug("Media session: stop");
+          api?.emit("playback:pause", void 0);
+          api?.emit("playback:seeking", { time: 0 });
+        });
+      } catch (e) {
+        api?.logger.debug("Some play/pause actions not supported", e);
+      }
+    }
+    if (mergedConfig.enableSeek) {
+      try {
+        navigator.mediaSession.setActionHandler("seekbackward", (details) => {
+          const offset = details.seekOffset || seekOffset;
+          const currentTime = api?.getState("currentTime") || 0;
+          const newTime = Math.max(0, currentTime - offset);
+          api?.logger.debug("Media session: seekbackward", { offset, newTime });
+          api?.emit("playback:seeking", { time: newTime });
+        });
+        navigator.mediaSession.setActionHandler("seekforward", (details) => {
+          const offset = details.seekOffset || seekOffset;
+          const currentTime = api?.getState("currentTime") || 0;
+          const duration = api?.getState("duration") || 0;
+          const newTime = Math.min(duration, currentTime + offset);
+          api?.logger.debug("Media session: seekforward", { offset, newTime });
+          api?.emit("playback:seeking", { time: newTime });
+        });
+        navigator.mediaSession.setActionHandler("seekto", (details) => {
+          if (details.seekTime !== void 0) {
+            api?.logger.debug("Media session: seekto", { time: details.seekTime });
+            api?.emit("playback:seeking", { time: details.seekTime });
+          }
+        });
+      } catch (e) {
+        api?.logger.debug("Some seek actions not supported", e);
+      }
+    }
+    if (mergedConfig.enableTrackNavigation) {
+      try {
+        navigator.mediaSession.setActionHandler("previoustrack", () => {
+          api?.logger.debug("Media session: previoustrack");
+          const playlist = api?.getPlugin("playlist");
+          if (playlist) {
+            playlist.previous();
+          } else {
+            api?.emit("playback:seeking", { time: 0 });
+          }
+        });
+        navigator.mediaSession.setActionHandler("nexttrack", () => {
+          api?.logger.debug("Media session: nexttrack");
+          const playlist = api?.getPlugin("playlist");
+          if (playlist) {
+            playlist.next();
+          }
+        });
+      } catch (e) {
+        api?.logger.debug("Track navigation not supported", e);
+      }
+    }
+  };
+  const clearActionHandlers = () => {
+    if (!isMediaSessionSupported()) return;
+    const actions = [
+      "play",
+      "pause",
+      "stop",
+      "seekbackward",
+      "seekforward",
+      "seekto",
+      "previoustrack",
+      "nexttrack"
+    ];
+    for (const action of actions) {
+      try {
+        navigator.mediaSession.setActionHandler(action, null);
+      } catch (e) {
+      }
+    }
+  };
+  const plugin = {
+    id: "media-session",
+    name: "Media Session",
+    version: "1.0.0",
+    type: "feature",
+    description: "Media Session API integration for system-level media controls",
+    async init(pluginApi) {
+      api = pluginApi;
+      if (!isMediaSessionSupported()) {
+        api.logger.info("Media Session API not supported in this browser");
+        return;
+      }
+      api.logger.info("Media Session plugin initialized");
+      setupActionHandlers();
+      const unsubPlay = api.on("playback:play", () => {
+        if (isMediaSessionSupported()) {
+          navigator.mediaSession.playbackState = "playing";
+        }
+      });
+      const unsubPause = api.on("playback:pause", () => {
+        if (isMediaSessionSupported()) {
+          navigator.mediaSession.playbackState = "paused";
+        }
+      });
+      const unsubEnded = api.on("playback:ended", () => {
+        if (isMediaSessionSupported()) {
+          navigator.mediaSession.playbackState = "none";
+        }
+      });
+      let lastPositionUpdate = 0;
+      const unsubTimeUpdate = api.on("playback:timeupdate", () => {
+        const now = Date.now();
+        if (now - lastPositionUpdate >= 1e3) {
+          lastPositionUpdate = now;
+          updatePositionState();
+        }
+      });
+      const unsubMetadata = api.on("media:loadedmetadata", () => {
+        updatePositionState();
+      });
+      const unsubState = api.subscribeToState((event) => {
+        if (event.key === "title" && typeof event.value === "string") {
+          currentMetadata.title = event.value;
+          updateMetadata();
+        } else if (event.key === "poster" && typeof event.value === "string") {
+          currentMetadata.artwork = [{ src: event.value, sizes: "512x512" }];
+          updateMetadata();
+        }
+      });
+      const unsubPlaylist = api.on("playlist:change", (payload) => {
+        if (payload?.track) {
+          const track = payload.track;
+          currentMetadata = {
+            title: track.title,
+            artist: track.artist,
+            album: track.album,
+            artwork: track.artwork ? [{ src: track.artwork, sizes: "512x512" }] : void 0
+          };
+          updateMetadata();
+        }
+      });
+      api.onDestroy(() => {
+        unsubPlay();
+        unsubPause();
+        unsubEnded();
+        unsubTimeUpdate();
+        unsubMetadata();
+        unsubState();
+        unsubPlaylist();
+        clearActionHandlers();
+      });
+    },
+    async destroy() {
+      api?.logger.info("Media Session plugin destroying");
+      clearActionHandlers();
+      if (isMediaSessionSupported()) {
+        navigator.mediaSession.metadata = null;
+        navigator.mediaSession.playbackState = "none";
+      }
+      api = null;
+    },
+    isSupported() {
+      return isMediaSessionSupported();
+    },
+    setMetadata(metadata) {
+      currentMetadata = { ...currentMetadata, ...metadata };
+      updateMetadata();
+    },
+    setPlaybackState(state) {
+      if (isMediaSessionSupported()) {
+        navigator.mediaSession.playbackState = state;
+      }
+    },
+    setPositionState(state) {
+      if (isMediaSessionSupported()) {
+        try {
+          navigator.mediaSession.setPositionState(state);
+        } catch (e) {
+          api?.logger.debug("Failed to set position state", e);
+        }
+      }
+    },
+    setActionHandler(action, handler) {
+      if (isMediaSessionSupported()) {
+        try {
+          navigator.mediaSession.setActionHandler(action, handler);
+        } catch (e) {
+          api?.logger.debug(`Action ${action} not supported`, e);
+        }
+      }
+    }
+  };
+  return plugin;
+}
+var index_default = createMediaSessionPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createMediaSessionPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,142 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * Media Session Plugin Types
+ */
+
+/**
+ * Media metadata for the session
+ */
+interface MediaSessionMetadata {
+    /** Track/video title */
+    title?: string;
+    /** Artist name */
+    artist?: string;
+    /** Album name */
+    album?: string;
+    /** Artwork URLs (multiple sizes for different displays) */
+    artwork?: MediaSessionArtwork[];
+}
+/**
+ * Artwork definition
+ */
+interface MediaSessionArtwork {
+    /** Image URL */
+    src: string;
+    /** Image size (e.g., '96x96', '256x256', '512x512') */
+    sizes?: string;
+    /** MIME type */
+    type?: string;
+}
+/**
+ * Media session action handlers
+ */
+interface MediaSessionActions {
+    /** Play action */
+    play?: () => void;
+    /** Pause action */
+    pause?: () => void;
+    /** Stop action */
+    stop?: () => void;
+    /** Seek backward action */
+    seekbackward?: (details: {
+        seekOffset?: number;
+    }) => void;
+    /** Seek forward action */
+    seekforward?: (details: {
+        seekOffset?: number;
+    }) => void;
+    /** Seek to position action */
+    seekto?: (details: {
+        seekTime: number;
+        fastSeek?: boolean;
+    }) => void;
+    /** Previous track action */
+    previoustrack?: () => void;
+    /** Next track action */
+    nexttrack?: () => void;
+}
+/**
+ * Media session plugin configuration
+ */
+interface MediaSessionPluginConfig {
+    /** Enable play/pause actions (default: true) */
+    enablePlayPause?: boolean;
+    /** Enable seek actions (default: true) */
+    enableSeek?: boolean;
+    /** Enable previous/next track actions (default: true) */
+    enableTrackNavigation?: boolean;
+    /** Seek offset in seconds for seekbackward/seekforward (default: 10) */
+    seekOffset?: number;
+    /** Default artwork to use when none provided */
+    defaultArtwork?: MediaSessionArtwork[];
+    /** Update position state on timeupdate (default: true) */
+    updatePositionState?: boolean;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Media session plugin interface
+ */
+interface IMediaSessionPlugin extends Plugin<MediaSessionPluginConfig> {
+    /**
+     * Check if Media Session API is supported
+     */
+    isSupported(): boolean;
+    /**
+     * Update media metadata
+     */
+    setMetadata(metadata: MediaSessionMetadata): void;
+    /**
+     * Update playback state
+     */
+    setPlaybackState(state: 'none' | 'paused' | 'playing'): void;
+    /**
+     * Update position state (for seek bar in system UI)
+     */
+    setPositionState(state: {
+        duration: number;
+        position: number;
+        playbackRate: number;
+    }): void;
+    /**
+     * Set a custom action handler
+     */
+    setActionHandler(action: keyof MediaSessionActions, handler: (() => void) | null): void;
+}
+
+/**
+ * Media Session Plugin for Scarlett Player
+ *
+ * Integrates with the browser's Media Session API for:
+ * - Lock screen controls on mobile devices
+ * - Notification center playback controls
+ * - Hardware media key support (keyboard play/pause/next/prev)
+ * - Album art and track info in system media UI
+ * - Seek bar with position state
+ */
+
+/**
+ * Create a Media Session Plugin instance.
+ *
+ * @param config - Plugin configuration
+ * @returns Media Session Plugin instance
+ *
+ * @example
+ * ```ts
+ * import { createMediaSessionPlugin } from '@scarlett-player/media-session';
+ *
+ * const player = new ScarlettPlayer({
+ *   container: document.getElementById('player'),
+ *   plugins: [
+ *     createMediaSessionPlugin({
+ *       seekOffset: 15,
+ *       defaultArtwork: [{ src: '/default-artwork.png', sizes: '512x512' }],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function createMediaSessionPlugin(config?: Partial<MediaSessionPluginConfig>): IMediaSessionPlugin;
+
+export { type IMediaSessionPlugin, type MediaSessionArtwork, type MediaSessionMetadata, type MediaSessionPluginConfig, createMediaSessionPlugin, createMediaSessionPlugin as default };

package/dist/index.d.ts

@@ -0,0 +1,142 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * Media Session Plugin Types
+ */
+
+/**
+ * Media metadata for the session
+ */
+interface MediaSessionMetadata {
+    /** Track/video title */
+    title?: string;
+    /** Artist name */
+    artist?: string;
+    /** Album name */
+    album?: string;
+    /** Artwork URLs (multiple sizes for different displays) */
+    artwork?: MediaSessionArtwork[];
+}
+/**
+ * Artwork definition
+ */
+interface MediaSessionArtwork {
+    /** Image URL */
+    src: string;
+    /** Image size (e.g., '96x96', '256x256', '512x512') */
+    sizes?: string;
+    /** MIME type */
+    type?: string;
+}
+/**
+ * Media session action handlers
+ */
+interface MediaSessionActions {
+    /** Play action */
+    play?: () => void;
+    /** Pause action */
+    pause?: () => void;
+    /** Stop action */
+    stop?: () => void;
+    /** Seek backward action */
+    seekbackward?: (details: {
+        seekOffset?: number;
+    }) => void;
+    /** Seek forward action */
+    seekforward?: (details: {
+        seekOffset?: number;
+    }) => void;
+    /** Seek to position action */
+    seekto?: (details: {
+        seekTime: number;
+        fastSeek?: boolean;
+    }) => void;
+    /** Previous track action */
+    previoustrack?: () => void;
+    /** Next track action */
+    nexttrack?: () => void;
+}
+/**
+ * Media session plugin configuration
+ */
+interface MediaSessionPluginConfig {
+    /** Enable play/pause actions (default: true) */
+    enablePlayPause?: boolean;
+    /** Enable seek actions (default: true) */
+    enableSeek?: boolean;
+    /** Enable previous/next track actions (default: true) */
+    enableTrackNavigation?: boolean;
+    /** Seek offset in seconds for seekbackward/seekforward (default: 10) */
+    seekOffset?: number;
+    /** Default artwork to use when none provided */
+    defaultArtwork?: MediaSessionArtwork[];
+    /** Update position state on timeupdate (default: true) */
+    updatePositionState?: boolean;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Media session plugin interface
+ */
+interface IMediaSessionPlugin extends Plugin<MediaSessionPluginConfig> {
+    /**
+     * Check if Media Session API is supported
+     */
+    isSupported(): boolean;
+    /**
+     * Update media metadata
+     */
+    setMetadata(metadata: MediaSessionMetadata): void;
+    /**
+     * Update playback state
+     */
+    setPlaybackState(state: 'none' | 'paused' | 'playing'): void;
+    /**
+     * Update position state (for seek bar in system UI)
+     */
+    setPositionState(state: {
+        duration: number;
+        position: number;
+        playbackRate: number;
+    }): void;
+    /**
+     * Set a custom action handler
+     */
+    setActionHandler(action: keyof MediaSessionActions, handler: (() => void) | null): void;
+}
+
+/**
+ * Media Session Plugin for Scarlett Player
+ *
+ * Integrates with the browser's Media Session API for:
+ * - Lock screen controls on mobile devices
+ * - Notification center playback controls
+ * - Hardware media key support (keyboard play/pause/next/prev)
+ * - Album art and track info in system media UI
+ * - Seek bar with position state
+ */
+
+/**
+ * Create a Media Session Plugin instance.
+ *
+ * @param config - Plugin configuration
+ * @returns Media Session Plugin instance
+ *
+ * @example
+ * ```ts
+ * import { createMediaSessionPlugin } from '@scarlett-player/media-session';
+ *
+ * const player = new ScarlettPlayer({
+ *   container: document.getElementById('player'),
+ *   plugins: [
+ *     createMediaSessionPlugin({
+ *       seekOffset: 15,
+ *       defaultArtwork: [{ src: '/default-artwork.png', sizes: '512x512' }],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function createMediaSessionPlugin(config?: Partial<MediaSessionPluginConfig>): IMediaSessionPlugin;
+
+export { type IMediaSessionPlugin, type MediaSessionArtwork, type MediaSessionMetadata, type MediaSessionPluginConfig, createMediaSessionPlugin, createMediaSessionPlugin as default };

package/dist/index.js

@@ -0,0 +1,264 @@
+// src/index.ts
+var DEFAULT_CONFIG = {
+  enablePlayPause: true,
+  enableSeek: true,
+  enableTrackNavigation: true,
+  seekOffset: 10,
+  updatePositionState: true
+};
+function isMediaSessionSupported() {
+  return typeof navigator !== "undefined" && "mediaSession" in navigator;
+}
+function createMediaSessionPlugin(config) {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  let api = null;
+  let currentMetadata = {};
+  const updateMetadata = () => {
+    if (!isMediaSessionSupported()) return;
+    const artwork = [];
+    const artworkSources = currentMetadata.artwork || mergedConfig.defaultArtwork || [];
+    for (const art of artworkSources) {
+      artwork.push({
+        src: art.src,
+        sizes: art.sizes || "512x512",
+        type: art.type || "image/png"
+      });
+    }
+    try {
+      navigator.mediaSession.metadata = new MediaMetadata({
+        title: currentMetadata.title || "Unknown",
+        artist: currentMetadata.artist || "",
+        album: currentMetadata.album || "",
+        artwork
+      });
+    } catch (e) {
+      api?.logger.warn("Failed to set media session metadata", e);
+    }
+  };
+  const updatePositionState = () => {
+    if (!isMediaSessionSupported() || !mergedConfig.updatePositionState) return;
+    const duration = api?.getState("duration") || 0;
+    const position = api?.getState("currentTime") || 0;
+    const playbackRate = api?.getState("playbackRate") || 1;
+    if (duration > 0 && isFinite(duration)) {
+      try {
+        navigator.mediaSession.setPositionState({
+          duration,
+          position: Math.min(position, duration),
+          playbackRate
+        });
+      } catch (e) {
+        api?.logger.debug("Failed to set position state", e);
+      }
+    }
+  };
+  const setupActionHandlers = () => {
+    if (!isMediaSessionSupported()) return;
+    const seekOffset = mergedConfig.seekOffset || 10;
+    if (mergedConfig.enablePlayPause) {
+      try {
+        navigator.mediaSession.setActionHandler("play", () => {
+          api?.logger.debug("Media session: play");
+          api?.emit("playback:play", void 0);
+        });
+        navigator.mediaSession.setActionHandler("pause", () => {
+          api?.logger.debug("Media session: pause");
+          api?.emit("playback:pause", void 0);
+        });
+        navigator.mediaSession.setActionHandler("stop", () => {
+          api?.logger.debug("Media session: stop");
+          api?.emit("playback:pause", void 0);
+          api?.emit("playback:seeking", { time: 0 });
+        });
+      } catch (e) {
+        api?.logger.debug("Some play/pause actions not supported", e);
+      }
+    }
+    if (mergedConfig.enableSeek) {
+      try {
+        navigator.mediaSession.setActionHandler("seekbackward", (details) => {
+          const offset = details.seekOffset || seekOffset;
+          const currentTime = api?.getState("currentTime") || 0;
+          const newTime = Math.max(0, currentTime - offset);
+          api?.logger.debug("Media session: seekbackward", { offset, newTime });
+          api?.emit("playback:seeking", { time: newTime });
+        });
+        navigator.mediaSession.setActionHandler("seekforward", (details) => {
+          const offset = details.seekOffset || seekOffset;
+          const currentTime = api?.getState("currentTime") || 0;
+          const duration = api?.getState("duration") || 0;
+          const newTime = Math.min(duration, currentTime + offset);
+          api?.logger.debug("Media session: seekforward", { offset, newTime });
+          api?.emit("playback:seeking", { time: newTime });
+        });
+        navigator.mediaSession.setActionHandler("seekto", (details) => {
+          if (details.seekTime !== void 0) {
+            api?.logger.debug("Media session: seekto", { time: details.seekTime });
+            api?.emit("playback:seeking", { time: details.seekTime });
+          }
+        });
+      } catch (e) {
+        api?.logger.debug("Some seek actions not supported", e);
+      }
+    }
+    if (mergedConfig.enableTrackNavigation) {
+      try {
+        navigator.mediaSession.setActionHandler("previoustrack", () => {
+          api?.logger.debug("Media session: previoustrack");
+          const playlist = api?.getPlugin("playlist");
+          if (playlist) {
+            playlist.previous();
+          } else {
+            api?.emit("playback:seeking", { time: 0 });
+          }
+        });
+        navigator.mediaSession.setActionHandler("nexttrack", () => {
+          api?.logger.debug("Media session: nexttrack");
+          const playlist = api?.getPlugin("playlist");
+          if (playlist) {
+            playlist.next();
+          }
+        });
+      } catch (e) {
+        api?.logger.debug("Track navigation not supported", e);
+      }
+    }
+  };
+  const clearActionHandlers = () => {
+    if (!isMediaSessionSupported()) return;
+    const actions = [
+      "play",
+      "pause",
+      "stop",
+      "seekbackward",
+      "seekforward",
+      "seekto",
+      "previoustrack",
+      "nexttrack"
+    ];
+    for (const action of actions) {
+      try {
+        navigator.mediaSession.setActionHandler(action, null);
+      } catch (e) {
+      }
+    }
+  };
+  const plugin = {
+    id: "media-session",
+    name: "Media Session",
+    version: "1.0.0",
+    type: "feature",
+    description: "Media Session API integration for system-level media controls",
+    async init(pluginApi) {
+      api = pluginApi;
+      if (!isMediaSessionSupported()) {
+        api.logger.info("Media Session API not supported in this browser");
+        return;
+      }
+      api.logger.info("Media Session plugin initialized");
+      setupActionHandlers();
+      const unsubPlay = api.on("playback:play", () => {
+        if (isMediaSessionSupported()) {
+          navigator.mediaSession.playbackState = "playing";
+        }
+      });
+      const unsubPause = api.on("playback:pause", () => {
+        if (isMediaSessionSupported()) {
+          navigator.mediaSession.playbackState = "paused";
+        }
+      });
+      const unsubEnded = api.on("playback:ended", () => {
+        if (isMediaSessionSupported()) {
+          navigator.mediaSession.playbackState = "none";
+        }
+      });
+      let lastPositionUpdate = 0;
+      const unsubTimeUpdate = api.on("playback:timeupdate", () => {
+        const now = Date.now();
+        if (now - lastPositionUpdate >= 1e3) {
+          lastPositionUpdate = now;
+          updatePositionState();
+        }
+      });
+      const unsubMetadata = api.on("media:loadedmetadata", () => {
+        updatePositionState();
+      });
+      const unsubState = api.subscribeToState((event) => {
+        if (event.key === "title" && typeof event.value === "string") {
+          currentMetadata.title = event.value;
+          updateMetadata();
+        } else if (event.key === "poster" && typeof event.value === "string") {
+          currentMetadata.artwork = [{ src: event.value, sizes: "512x512" }];
+          updateMetadata();
+        }
+      });
+      const unsubPlaylist = api.on("playlist:change", (payload) => {
+        if (payload?.track) {
+          const track = payload.track;
+          currentMetadata = {
+            title: track.title,
+            artist: track.artist,
+            album: track.album,
+            artwork: track.artwork ? [{ src: track.artwork, sizes: "512x512" }] : void 0
+          };
+          updateMetadata();
+        }
+      });
+      api.onDestroy(() => {
+        unsubPlay();
+        unsubPause();
+        unsubEnded();
+        unsubTimeUpdate();
+        unsubMetadata();
+        unsubState();
+        unsubPlaylist();
+        clearActionHandlers();
+      });
+    },
+    async destroy() {
+      api?.logger.info("Media Session plugin destroying");
+      clearActionHandlers();
+      if (isMediaSessionSupported()) {
+        navigator.mediaSession.metadata = null;
+        navigator.mediaSession.playbackState = "none";
+      }
+      api = null;
+    },
+    isSupported() {
+      return isMediaSessionSupported();
+    },
+    setMetadata(metadata) {
+      currentMetadata = { ...currentMetadata, ...metadata };
+      updateMetadata();
+    },
+    setPlaybackState(state) {
+      if (isMediaSessionSupported()) {
+        navigator.mediaSession.playbackState = state;
+      }
+    },
+    setPositionState(state) {
+      if (isMediaSessionSupported()) {
+        try {
+          navigator.mediaSession.setPositionState(state);
+        } catch (e) {
+          api?.logger.debug("Failed to set position state", e);
+        }
+      }
+    },
+    setActionHandler(action, handler) {
+      if (isMediaSessionSupported()) {
+        try {
+          navigator.mediaSession.setActionHandler(action, handler);
+        } catch (e) {
+          api?.logger.debug(`Action ${action} not supported`, e);
+        }
+      }
+    }
+  };
+  return plugin;
+}
+var index_default = createMediaSessionPlugin;
+export {
+  createMediaSessionPlugin,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@scarlett-player/media-session",
+  "version": "0.2.0",
+  "description": "Media Session Plugin for Scarlett Player - Lock screen controls, media keys, and system media UI integration",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@scarlett-player/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.6.0",
+    "jsdom": "^24.0.0",
+    "@scarlett-player/core": "0.2.0"
+  },
+  "keywords": [
+    "video",
+    "audio",
+    "player",
+    "media-session",
+    "lock-screen",
+    "media-keys",
+    "notifications",
+    "scarlett"
+  ],
+  "author": "The Stream Platform",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hackney-Enterprises-Inc/scarlett-player.git",
+    "directory": "packages/plugins/media-session"
+  },
+  "bugs": {
+    "url": "https://github.com/Hackney-Enterprises-Inc/scarlett-player/issues"
+  },
+  "homepage": "https://scarlettplayer.com",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}