@microsoft/live-share-media 1.2.2 → 1.3.1

package/src/internals/GroupTransportState.ts

@@ -1,170 +1,170 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import { ILiveEvent, LiveShareRuntime } from "@microsoft/live-share";
-import EventEmitter from "events";
-import { IMediaPlayerState } from "../LiveMediaSessionCoordinator";
-import {
-    ExtendedMediaSessionPlaybackState,
-    ExtendedMediaSessionAction,
-    ExtendedMediaSessionActionSource,
-} from "../MediaSessionExtensions";
-import {
-    GroupPlaybackTrack,
-    GroupPlaybackTrackEvents,
-} from "./GroupPlaybackTrack";
-
-/**
- * @hidden
- */
-export interface ITransportState {
-    playbackState: ExtendedMediaSessionPlaybackState;
-    startPosition: number;
-    timestamp: number;
-    clientId: string;
-}
-
-/**
- * @hidden
- */
-export enum GroupTransportStateEvents {
-    transportStateChange = "transportStateChange",
-}
-
-/**
- * @hidden
- */
-export interface ITransportStateChangeEvent extends ILiveEvent {
-    action: ExtendedMediaSessionAction;
-    seekTime?: number;
-}
-
-/**
- * @hidden
- */
-export class GroupTransportState extends EventEmitter {
-    private readonly _getMediaPlayerState: () => IMediaPlayerState;
-    private _track: GroupPlaybackTrack;
-    private readonly _liveRuntime: LiveShareRuntime;
-    private _current: ITransportState;
-
-    constructor(
-        track: GroupPlaybackTrack,
-        getMediaPlayerState: () => IMediaPlayerState,
-        liveRuntime: LiveShareRuntime
-    ) {
-        super();
-        this._liveRuntime = liveRuntime;
-        this._getMediaPlayerState = getMediaPlayerState;
-        this._track = track;
-        this._current = {
-            playbackState: "none",
-            startPosition: 0.0,
-            timestamp: 0,
-            clientId: "",
-        };
-
-        // Listen for track changes
-        this._track.on(GroupPlaybackTrackEvents.trackChange, () => {
-            // Track changed so reset state to stopped ad position 0.0
-            this._current = {
-                playbackState: "none",
-                startPosition: 0.0,
-                timestamp: this._track.current.timestamp,
-                clientId: this._track.current.clientId,
-            };
-        });
-    }
-
-    public get current(): Readonly<ITransportState> {
-        return this._current;
-    }
-
-    public get playbackState(): ExtendedMediaSessionPlaybackState {
-        return this.current.playbackState;
-    }
-
-    public get startPosition(): number {
-        return this.current.startPosition;
-    }
-
-    public get timestamp(): number {
-        return this.current.timestamp;
-    }
-
-    public get track(): GroupPlaybackTrack {
-        return this._track;
-    }
-
-    public compare(state: ITransportState): boolean {
-        return (
-            this.current.playbackState == state.playbackState &&
-            this.current.startPosition == state.startPosition
-        );
-    }
-
-    public updateState(
-        state: ITransportState,
-        source: ExtendedMediaSessionActionSource
-    ): boolean {
-        // Ignore if same playback state and start position
-        if (this.compare(state)) {
-            return false;
-        }
-
-        // Ignore state changes that are older
-        const originalState = this.current;
-        if (state.timestamp < originalState.timestamp) {
-            return false;
-        }
-
-        // Ignore state changes that have the same timestamp and the clientId sorts higher.
-        if (
-            state.timestamp == originalState.timestamp &&
-            state.clientId.localeCompare(originalState.clientId) > 0
-        ) {
-            return false;
-        }
-
-        // Update playback state
-        this._current = state;
-
-        // Trigger transport change
-        const playerState = this._getMediaPlayerState().playbackState;
-        if (
-            originalState.playbackState == state.playbackState &&
-            playerState != "ended"
-        ) {
-            this.emit(GroupTransportStateEvents.transportStateChange, {
-                type: GroupTransportStateEvents.transportStateChange,
-                action: "seekto",
-                clientId: state.clientId,
-                seekTime: state.startPosition,
-                source,
-            });
-        } else if (state.playbackState == "playing") {
-            const now = this._liveRuntime.getTimestamp();
-            const projectedPosition =
-                state.startPosition + (now - state.timestamp) / 1000;
-            this.emit(GroupTransportStateEvents.transportStateChange, {
-                type: GroupTransportStateEvents.transportStateChange,
-                action: "play",
-                clientId: state.clientId,
-                seekTime: projectedPosition,
-                source,
-            });
-        } else {
-            this.emit(GroupTransportStateEvents.transportStateChange, {
-                type: GroupTransportStateEvents.transportStateChange,
-                action: "pause",
-                clientId: state.clientId,
-                seekTime: state.startPosition,
-                source,
-            });
-        }
-
-        return true;
-    }
-}
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { ILiveEvent, LiveShareRuntime } from "@microsoft/live-share";
+import EventEmitter from "events";
+import { IMediaPlayerState } from "../LiveMediaSessionCoordinator";
+import {
+    ExtendedMediaSessionPlaybackState,
+    ExtendedMediaSessionAction,
+    ExtendedMediaSessionActionSource,
+} from "../MediaSessionExtensions";
+import {
+    GroupPlaybackTrack,
+    GroupPlaybackTrackEvents,
+} from "./GroupPlaybackTrack";
+
+/**
+ * @hidden
+ */
+export interface ITransportState {
+    playbackState: ExtendedMediaSessionPlaybackState;
+    startPosition: number;
+    timestamp: number;
+    clientId: string;
+}
+
+/**
+ * @hidden
+ */
+export enum GroupTransportStateEvents {
+    transportStateChange = "transportStateChange",
+}
+
+/**
+ * @hidden
+ */
+export interface ITransportStateChangeEvent extends ILiveEvent {
+    action: ExtendedMediaSessionAction;
+    seekTime?: number;
+}
+
+/**
+ * @hidden
+ */
+export class GroupTransportState extends EventEmitter {
+    private readonly _getMediaPlayerState: () => IMediaPlayerState;
+    private _track: GroupPlaybackTrack;
+    private readonly _liveRuntime: LiveShareRuntime;
+    private _current: ITransportState;
+
+    constructor(
+        track: GroupPlaybackTrack,
+        getMediaPlayerState: () => IMediaPlayerState,
+        liveRuntime: LiveShareRuntime
+    ) {
+        super();
+        this._liveRuntime = liveRuntime;
+        this._getMediaPlayerState = getMediaPlayerState;
+        this._track = track;
+        this._current = {
+            playbackState: "none",
+            startPosition: 0.0,
+            timestamp: 0,
+            clientId: "",
+        };
+
+        // Listen for track changes
+        this._track.on(GroupPlaybackTrackEvents.trackChange, () => {
+            // Track changed so reset state to stopped ad position 0.0
+            this._current = {
+                playbackState: "none",
+                startPosition: 0.0,
+                timestamp: this._track.current.timestamp,
+                clientId: this._track.current.clientId,
+            };
+        });
+    }
+
+    public get current(): Readonly<ITransportState> {
+        return this._current;
+    }
+
+    public get playbackState(): ExtendedMediaSessionPlaybackState {
+        return this.current.playbackState;
+    }
+
+    public get startPosition(): number {
+        return this.current.startPosition;
+    }
+
+    public get timestamp(): number {
+        return this.current.timestamp;
+    }
+
+    public get track(): GroupPlaybackTrack {
+        return this._track;
+    }
+
+    public compare(state: ITransportState): boolean {
+        return (
+            this.current.playbackState == state.playbackState &&
+            this.current.startPosition == state.startPosition
+        );
+    }
+
+    public updateState(
+        state: ITransportState,
+        source: ExtendedMediaSessionActionSource
+    ): boolean {
+        // Ignore if same playback state and start position
+        if (this.compare(state)) {
+            return false;
+        }
+
+        // Ignore state changes that are older
+        const originalState = this.current;
+        if (state.timestamp < originalState.timestamp) {
+            return false;
+        }
+
+        // Ignore state changes that have the same timestamp and the clientId sorts higher.
+        if (
+            state.timestamp == originalState.timestamp &&
+            state.clientId.localeCompare(originalState.clientId) > 0
+        ) {
+            return false;
+        }
+
+        // Update playback state
+        this._current = state;
+
+        // Trigger transport change
+        const playerState = this._getMediaPlayerState().playbackState;
+        if (
+            originalState.playbackState == state.playbackState &&
+            playerState != "ended"
+        ) {
+            this.emit(GroupTransportStateEvents.transportStateChange, {
+                type: GroupTransportStateEvents.transportStateChange,
+                action: "seekto",
+                clientId: state.clientId,
+                seekTime: state.startPosition,
+                source,
+            });
+        } else if (state.playbackState == "playing") {
+            const now = this._liveRuntime.getTimestamp();
+            const projectedPosition =
+                state.startPosition + (now - state.timestamp) / 1000;
+            this.emit(GroupTransportStateEvents.transportStateChange, {
+                type: GroupTransportStateEvents.transportStateChange,
+                action: "play",
+                clientId: state.clientId,
+                seekTime: projectedPosition,
+                source,
+            });
+        } else {
+            this.emit(GroupTransportStateEvents.transportStateChange, {
+                type: GroupTransportStateEvents.transportStateChange,
+                action: "pause",
+                clientId: state.clientId,
+                seekTime: state.startPosition,
+                source,
+            });
+        }
+
+        return true;
+    }
+}

