@microsoft/live-share-media 1.3.1 → 2.0.0-internal.1

package/src/LiveMediaSessionCoordinator.ts

@@ -33,6 +33,7 @@ import {
     ISetTrackDataEvent,
     TrackMetadataNotSetError,
     ActionBlockedError,
+    IRateChangeCommandEvent,
 } from "./internals";
 import { LiveMediaSessionCoordinatorSuspension } from "./LiveMediaSessionCoordinatorSuspension";
 import EventEmitter from "events";
@@ -87,6 +88,7 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
     private _playEvent?: LiveEventTarget<ITransportCommandEvent>;
     private _pauseEvent?: LiveEventTarget<ITransportCommandEvent>;
     private _seekToEvent?: LiveEventTarget<ITransportCommandEvent>;
+    private _rateChangeEvent?: LiveEventTarget<IRateChangeCommandEvent>;
     private _setTrackEvent?: LiveEventTarget<ISetTrackEvent>;
     private _setTrackDataEvent?: LiveEventTarget<ISetTrackDataEvent>;
     private _positionUpdateEvent?: LiveEventTarget<IPositionUpdateEvent>;
@@ -170,6 +172,20 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
      */
     public canSetTrackData: boolean = true;
 
+    /**
+     * Controls whether or not the local client is allowed to change the playback rate.
+     *
+     * @remarks
+     * This flag largely meant to influence decisions made by the coordinator and can be used by
+     * the UI to determine what controls should be shown to the user. It does not provide any
+     * security in itself.
+     *
+     * If your app is running in a semi-trusted environment where only some clients are allowed
+     * to change the tracks data object, you should use "role based verification" to enforce those
+     * policies.
+     */
+    public canSetPlaybackRate: boolean = true;
+
     /**
      * Controls whether or not the local client is allowed to send position updates to the group.
      *
@@ -346,6 +362,27 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
         }
     }
 
+    public async setPlaybackRate(playbackRate: number): Promise<void> {
+        LiveDataObjectNotInitializedError.assert(
+            "LiveMediaSessionCoordinator:setPlaybackRate",
+            "setPlaybackRate",
+            this.initializeState
+        );
+        ActionBlockedError.assert(
+            this.canSetPlaybackRate,
+            "LiveMediaSessionCoordinator:setPlaybackRate",
+            "setPlaybackRate",
+            "canSetPlaybackRate"
+        );
+
+        this._logger.sendTelemetryEvent(
+            TelemetryEvents.SessionCoordinator.SetPlaybackRateCalled,
+            null,
+            { playbackRate }
+        );
+        await this._rateChangeEvent!.sendEvent({ playbackRate });
+    }
+
     /**
      * Instructs the group to load a new track.
      *
@@ -624,6 +661,11 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
             this.emit(evt.name, evt)
         );
 
+        this._groupState.on(
+            GroupCoordinatorStateEvents.triggeractionignored,
+            (evt) => this.emit(evt.name, evt)
+        );
+
         // Listen for track changes
         this._setTrackEvent = new LiveEventTarget<ISetTrackEvent>(
             scope,
@@ -649,6 +691,13 @@ export class LiveMediaSessionCoordinator extends EventEmitter {
             (event, local) =>
                 this._groupState!.handleTransportCommand(event, local)
         );
+        this._rateChangeEvent = new LiveEventTarget(
+            scope,
+            "rateChange",
+            (event: ILiveEvent<IRateChangeCommandEvent>, local) => {
+                this._groupState!.handleRateChangeCommand(event, local);
+            }
+        );
 
         // Listen for position updates
         this._positionUpdateEvent = new LiveEventTarget(

package/src/MediaPlayerSynchronizer.ts

@@ -20,7 +20,7 @@ import {
 import { VolumeManager } from "./VolumeManager";
 import { LiveMediaSession } from "./LiveMediaSession";
 import { IMediaPlayer } from "./IMediaPlayer";
-import { TelemetryEvents } from "./internals";
+import { ITriggerActionEvent, TelemetryEvents } from "./internals";
 import { waitUntilConnected } from "@microsoft/live-share/bin/internals";
 
 /**
@@ -64,6 +64,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         "pause",
         "seekto",
         "settrack",
+        "ratechange",
         "datachange",
         "catchup",
         "wait",
@@ -89,6 +90,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
     private _viewOnly = false;
     private _blockUnexpectedPlayerEvents = true;
     private _expectedPlaybackState: ExtendedMediaSessionPlaybackState = "none";
+    private _expectedPlaybackRate: number = 1.0;
     private _metadata: ExtendedMediaMetadata | null = null;
     private _trackData: object | null = null;
 
@@ -142,7 +144,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
                 playbackState: playbackState,
                 positionState: {
                     position: this._player.currentTime,
-                    playbackRate: this._player.playbackRate,
+                    playbackRate: this._player.playbackRate ?? 1,
                     duration: this._player.duration,
                 },
                 trackData: this._trackData,
@@ -227,22 +229,19 @@ export class MediaPlayerSynchronizer extends EventEmitter {
                     }
                     break;
                 case "ratechange":
-                    // Block rate changes unless suspended.
                     if (
-                        this._player.playbackRate != 1.0 &&
+                        this._blockUnexpectedPlayerEvents &&
+                        this._expectedPlaybackRate !==
+                            this._player.playbackRate &&
                         !this._mediaSession.coordinator.isSuspended
                     ) {
-                        this._logger.sendTelemetryEvent(
-                            TelemetryEvents.MediaPlayerSynchronizer
-                                .PlaybackRateChangeBlocked
-                        );
-                        this._player.playbackRate = 1.0;
+                        this._player.playbackRate = this._expectedPlaybackRate;
                     }
                     break;
                 case "blocked":
                     this._logger.sendTelemetryEvent(
                         TelemetryEvents.MediaPlayerSynchronizer
-                            .PlaybackRateChangeBlocked
+                            .PlayerBlockedOperation
                     );
                     break;
             }
@@ -254,6 +253,13 @@ export class MediaPlayerSynchronizer extends EventEmitter {
             (evt) => this.emit(evt.type, evt)
         );
 
+        this._mediaSession.coordinator.on(
+            MediaSessionCoordinatorEvents.triggeractionignored,
+            (evt: ITriggerActionEvent) => {
+                this.dispatchGroupAction(evt.details, undefined);
+            }
+        );
+
         // Register media session actions
         for (const action of MediaPlayerSynchronizer.SESSION_ACTIONS) {
             this._mediaSession.setActionHandler(
@@ -344,6 +350,22 @@ export class MediaPlayerSynchronizer extends EventEmitter {
                                         .DataChangeAction
                                 );
                                 break;
+                            case "ratechange":
+                                if (!details.playbackRate) {
+                                    break;
+                                }
+
+                                this._logger.sendTelemetryEvent(
+                                    TelemetryEvents.MediaPlayerSynchronizer
+                                        .RateChangeAction,
+                                    null,
+                                    { playbackRate: details.playbackRate }
+                                );
+                                this._expectedPlaybackRate =
+                                    details.playbackRate;
+                                this._player.playbackRate =
+                                    details.playbackRate;
+                                break;
                             case "catchup":
                                 if (typeof details.seekTime == "number") {
                                     this._logger.sendTelemetryEvent(
@@ -401,10 +423,10 @@ export class MediaPlayerSynchronizer extends EventEmitter {
      *
      * @remarks
      * Toggling this value to true results in `mediaSession.coordinator.canPlayPause`,
-     * `mediaSession.coordinator.canSeek`, `mediaSession.coordinator.canSetTrack`, and
-     * `mediaSession.coordinator.canSetTrackData` all being set to false.  For more fine
-     * grained control over the local clients policies, call the `mediaSession.coordinator`
-     * directly.
+     * `mediaSession.coordinator.canSeek`, `mediaSession.coordinator.canSetTrack`,
+     * `mediaSession.coordinator.canSetTrackData`, and `mediaSession.coordinator.canSetPlaybackRate`
+     *  all being set to false.  For more fine grained control over the local clients policies,
+     *  call the `mediaSession.coordinator` directly.
      */
     public get viewOnly(): boolean {
         return this._viewOnly;
@@ -416,6 +438,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this.mediaSession.coordinator.canSeek = !value;
         this.mediaSession.coordinator.canSetTrack = !value;
         this.mediaSession.coordinator.canSetTrackData = !value;
+        this.mediaSession.coordinator.canSetPlaybackRate = !value;
     }
 
     /**
@@ -635,6 +658,24 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         });
     }
 
+    public async setPlaybackRate(playbackRate: number): Promise<void> {
+        this._logger.sendTelemetryEvent(
+            TelemetryEvents.MediaPlayerSynchronizer.RateChangeCalled,
+            null,
+            { playbackRate }
+        );
+
+        await this._mediaSession.coordinator.setPlaybackRate(playbackRate);
+
+        this.dispatchUserAction({
+            action: "ratechange",
+            source: "user",
+            clientId: await waitUntilConnected(this._runtime),
+            local: true,
+            playbackRate,
+        });
+    }
+
     /**
      * Tells the group to change to a new track.
      *
@@ -687,7 +728,6 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         });
     }
 
-    // TODO: what is delay useful for? we do not use, delete?
     private dispatchGroupAction(
         details: ExtendedMediaSessionActionDetails,
         error: Error | undefined

package/src/MediaSessionExtensions.ts

@@ -59,6 +59,10 @@ export enum MediaSessionCoordinatorEvents {
      * 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",
 }
 
 /**
@@ -71,6 +75,7 @@ export enum MediaSessionCoordinatorEvents {
 export type ExtendedMediaSessionAction =
     | MediaSessionAction
     | "settrack"
+    | "ratechange"
     | "wait"
     | "catchup"
     | "datachange"
@@ -116,6 +121,15 @@ export interface ExtendedMediaMetadata extends MediaMetadata {
     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`.
  *
@@ -169,9 +183,11 @@ export interface ExtendedMediaSessionActionDetails {
      */
     data?: object | null;
     /**
-     * Action type that was blocked.
+     * Reason an action is ignored by the local client, undefined if not ignored.
      */
-    blocked?: ExtendedMediaSessionAction | null;
+    ignoreReason?: ExtendedMediaSessionActionIgnore | null;
+
+    playbackRate?: number | null;
 }
 
 /**