@microsoft/live-share-media 1.0.0-preview.9 → 1.0.0

package/bin/internals/index.js

@@ -1,27 +1,27 @@
-"use strict";
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./consts"), exports);
-__exportStar(require("./GroupCoordinatorState"), exports);
-__exportStar(require("./GroupPlaybackPosition"), exports);
-__exportStar(require("./GroupPlaybackTrack"), exports);
-__exportStar(require("./GroupPlaybackTrackData"), exports);
-__exportStar(require("./GroupTransportState"), exports);
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./consts"), exports);
+__exportStar(require("./GroupCoordinatorState"), exports);
+__exportStar(require("./GroupPlaybackPosition"), exports);
+__exportStar(require("./GroupPlaybackTrack"), exports);
+__exportStar(require("./GroupPlaybackTrackData"), exports);
+__exportStar(require("./GroupTransportState"), exports);
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@microsoft/live-share-media",
-    "version": "1.0.0-preview.9",
+    "version": "1.0.0",
     "description": "Live Share classes that synchronize media playback across clients.",
     "author": "Microsoft",
     "license": "SEE LICENSE IN LICENSE",
@@ -13,18 +13,20 @@
         "test:debug": "ts-mocha src/**/*.spec.ts --inspect-brk",
         "test:coverage": "nyc --reporter=html --reporter=text --reporter=text-summary npm test"
     },