package/src/internals/consts.ts

@@ -1,102 +1,103 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-/**
- * @hidden
- * List of telemetry events. Wrap with a call to transmit() if the event should be transmitted to
- * the telemetry service.
- */
-export const TelemetryEvents = {
-    MediaPlayerSynchronizer: {
-        SynchronizationStarted:
-            "MediaPlayerSynchronizer:SynchronizationStarted",
-        PlayerEvent: "MediaPlayerSynchronizer:PlayerEvent",
-        PlayAction: "MediaPlayerSynchronizer:PlayAction",
-        PauseAction: "MediaPlayerSynchronizer:PauseAction",
-        SeekToAction: "MediaPlayerSynchronizer:SeekToAction",
-        CatchupAction: "MediaPlayerSynchronizer:CatchupAction",
-        SetTrackAction: "MediaPlayerSynchronizer:SetTrackAction",
-        DataChangeAction: "MediaPlayerSynchronizer:DataChangeAction",
-        UserTappedVideoToPlay: transmit(
-            "MediaPlayerSynchronizer:UserTappedVideoToPlay"
-        ),
-        UserTappedVideoToPlayError:
-            "MediaPlayerSynchronizer:UserTappedVideoToPlayError",
-        PlaybackRateChangeBlocked:
-            "MediaPlayerSynchronizer:PlaybackRateChangeBlocked",
-        PlayerBlockedOperation: transmit(
-            "MediaPlayerSynchronizer:PlayerBlockedOperation"
-        ),
-        SeekingPlayerToStartPosition:
-            "MediaPlayerSynchronizer:SeekingPlayerToStartPosition",
-        BeginSeekCalled: "MediaPlayerSynchronizer:BeginSeekCalled",
-        EndSeekCalled: "MediaPlayerSynchronizer:EndSeekCalled",
-        PlayCalled: "MediaPlayerSynchronizer:PlayCalled",
-        PauseCalled: "MediaPlayerSynchronizer:PauseCalled",
-        SeekToCalled: "MediaPlayerSynchronizer:SeekToCalled",
-        SetTrackCalled: "MediaPlayerSynchronizer:SetTrackCalled",
-        SetTrackDataCalled: "MediaPlayerSynchronizer:SetTrackDataCalled",
-    },
-    MediaSession: {
-        PlayAction: transmit("MediaSession:PlayAction"),
-        PauseAction: transmit("MediaSession:PauseAction"),
-        SeekToAction: transmit("MediaSession:SeekToAction"),
-        CatchUpAction: transmit("MediaSession:CatchUpAction"),
-        SetTrackAction: transmit("MediaSession:SetTrackAction"),
-        DataChangeAction: "MediaSession:DataChangeAction",
-        BeginPositionUpdateTimer: "MediaSession:BeginPositionUpdateTimer",
-    },
-    SessionCoordinator: {
-        PlayCalled: transmit("SessionCoordinator:PlayCalled"),
-        PauseCalled: transmit("SessionCoordinator:PauseCalled"),
-        SeekToCalled: transmit("SessionCoordinator:SeekToCalled"),
-        SetTrackCalled: transmit("SessionCoordinator:SetTrackCalled"),
-        SetTrackDataCalled: "SessionCoordinator:SetTrackDataCalled",
-        BeginSuspension: "SessionCoordinator:BeginSuspension",
-        BeginSuspensionAndWait: transmit(
-            "SessionCoordinator:BeginSuspensionAndWait"
-        ),
-        EndSuspension: "SessionCoordinator:EndSuspension",
-        EndSuspensionAndWait: transmit(
-            "SessionCoordinator:EndSuspensionAndWait"
-        ),
-        RemoteJoinReceived: "SessionCoordinator:RemoteJoinReceived",
-        RemoteSetTrackReceived: transmit(
-            "SessionCoordinator:RemoteSetTrackReceived"
-        ),
-        RemoteSetTrackDataReceived: transmit(
-            "SessionCoordinator:RemoteSetTrackDataReceived"
-        ),
-        RemotePlayReceived: transmit("SessionCoordinator:RemotePlayReceived"),
-        RemotePauseReceived: transmit("SessionCoordinator:RemotePauseReceived"),
-        RemoteSeekToReceived: transmit(
-            "SessionCoordinator:RemoteSeekToReceived"
-        ),
-        PositionUpdateEventError: "SessionCoordinator:PositionUpdateEventError",
-        SendJoinedEventError: "SessionCoordinator:SendJoinedEventError",
-    },
-    GroupCoordinator: {
-        TrackChanged: "GroupCoordinator:TrackChanged",
-        TrackChangeDelayed: "GroupCoordinator:TrackChangeDelayed",
-        TrackDataChanged: "GroupCoordinator:TrackDataChanged",
-        TrackDataChangeDelayed: "GroupCoordinator:TrackDataChangeDelayed",
-        TransportStateChanged: "GroupCoordinator:TransportStateChanged",
-        TransportStateChangeDelayed:
-            "GroupCoordinator:TransportStateChangeDelayed",
-        BeginSoftSuspension: "GroupCoordinator:BeginSoftSuspension",
-        CheckingForSyncIssues: "GroupCoordinator:CheckingForSyncIssues",
-        TrackOutOfSync: transmit("GroupCoordinator:TrackOutOfSync"),
-        TrackDataOutOfSync: transmit("GroupCoordinator:TrackDataOutOfSync"),
-        TransportOutOfSync: transmit("GroupCoordinator:TransportOutOfSync"),
-        PositionOutOfSync: transmit("GroupCoordinator:PositionOutOfSync"),
-    },
-};
-
-/**
- * @hidden
- */
-function transmit(eventName: string): string {
-    return `${eventName}#transmit`;
-}
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+/**
+ * @hidden
+ * List of telemetry events. Wrap with a call to transmit() if the event should be transmitted to
+ * the telemetry service.
+ */
+export const TelemetryEvents = {
+    MediaPlayerSynchronizer: {
+        SynchronizationStarted:
+            "MediaPlayerSynchronizer:SynchronizationStarted",
+        PlayerEvent: "MediaPlayerSynchronizer:PlayerEvent",
+        PlayAction: "MediaPlayerSynchronizer:PlayAction",
+        PauseAction: "MediaPlayerSynchronizer:PauseAction",
+        SeekToAction: "MediaPlayerSynchronizer:SeekToAction",
+        CatchupAction: "MediaPlayerSynchronizer:CatchupAction",
+        SetTrackAction: "MediaPlayerSynchronizer:SetTrackAction",
+        DataChangeAction: "MediaPlayerSynchronizer:DataChangeAction",
+        UserTappedVideoToPlay: transmit(
+            "MediaPlayerSynchronizer:UserTappedVideoToPlay"
+        ),
+        UserTappedVideoToPlayError:
+            "MediaPlayerSynchronizer:UserTappedVideoToPlayError",
+        PlaybackRateChangeBlocked:
+            "MediaPlayerSynchronizer:PlaybackRateChangeBlocked",
+        PlayerBlockedOperation: transmit(
+            "MediaPlayerSynchronizer:PlayerBlockedOperation"
+        ),
+        SeekingPlayerToStartPosition:
+            "MediaPlayerSynchronizer:SeekingPlayerToStartPosition",
+        BeginSeekCalled: "MediaPlayerSynchronizer:BeginSeekCalled",
+        EndSeekCalled: "MediaPlayerSynchronizer:EndSeekCalled",
+        PlayCalled: "MediaPlayerSynchronizer:PlayCalled",
+        PauseCalled: "MediaPlayerSynchronizer:PauseCalled",
+        SeekToCalled: "MediaPlayerSynchronizer:SeekToCalled",
+        SetTrackCalled: "MediaPlayerSynchronizer:SetTrackCalled",
+        SetTrackDataCalled: "MediaPlayerSynchronizer:SetTrackDataCalled",
+    },
+    MediaSession: {
+        PlayAction: transmit("MediaSession:PlayAction"),
+        PauseAction: transmit("MediaSession:PauseAction"),
+        SeekToAction: transmit("MediaSession:SeekToAction"),
+        CatchUpAction: transmit("MediaSession:CatchUpAction"),
+        SetTrackAction: transmit("MediaSession:SetTrackAction"),
+        DataChangeAction: "MediaSession:DataChangeAction",
+        BeginPositionUpdateTimer: "MediaSession:BeginPositionUpdateTimer",
+    },
+    SessionCoordinator: {
+        PlayCalled: transmit("SessionCoordinator:PlayCalled"),
+        PauseCalled: transmit("SessionCoordinator:PauseCalled"),
+        SeekToCalled: transmit("SessionCoordinator:SeekToCalled"),
+        SetTrackCalled: transmit("SessionCoordinator:SetTrackCalled"),
+        SetTrackDataCalled: "SessionCoordinator:SetTrackDataCalled",
+        BeginSuspension: "SessionCoordinator:BeginSuspension",
+        BeginSuspensionAndWait: transmit(
+            "SessionCoordinator:BeginSuspensionAndWait"
+        ),
+        EndSuspension: "SessionCoordinator:EndSuspension",
+        EndSuspensionAndWait: transmit(
+            "SessionCoordinator:EndSuspensionAndWait"
+        ),
+        RemoteConnectReceived: "SessionCoordinator:RemoteConnectReceived",
+        RemoteSetTrackReceived: transmit(
+            "SessionCoordinator:RemoteSetTrackReceived"
+        ),
+        RemoteSetTrackDataReceived: transmit(
+            "SessionCoordinator:RemoteSetTrackDataReceived"
+        ),
+        RemotePlayReceived: transmit("SessionCoordinator:RemotePlayReceived"),
+        RemotePauseReceived: transmit("SessionCoordinator:RemotePauseReceived"),
+        RemoteSeekToReceived: transmit(
+            "SessionCoordinator:RemoteSeekToReceived"
+        ),
+        PositionUpdateEventError: "SessionCoordinator:PositionUpdateEventError",
+        LiveObjectSynchronizerStartError:
+            "SessionCoordinator:LiveObjectSynchronizerStartError",
+    },
+    GroupCoordinator: {
+        TrackChanged: "GroupCoordinator:TrackChanged",
+        TrackChangeDelayed: "GroupCoordinator:TrackChangeDelayed",
+        TrackDataChanged: "GroupCoordinator:TrackDataChanged",
+        TrackDataChangeDelayed: "GroupCoordinator:TrackDataChangeDelayed",
+        TransportStateChanged: "GroupCoordinator:TransportStateChanged",
+        TransportStateChangeDelayed:
+            "GroupCoordinator:TransportStateChangeDelayed",
+        BeginSoftSuspension: "GroupCoordinator:BeginSoftSuspension",
+        CheckingForSyncIssues: "GroupCoordinator:CheckingForSyncIssues",
+        TrackOutOfSync: transmit("GroupCoordinator:TrackOutOfSync"),
+        TrackDataOutOfSync: transmit("GroupCoordinator:TrackDataOutOfSync"),
+        TransportOutOfSync: transmit("GroupCoordinator:TransportOutOfSync"),
+        PositionOutOfSync: transmit("GroupCoordinator:PositionOutOfSync"),
+    },
+};
+
+/**
+ * @hidden
+ */
+function transmit(eventName: string): string {
+    return `${eventName}#transmit`;
+}

