@microsoft/live-share-media 1.3.0 → 1.4.0

package/src/MediaSessionActionThrottler.ts

@@ -1,19 +1,19 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import {
-    ExtendedMediaSessionActionDetails,
-    ExtendedMediaSessionActionHandler,
-} from "./MediaSessionExtensions";
-
-/**
- * Base class for action throttlers.
- */
-export abstract class MediaSessionActionThrottler {
-    public abstract throttled(
-        details: MediaSessionActionDetails | ExtendedMediaSessionActionDetails,
-        handler?: MediaSessionActionHandler | ExtendedMediaSessionActionHandler
-    ): void;
-}
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    ExtendedMediaSessionActionDetails,
+    ExtendedMediaSessionActionHandler,
+} from "./MediaSessionExtensions";
+
+/**
+ * Base class for action throttlers.
+ */
+export abstract class MediaSessionActionThrottler {
+    public abstract throttled(
+        details: MediaSessionActionDetails | ExtendedMediaSessionActionDetails,
+        handler?: MediaSessionActionHandler | ExtendedMediaSessionActionHandler
+    ): void;
+}

package/src/MediaSessionExtensions.ts

@@ -1,187 +1,198 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-/**
- * Suspension object for when group synchronization is suspended for the local user.
- */
-export interface MediaSessionCoordinatorSuspension {
-    /**
-     * The wait point that the suspension was created with.
-     *
-     * @remarks
-     * If undefined, the suspension was not created with a wait point.
-     */
-    waitPoint?: CoordinationWaitPoint;
-    /**
-     * Ends the suspension.
-     *
-     * @param seekTo the timestamp to seek to after the suspension ends.
-     * If no value is provided, the local user will return to the group playback position.
-     *
-     * @remarks
-     * If there are other suspensions active, all other suspensions must be ended before group synchronization can resume.
-     */
-    end(seekTo?: number): void;
-}
-
-/**
- * Wait point interface for a suspension.
- *
- * @remarks
- * Used by {@link MediaSessionCoordinatorSuspension} to schedule a suspension at a specific media position.
- */
-export interface CoordinationWaitPoint {
-    /**
-     * The position in milliseconds that the suspension should begin.
-     */
-    position: number;
-    /**
-     * Optional. The reason for the suspension.
-     */
-    reason?: string;
-    /**
-     * Optional. The max clients to wait for before a suspension ends.
-     */
-    maxClients?: number;
-}
-
-/**
- * The state of the `LiveMediaSessionCoordinator`.
- */
-export type MediaSessionCoordinatorState = "closed" | "waiting" | "joined";
-
-/**
- * Event types of `LiveMediaSessionCoordinator`.
- */
-export enum MediaSessionCoordinatorEvents {
-    /**
-     * Event emitted after the coordinator's state changed
-     */
-    coordinatorstatechange = "coordinatorstatechange",
-    /**
-     * Event emitted when an action was triggered.
-     */
-    triggeraction = "triggeraction",
-}
-
-/**
- * Action types supported for `LiveMediaSession`.
- *
- * @remarks
- * These types extend the default actions supported by the `MediaSession` specification in browsers.
- * These additional actions help with group synchronization.
- */
-export type ExtendedMediaSessionAction =
-    | MediaSessionAction
-    | "settrack"
-    | "wait"
-    | "catchup"
-    | "datachange"
-    | "blocked";
-
-/**
- * Extended playback state for `LiveMediaSession`.
- *
- * @remarks
- * These types extend the default state types supported by the `MediaSession` specification in browsers.
- * These additional types help with group synchronization.
- */
-export type ExtendedMediaSessionPlaybackState =
-    | MediaSessionPlaybackState
-    | "suspended"
-    | "waiting"
-    | "ended";
-
-/**
- * The source of the action for `LiveMediaSession`.
- *
- * @remarks
- * Is `user` when the action was explicitly invoked via the `LiveMediaSessionCoordinator`.
- * Is `system` when the action was invoked via `GroupCoordinatorState` when the local client is out of sync.
- */
-export type ExtendedMediaSessionActionSource = "user" | "system";
-
-/**
- * Metadata for `LiveMediaSession`.
- *
- * @remarks
- * These types extend the default session metadata supported by the `MediaSession` specification in browsers.
- * These additional types help with group synchronization.
- */
-export interface ExtendedMediaMetadata extends MediaMetadata {
-    /**
-     * A unique identifier for the track (e.g., UUID, URL, etc.)
-     */
-    trackIdentifier: string;
-    /**
-     * Flag indicating whether or not the stream is a live broadcast.
-     */
-    liveStream?: boolean;
-}
-
-/**
- * Details for emitted actions from `LiveMediaSession`.
- *
- * @remarks
- * These types extend the default event details supported by the `MediaSession` specification in browsers.
- * These additional types help with group synchronization.
- */
-export interface ExtendedMediaSessionActionDetails {
-    /**
-     * The action type of this event.
-     */
-    action: ExtendedMediaSessionAction;
-    /**
-     * The source of the action.
-     *
-     * @remarks
-     * Is `user` when the action was explicitly invoked via the `LiveMediaSessionCoordinator`.
-     * Is `system` when the action was invoked via `GroupCoordinatorState` when the local client is out of sync.
-     */
-    source: ExtendedMediaSessionActionSource;
-    /**
-     * Unique identifier of the client that triggered this action.
-     */
-    clientId: string;
-    /**
-     * Flag indicating whether or not the action was triggered by the local client.
-     */
-    local: boolean;
-    /**
-     * Flag indicating whether or not this was a fast seek action.
-     */
-    fastSeek?: boolean | null;
-    /**
-     * The offset of the seek.
-     */
-    seekOffset?: number | null;
-    /**
-     * Timestamp of the seek event.
-     */
-    seekTime?: number | null;
-    /**
-     * Updated session metadata that was changed via this action.
-     */
-    metadata?: ExtendedMediaMetadata | null;
-    /**
-     * Suspension associated with this action.
-     */
-    suspension?: MediaSessionCoordinatorSuspension | null;
-    /**
-     * Custom data associated with this action.
-     */
-    data?: object | null;
-    /**
-     * Action type that was blocked.
-     */
-    blocked?: ExtendedMediaSessionAction | null;
-}
-
-/**
- * Handler for `LiveMediaSession` actions.
- */
-export interface ExtendedMediaSessionActionHandler {
-    (details: ExtendedMediaSessionActionDetails): void;
-}
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+/**
+ * Suspension object for when group synchronization is suspended for the local user.
+ */
+export interface MediaSessionCoordinatorSuspension {
+    /**
+     * The wait point that the suspension was created with.
+     *
+     * @remarks
+     * If undefined, the suspension was not created with a wait point.
+     */
+    waitPoint?: CoordinationWaitPoint;
+    /**
+     * Ends the suspension.
+     *
+     * @param seekTo the timestamp to seek to after the suspension ends.
+     * If no value is provided, the local user will return to the group playback position.
+     *
+     * @remarks
+     * If there are other suspensions active, all other suspensions must be ended before group synchronization can resume.
+     */
+    end(seekTo?: number): void;
+}
+
+/**
+ * Wait point interface for a suspension.
+ *
+ * @remarks
+ * Used by {@link MediaSessionCoordinatorSuspension} to schedule a suspension at a specific media position.
+ */
+export interface CoordinationWaitPoint {
+    /**
+     * The position in milliseconds that the suspension should begin.
+     */
+    position: number;
+    /**
+     * Optional. The reason for the suspension.
+     */
+    reason?: string;
+    /**
+     * Optional. The max clients to wait for before a suspension ends.
+     */
+    maxClients?: number;
+}
+
+/**
+ * Event types of `LiveMediaSessionCoordinator`.
+ */
+export enum MediaSessionCoordinatorEvents {
+    /**
+     * Event emitted after the coordinator's state changed
+     */
+    coordinatorstatechange = "coordinatorstatechange",
+    /**
+     * Event emitted when an action was triggered.
+     */
+    triggeraction = "triggeraction",
+    /**
+     * Event emitted when an action would have been triggered, but a suspension is active for the local client.
+     */
+    triggeractionignored = "triggeractionignored",
+}
+
+/**
+ * Action types supported for `LiveMediaSession`.
+ *
+ * @remarks
+ * These types extend the default actions supported by the `MediaSession` specification in browsers.
+ * These additional actions help with group synchronization.
+ */
+export type ExtendedMediaSessionAction =
+    | MediaSessionAction
+    | "settrack"
+    | "ratechange"
+    | "wait"
+    | "catchup"
+    | "datachange"
+    | "blocked";
+
+/**
+ * Extended playback state for `LiveMediaSession`.
+ *
+ * @remarks
+ * These types extend the default state types supported by the `MediaSession` specification in browsers.
+ * These additional types help with group synchronization.
+ */
+export type ExtendedMediaSessionPlaybackState =
+    | MediaSessionPlaybackState
+    | "suspended"
+    | "waiting"
+    | "ended";
+
+/**
+ * The source of the action for `LiveMediaSession`.
+ *
+ * @remarks
+ * Is `user` when the action was explicitly invoked via the `LiveMediaSessionCoordinator`.
+ * Is `system` when the action was invoked via `GroupCoordinatorState` when the local client is out of sync.
+ */
+export type ExtendedMediaSessionActionSource = "user" | "system";
+
+/**
+ * Metadata for `LiveMediaSession`.
+ *
+ * @remarks
+ * These types extend the default session metadata supported by the `MediaSession` specification in browsers.
+ * These additional types help with group synchronization.
+ */
+export interface ExtendedMediaMetadata extends MediaMetadata {
+    /**
+     * A unique identifier for the track (e.g., UUID, URL, etc.)
+     */
+    trackIdentifier: string;
+    /**
+     * Flag indicating whether or not the stream is a live broadcast.
+     */
+    liveStream?: boolean;
+}
+
+/**
+ * The reasons why an action is ignored.
+ *
+ * @remarks
+ * Is `localusersuspended` when the action updated the group state, but ignored locally due to the local client being suspended.
+
+ */
+export type ExtendedMediaSessionActionIgnore = "localusersuspended";
+
+/**
+ * Details for emitted actions from `LiveMediaSession`.
+ *
+ * @remarks
+ * These types extend the default event details supported by the `MediaSession` specification in browsers.
+ * These additional types help with group synchronization.
+ */
+export interface ExtendedMediaSessionActionDetails {
+    /**
+     * The action type of this event.
+     */
+    action: ExtendedMediaSessionAction;
+    /**
+     * The source of the action.
+     *
+     * @remarks
+     * Is `user` when the action was explicitly invoked via the `LiveMediaSessionCoordinator`.
+     * Is `system` when the action was invoked via `GroupCoordinatorState` when the local client is out of sync.
+     */
+    source: ExtendedMediaSessionActionSource;
+    /**
+     * Unique identifier of the client that triggered this action.
+     */
+    clientId: string;
+    /**
+     * Flag indicating whether or not the action was triggered by the local client.
+     */
+    local: boolean;
+    /**
+     * Flag indicating whether or not this was a fast seek action.
+     */
+    fastSeek?: boolean | null;
+    /**
+     * The offset of the seek.
+     */
+    seekOffset?: number | null;
+    /**
+     * Timestamp of the seek event.
+     */
+    seekTime?: number | null;
+    /**
+     * Updated session metadata that was changed via this action.
+     */
+    metadata?: ExtendedMediaMetadata | null;
+    /**
+     * Suspension associated with this action.
+     */
+    suspension?: MediaSessionCoordinatorSuspension | null;
+    /**
+     * Custom data associated with this action.
+     */
+    data?: object | null;
+    /**
+     * Reason an action is ignored by the local client, undefined if not ignored.
+     */
+    ignoreReason?: ExtendedMediaSessionActionIgnore | null;
+
+    playbackRate?: number | null;
+}
+
+/**
+ * Handler for `LiveMediaSession` actions.
+ */
+export interface ExtendedMediaSessionActionHandler {
+    (details: ExtendedMediaSessionActionDetails): void;
+}