-    "dependencies": {
-        "@microsoft/live-share": "1.0.0-preview.9",
-        "fluid-framework": "~1.2.3"
-    },
     "devDependencies": {
+        "@microsoft/live-share": "1.0.0",
         "@types/assert": "^1.5.6",
         "@types/mocha": "^10.0.1",
-        "@types/node": "^18.11.18",
+        "@types/node": "^20.2.3",
+        "fluid-framework": "^1.3.6",
         "mocha": "^10.2.0",
         "nyc": "^15.1.0",
         "ts-mocha": "^10.0.0",
-        "typescript": "^4.6.4"
+        "typescript": "^5.0.4"
+    },
+    "peerDependencies": {
+        "@microsoft/live-share": "1.0.0",
+        "fluid-framework": "^1.2.3"
     },
     "repository": {
         "directory": "packages/live-share-media",

package/src/LiveMediaSession.ts

@@ -3,8 +3,13 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-import { DataObject, DataObjectFactory } from "@fluidframework/aqueduct";
-import { DynamicObjectRegistry, LiveTelemetryLogger, UserMeetingRole } from "@microsoft/live-share";
+import { DataObjectFactory } from "@fluidframework/aqueduct";
+import {
+    DynamicObjectRegistry,
+    LiveDataObject,
+    LiveTelemetryLogger,
+    UserMeetingRole,
+} from "@microsoft/live-share";
 import { MediaPlayerSynchronizer } from "./MediaPlayerSynchronizer";
 import { ITriggerActionEvent, TelemetryEvents } from "./internals";
 import {
@@ -23,7 +28,7 @@ import { IMediaPlayer } from "./IMediaPlayer";
 /**
  * Live fluid object that synchronizes media playback across multiple clients.
  */
-export class LiveMediaSession extends DataObject {
+export class LiveMediaSession extends LiveDataObject {
     private _actionThrottler: MediaSessionActionThrottler =
         new RepeatedActionThrottler();
     private _logger?: LiveTelemetryLogger;
@@ -80,14 +85,6 @@ export class LiveMediaSession extends DataObject {
         return this.coordinator.isInitialized;
     }
 
-    /**
-     * @deprecated isInitialized should be used instead
-     * Returns true if the object has been initialized.
-     */
-    public get isStarted(): boolean {
-        return this.isInitialized;
-    }
-
     /**
      * The group coordinator for the session.
      */
@@ -107,13 +104,15 @@ export class LiveMediaSession extends DataObject {
 
     /**
      * initialize the object.
-     * @param acceptTransportChangesFrom Optional. List of roles allowed to group transport
+     * @param allowedRoles Optional. List of roles allowed to group transport
      * operations like play/pause/seek/setTrack.
+     * @returns a void promise that resolves once complete
      */
-    public initialize(
-        acceptTransportChangesFrom?: UserMeetingRole[]
-    ): Promise<void> {
-        return this.coordinator.initialize(acceptTransportChangesFrom);
+    public initialize(allowedRoles?: UserMeetingRole[]): Promise<void> {
+        if (allowedRoles) {
+            this._allowedRoles = allowedRoles;
+        }
+        return this.coordinator.initialize(allowedRoles);
     }
 
     /**
@@ -184,11 +183,13 @@ export class LiveMediaSession extends DataObject {
     }
 
     protected async hasInitialized(): Promise<void> {
-        this._logger = new LiveTelemetryLogger(this.runtime);
+        this._logger = new LiveTelemetryLogger(this.runtime, this.liveRuntime);
 
         // Create coordinator and listen for triggered actions
-        this._coordinator = new LiveMediaSessionCoordinator(this.runtime, () =>
-            this.getCurrentPlayerState()
+        this._coordinator = new LiveMediaSessionCoordinator(
+            this.runtime,
+            this.liveRuntime,
+            () => this.getCurrentPlayerState()
         );
         this._coordinator.on(
             MediaSessionCoordinatorEvents.triggeraction,
@@ -302,4 +303,7 @@ export class LiveMediaSession extends DataObject {
 /**
  * Register `LiveMediaSession` as an available `LoadableObjectClass` for use in packages that support dynamic object loading, such as `@microsoft/live-share-turbo`.
  */
-DynamicObjectRegistry.registerObjectClass(LiveMediaSession, LiveMediaSession.TypeName);
+DynamicObjectRegistry.registerObjectClass(
+    LiveMediaSession,
+    LiveMediaSession.TypeName
+);

package/src/LiveMediaSessionCoordinator.ts

@@ -7,18 +7,15 @@ import {
     LiveEventScope,
     LiveTelemetryLogger,
     LiveEventTarget,
-    ILiveEvent,
     IRuntimeSignaler,
     TimeInterval,
     UserMeetingRole,
+    LiveShareRuntime,
 } from "@microsoft/live-share";
 import {
     CoordinationWaitPoint,
-    ExtendedMediaSessionActionDetails,
     ExtendedMediaMetadata,
     ExtendedMediaSessionPlaybackState,
-    MediaSessionCoordinatorEvents,
-    MediaSessionCoordinatorState,
     MediaSessionCoordinatorSuspension,
 } from "./MediaSessionExtensions";
 import {
@@ -28,7 +25,6 @@ import {
     IPositionUpdateEvent,
     GroupCoordinatorState,
     GroupCoordinatorStateEvents,
-    ITriggerActionEvent,
     ISetTrackDataEvent,
 } from "./internals";
 import { LiveMediaSessionCoordinatorSuspension } from "./LiveMediaSessionCoordinatorSuspension";
@@ -69,6 +65,7 @@ export interface IMediaPlayerState {
  */
 export class LiveMediaSessionCoordinator extends EventEmitter {
     private readonly _runtime: IRuntimeSignaler;
+    private readonly _liveRuntime: LiveShareRuntime;
     private readonly _logger: LiveTelemetryLogger;
     private readonly _getPlayerState: () => IMediaPlayerState;
     private _positionUpdateInterval = new TimeInterval(2000);
@@ -83,22 +80,26 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
     private _setTrackEvent?: LiveEventTarget<ISetTrackEvent>;
     private _setTrackDataEvent?: LiveEventTarget<ISetTrackDataEvent>;
     private _positionUpdateEvent?: LiveEventTarget<IPositionUpdateEvent>;
-    private _joinedEvent?: LiveEventTarget<ILiveEvent>;
+    private _joinedEvent?: LiveEventTarget<undefined>;
 
     // Distributed state
     private _groupState?: GroupCoordinatorState;
 
+    private _allowedRoles?: UserMeetingRole[];
+
     /**
      * @hidden
      * Applications shouldn't directly create new coordinator instances.
      */
     constructor(
         runtime: IRuntimeSignaler,
+        liveRuntime: LiveShareRuntime,
         getPlayerState: () => IMediaPlayerState
     ) {
         super();
         this._runtime = runtime;
-        this._logger = new LiveTelemetryLogger(runtime);
+        this._liveRuntime = liveRuntime;
+        this._logger = new LiveTelemetryLogger(runtime, liveRuntime);
         this._getPlayerState = getPlayerState;
     }
 
@@ -201,8 +202,10 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
      * @remarks
      * Throws an exception if the session/coordinator hasn't been initialized, no track has been
      * loaded, or `canPlayPause` is false.
+     *
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public play(): void {
+    public async play(): Promise<void> {
         if (!this._hasInitialized) {
             throw new Error(
                 `LiveMediaSessionCoordinator.play() called before initialize() called.`
@@ -230,7 +233,7 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
             null,
             { position: position }
         );
-        this._playEvent!.sendEvent({
+        await this._playEvent!.sendEvent({
             track: this._groupState.playbackTrack.current,
             position: position,
         });
@@ -242,8 +245,10 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
      * @remarks
      * Throws an exception if the session/coordinator hasn't been initialized, no track has been
      * loaded, or `canPlayPause` is false.
+     *
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public pause(): void {
+    public async pause(): Promise<void> {
         if (!this._hasInitialized) {
             throw new Error(
                 `LiveMediaSessionCoordinator.pause() called before initialize() called.`
@@ -271,7 +276,7 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
             null,
             { position: position }
         );
-        this._pauseEvent!.sendEvent({
+        await this._pauseEvent!.sendEvent({
             track: this._groupState.playbackTrack.current,
             position: position,
         });
@@ -284,8 +289,9 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
      * Throws an exception if the session/coordinator hasn't been initialized, no track has been
      * loaded, or `canSeek` is false.
      * @param time Playback position in seconds to seek to.
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public seekTo(time: number): void {
+    public async seekTo(time: number): Promise<void> {
         if (!this._hasInitialized) {
             throw new Error(
                 `LiveMediaSessionCoordinator.seekTo() called before initialize() called.`
@@ -310,10 +316,15 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
             null,
             { position: time }
         );
-        this._seekToEvent!.sendEvent({
-            track: this._groupState.playbackTrack.current,
-            position: time,
-        });
+        try {
+            await this._seekToEvent!.sendEvent({
+                track: this._groupState.playbackTrack.current,
+                position: time,
+            });
+        } catch (err) {
+            await this._groupState!.syncLocalMediaSession();
+            throw err;
+        }
     }
 
     /**
@@ -324,11 +335,12 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
      * false.
      * @param metadata The track to load or `null` to indicate that the end of the track is reached.
      * @param waitPoints Optional. List of static wait points to configure for the track.  Dynamic wait points can be added via the `beginSuspension()` call.
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public setTrack(
+    public async setTrack(
         metadata: ExtendedMediaMetadata | null,
         waitPoints?: CoordinationWaitPoint[]
-    ): void {
+    ): Promise<void> {
         if (!this._hasInitialized) {
             throw new Error(
                 `LiveMediaSessionCoordinator.setTrack() called before initialize() called.`
@@ -345,7 +357,7 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
         this._logger.sendTelemetryEvent(
             TelemetryEvents.SessionCoordinator.SetTrackCalled
         );
-        this._setTrackEvent!.sendEvent({
+        await this._setTrackEvent!.sendEvent({
             metadata: metadata,
             waitPoints: waitPoints || [],
         });
@@ -361,8 +373,9 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
      * Throws an exception if the session/coordinator hasn't been initialized or `canSetTrackData` is
      * false.
      * @param data New data object to sync with the group. This value will be synchronized using a last writer wins strategy.
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public setTrackData(data: object | null): void {
+    public async setTrackData(data: object | null): Promise<void> {
         if (!this._hasInitialized) {
             throw new Error(
                 `LiveMediaSessionCoordinator.setTrackData() called before initialize() called.`
@@ -379,7 +392,7 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
         this._logger.sendTelemetryEvent(
             TelemetryEvents.SessionCoordinator.SetTrackDataCalled
         );
-        this._setTrackDataEvent!.sendEvent({
+        await this._setTrackDataEvent!.sendEvent({
             data: data,
         });
     }
@@ -520,23 +533,51 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
         }
 
         // Send position update event
-        const evt = this._groupState!.createPositionUpdateEvent(state);
-        this._positionUpdateEvent?.sendEvent(evt);
+        this.verifyLocalUserRoles()
+            .then((valid) => {
+                const evt = this._groupState!.createPositionUpdateEvent(state);
+                if (!valid) {
+                    // We still need to update _groupState with the local user's position.
+                    // So we do this here rather than on the receiving end.
+                    this._groupState!.handlePositionUpdate(
+                        {
+                            clientId: this._runtime.clientId ?? "",
+                            timestamp: this._liveRuntime.getTimestamp(),
+                            data: evt,
+                        },
+                        true
+                    );
+                    return;
+                }
+                return this._positionUpdateEvent?.sendEvent(evt);
+            })
+            .catch((err) => {
+                this._logger.sendErrorEvent(
+                    TelemetryEvents.SessionCoordinator.PositionUpdateEventError,
+                    err
+                );
+            });
     }
 
     protected async createChildren(
         acceptTransportChangesFrom?: UserMeetingRole[]
     ): Promise<void> {
+        this._allowedRoles = acceptTransportChangesFrom;
         // Create event scopes
         const scope = new LiveEventScope(
             this._runtime,
+            this._liveRuntime,
             acceptTransportChangesFrom
         );
-        const unrestrictedScope = new LiveEventScope(this._runtime);
+        const unrestrictedScope = new LiveEventScope(
+            this._runtime,
+            this._liveRuntime
+        );
 
         // Initialize internal coordinator state
         this._groupState = new GroupCoordinatorState(
             this._runtime,
+            this._liveRuntime,
             this._maxPlaybackDrift,
             this._positionUpdateInterval,
             this._getPlayerState
@@ -596,14 +637,22 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
                     }
                 );
                 const state = this._getPlayerState();
-                const update =
-                    this._groupState!.createPositionUpdateEvent(state);
-                this._positionUpdateEvent?.sendEvent(update);
+                this.sendPositionUpdate(state);
             }
         );
 
-        // Send initial joined event
-        this._joinedEvent.sendEvent({});
+        this.verifyLocalUserRoles()
+            .then((verified) => {
+                if (!verified) return;
+                // Send initial joined event
+                return this._joinedEvent?.sendEvent(undefined);
+            })
+            .catch((err) => {
+                this._logger.sendErrorEvent(
+                    TelemetryEvents.SessionCoordinator.SendJoinedEventError,
+                    err
+                );
+            });
     }
 
     private getPlayerPosition(): number {
@@ -618,4 +667,27 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
                     : 0.0;
         }
     }
+
+    private async verifyLocalUserRoles(): Promise<boolean> {
+        const clientId = await this.waitUntilConnected();
+        return this._liveRuntime.verifyRolesAllowed(
+            clientId,
+            this._allowedRoles ?? []
+        );
+    }
+
+    private waitUntilConnected(): Promise<string> {
+        return new Promise((resolve) => {
+            const onConnected = (clientId: string) => {
+                this._runtime.off("connected", onConnected);
+                resolve(clientId);
+            };
+
+            if (this._runtime.clientId && this._runtime.connected) {
+                resolve(this._runtime.clientId);
+            } else {
+                this._runtime.on("connected", onConnected);
+            }
+        });
+    }
 }

package/src/MediaPlayerSynchronizer.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the Microsoft Live Share SDK License.
  */
-import { LiveTelemetryLogger, IEvent } from "@microsoft/live-share";
+import { LiveTelemetryLogger, ILiveEvent } from "@microsoft/live-share";
 import EventEmitter from "events";
 import {
     ExtendedMediaSessionAction,
@@ -21,7 +21,7 @@ import { TelemetryEvents } from "./internals";
 /**
  * Event data returned by `MediaPlayerSynchronizer` object.
  */
-export interface IMediaPlayerSynchronizerEvent extends IEvent {
+export interface IMediaPlayerSynchronizerEvent extends ILiveEvent {
     /**
      * Event details.
      */
@@ -164,7 +164,13 @@ export class MediaPlayerSynchronizer extends EventEmitter {
                                 TelemetryEvents.MediaPlayerSynchronizer
                                     .UserTappedVideoToPlay
                             );
-                            this.play();
+                            this.play().catch((err) => {
+                                this._logger.sendErrorEvent(
+                                    TelemetryEvents.MediaPlayerSynchronizer
+                                        .UserTappedVideoToPlayError,
+                                    err
+                                );
+                            });
                         }
                     }
                     // block play if player state is playing when expected synced state is paused and coordinator is not suspended.
@@ -498,13 +504,15 @@ export class MediaPlayerSynchronizer extends EventEmitter {
      * @remarks
      * For proper operation apps should avoid calling `mediaSession.coordinator.play()` directly
      * and instead use the synchronizers `play()` method.
+     *
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public play(): void {
+    public async play(): Promise<void> {
         this._logger.sendTelemetryEvent(
             TelemetryEvents.MediaPlayerSynchronizer.PlayCalled
         );
         this._expectedPlaybackState = "playing";
-        this._mediaSession.coordinator.play();
+        await this._mediaSession.coordinator.play();
 
         this.dispatchUserAction({ action: "play" });
     }
@@ -515,13 +523,15 @@ export class MediaPlayerSynchronizer extends EventEmitter {
      * @remarks
      * For proper operation apps should avoid calling `mediaSession.coordinator.pause()` directly
      * and instead use the synchronizers `pause()` method.
+     *
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public pause(): void {
+    public async pause(): Promise<void> {
         this._logger.sendTelemetryEvent(
             TelemetryEvents.MediaPlayerSynchronizer.PauseCalled
         );
         this._expectedPlaybackState = "paused";
-        this._mediaSession.coordinator.pause();
+        await this._mediaSession.coordinator.pause();
 
         this.dispatchUserAction({ action: "pause" });
     }
@@ -532,8 +542,10 @@ export class MediaPlayerSynchronizer extends EventEmitter {
      * @remarks
      * For proper operation apps should avoid calling `mediaSession.coordinator.seekTo()` directly
      * and instead use the synchronizers `seekTo()` method.
+     *
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public seekTo(time: number): void {
+    public async seekTo(time: number): Promise<void> {
         // Always seek player to new time.
         // - This resolves an issue where the timeline scrubber can temporarily snap back to the original
         //   location.
@@ -544,7 +556,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
             null,
             { position: time }
         );
-        this._mediaSession.coordinator.seekTo(time);
+        await this._mediaSession.coordinator.seekTo(time);
 
         this.dispatchUserAction({ action: "seekto", seekTime: time });
     }
@@ -555,15 +567,17 @@ export class MediaPlayerSynchronizer extends EventEmitter {
      * @remarks
      * For proper operation apps should avoid calling `mediaSession.coordinator.setTrack()` directly
      * and instead use the synchronizers `setTrack()` method.
+     *
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public setTrack(
+    public async setTrack(
         track: ExtendedMediaMetadata,
         waitPoints?: CoordinationWaitPoint[]
-    ): void {
+    ): Promise<void> {
         this._logger.sendTelemetryEvent(
             TelemetryEvents.MediaPlayerSynchronizer.SetTrackCalled
         );
-        this._mediaSession.coordinator.setTrack(track, waitPoints);
+        await this._mediaSession.coordinator.setTrack(track, waitPoints);
 
         this.dispatchUserAction({ action: "settrack", metadata: track });
     }
@@ -574,13 +588,15 @@ export class MediaPlayerSynchronizer extends EventEmitter {
      * @remarks
      * For proper operation apps should avoid calling `mediaSession.coordinator.setTrackData()` directly
      * and instead use the synchronizers `setTrackData()` method.
+     *
+     * @returns a void promise that resolves once complete, throws if user does not have proper roles
      */
-    public setTrackData(data: object | null): void {
+    public async setTrackData(data: object | null): Promise<void> {
         this._logger.sendTelemetryEvent(
             TelemetryEvents.MediaPlayerSynchronizer.SetTrackDataCalled
         );
         this._trackData = data;
-        this._mediaSession.coordinator.setTrackData(data);
+        await this._mediaSession.coordinator.setTrackData(data);
 
         this.dispatchUserAction({ action: "datachange", data: data });
     }