package/src/internals/errors.ts

@@ -0,0 +1,42 @@
+/**
+ * @hidden
+ * Use for operations that are blocked due to the metadata not being set.
+ */
+export class TrackMetadataNotSetError extends Error {
+    constructor(prefix: string, callingFunction: string) {
+        super(
+            `${prefix} -  called before playback track metadata has been assigned.\nTo fix this error, ensure \`setTrack()\` has been called with the track information before calling \`${callingFunction}()\``
+        );
+    }
+
+    static assert(
+        condition: boolean,
+        prefix: string,
+        callingFunction: string
+    ): asserts condition {
+        if (condition) return;
+        throw new TrackMetadataNotSetError(prefix, callingFunction);
+    }
+}
+
+/**
+ * @hidden
+ * Use for operations that are blocked due to the metadata not being set.
+ */
+export class ActionBlockedError extends Error {
+    constructor(prefix: string, callingFunction: string, settingName: string) {
+        super(
+            `${prefix} - operation blocked due to \`${settingName}\` being set to false.\nTo fix this error, ensure \`${settingName}\` is true before calling \`${callingFunction}()\`, or set \`${settingName}\` to true. If you are using \`MediaPlayerSynchronizer\`, you can instead use the \`viewOnly\`, which when set to false, it will set \`${settingName}\` value to true.`
+        );
+    }
+
+    static assert(
+        condition: boolean,
+        prefix: string,
+        callingFunction: string,
+        settingName: string
+    ): asserts condition {
+        if (condition) return;
+        throw new ActionBlockedError(prefix, callingFunction, settingName);
+    }
+}

package/src/internals/index.ts

@@ -1,11 +1,12 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-export * from "./consts";
-export * from "./GroupCoordinatorState";
-export * from "./GroupPlaybackPosition";
-export * from "./GroupPlaybackTrack";
-export * from "./GroupPlaybackTrackData";
-export * from "./GroupTransportState";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+export * from "./consts";
+export * from "./GroupCoordinatorState";
+export * from "./GroupPlaybackPosition";
+export * from "./GroupPlaybackTrack";
+export * from "./GroupPlaybackTrackData";
+export * from "./GroupTransportState";
+export * from "./errors";

package/tsconfig.build.json

@@ -1,9 +1,9 @@
-{
-    "extends": "./tsconfig.json",
-    "compilerOptions": {
-      "target": "es6"                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */
-    },
-    "exclude": [
-      "test/**/*.ts"
-    ]
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+      "target": "es6"                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */
+    },
+    "exclude": [
+      "test/**/*.ts"
+    ]
   }