package/src/RepeatedActionThrottler.ts

@@ -1,76 +1,76 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import { TimeInterval } from "@microsoft/live-share";
-import { MediaSessionActionThrottler } from "./MediaSessionActionThrottler";
-import {
-    ExtendedMediaSessionActionDetails,
-    ExtendedMediaSessionAction,
-} from "./MediaSessionExtensions";
-
-/**
- *  A Throttler that passes through all actions but will only let an action be repeated once every 2 seconds.
- */
-export class RepeatedActionThrottler extends MediaSessionActionThrottler {
-    private static FILTERED_ACTIONS: ExtendedMediaSessionAction[] = [
-        "play",
-        "pause",
-        "seekto",
-        "catchup",
-    ];
-    private _repeatInterval = new TimeInterval(2000);
-    private _lastActionSentTime?: number;
-    private _lastActionSent?: string;
-
-    public get repeatInterval(): number {
-        return this._repeatInterval.seconds;
-    }
-
-    public set repeatInterval(value: number) {
-        this._repeatInterval.seconds = value;
-    }
-
-    public throttled(
-        details: MediaSessionActionDetails | ExtendedMediaSessionActionDetails,
-        handler?: MediaSessionActionHandler
-    ): void {
-        if (handler) {
-            if (
-                RepeatedActionThrottler.FILTERED_ACTIONS.indexOf(
-                    details.action
-                ) >= 0
-            ) {
-                const changeKey = this.getChangeKey(details);
-                const now = new Date().getTime();
-                if (this._lastActionSent && changeKey == this._lastActionSent) {
-                    if (
-                        now - this._lastActionSentTime! >=
-                        this._repeatInterval.milliseconds
-                    ) {
-                        handler(details as MediaSessionActionDetails);
-                        this._lastActionSentTime = now;
-                    }
-                } else {
-                    handler(details as MediaSessionActionDetails);
-                    this._lastActionSent = changeKey;
-                    this._lastActionSentTime = now;
-                }
-            } else {
-                handler(details as MediaSessionActionDetails);
-            }
-        }
-    }
-
-    private getChangeKey(
-        details: MediaSessionActionDetails | ExtendedMediaSessionActionDetails
-    ): string {
-        switch (details.action) {
-            case "seekto":
-                return `seekto:${details.seekTime}`;
-            default:
-                return details.action;
-        }
-    }
-}
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { TimeInterval } from "@microsoft/live-share";
+import { MediaSessionActionThrottler } from "./MediaSessionActionThrottler";
+import {
+    ExtendedMediaSessionActionDetails,
+    ExtendedMediaSessionAction,
+} from "./MediaSessionExtensions";
+
+/**
+ *  A Throttler that passes through all actions but will only let an action be repeated once every 2 seconds.
+ */
+export class RepeatedActionThrottler extends MediaSessionActionThrottler {
+    private static FILTERED_ACTIONS: ExtendedMediaSessionAction[] = [
+        "play",
+        "pause",
+        "seekto",
+        "catchup",
+    ];
+    private _repeatInterval = new TimeInterval(2000);
+    private _lastActionSentTime?: number;
+    private _lastActionSent?: string;
+
+    public get repeatInterval(): number {
+        return this._repeatInterval.seconds;
+    }
+
+    public set repeatInterval(value: number) {
+        this._repeatInterval.seconds = value;
+    }
+
+    public throttled(
+        details: MediaSessionActionDetails | ExtendedMediaSessionActionDetails,
+        handler?: MediaSessionActionHandler
+    ): void {
+        if (handler) {
+            if (
+                RepeatedActionThrottler.FILTERED_ACTIONS.indexOf(
+                    details.action
+                ) >= 0
+            ) {
+                const changeKey = this.getChangeKey(details);
+                const now = new Date().getTime();
+                if (this._lastActionSent && changeKey == this._lastActionSent) {
+                    if (
+                        now - this._lastActionSentTime! >=
+                        this._repeatInterval.milliseconds
+                    ) {
+                        handler(details as MediaSessionActionDetails);
+                        this._lastActionSentTime = now;
+                    }
+                } else {
+                    handler(details as MediaSessionActionDetails);
+                    this._lastActionSent = changeKey;
+                    this._lastActionSentTime = now;
+                }
+            } else {
+                handler(details as MediaSessionActionDetails);
+            }
+        }
+    }
+
+    private getChangeKey(
+        details: MediaSessionActionDetails | ExtendedMediaSessionActionDetails
+    ): string {
+        switch (details.action) {
+            case "seekto":
+                return `seekto:${details.seekTime}`;
+            default:
+                return details.action;
+        }
+    }
+}