@microsoft/live-share-media 0.1.2 → 0.2.0

package/src/MediaPlayerSynchronizer.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import { EphemeralTelemetryLogger, IEvent, TimeInterval } from '@microsoft/live-share';
@@ -11,11 +11,23 @@ import { VolumeLimiter } from './VolumeLimiter';
 import { IMediaPlayer } from './IMediaPlayer';
 import { TelemetryEvents } from './internals';
 
+/**
+ * Event data returned by `MediaPlayerSynchronizer` object.
+ */
 export interface IMediaPlayerSynchronizerEvent extends IEvent {
+    /**
+     * Event details.
+     */
     details: ExtendedMediaSessionActionDetails;
 }
 
+/**
+ * Events supported by `MediaPlayerSynchronizer` object.
+ */
 export enum MediaPlayerSynchronizerEvents {
+    /**
+     * 
+     */
     coordinatorstatechange = 'coordinatorstatechange',
     groupaction = 'groupaction',
     useraction = 'useraction'
@@ -40,7 +52,6 @@ export class MediaPlayerSynchronizer extends EventEmitter {
     private _volumeLimiter: VolumeLimiter;
     private _onEnd?: () => void;
     private _onPlayerEvent: EventListener;
-    private _catchupFastSeekPeriod: TimeInterval = new TimeInterval(0);
     private _seekSuspension?: MediaSessionCoordinatorSuspension;
     private _viewOnly = false;
     private _expectedPlaybackState: ExtendedMediaSessionPlaybackState = 'none';
@@ -61,7 +72,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this._onEnd = onEnd;
 
         // Listen for player state requests
-        mediaSession.onRequestPlayerState = () => {
+        mediaSession.setRequestPlayerStateHandler(() => {
             // Find playback state
             let playbackState: ExtendedMediaSessionPlaybackState;
             const src = this._player.currentSrc || this._player.src;
@@ -87,7 +98,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
             };
 
             return state;
-        }
+        });
 
         // Listen for player events
         this._onPlayerEvent = (evt: Event) => {
@@ -104,7 +115,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
                     // Handle case for YouTube player where user can pause/play video by clicking on it.
                     // - Videos don't always start at 0.0 seconds.
                     if (this._expectedPlaybackState != 'playing') {
-                        if (!this._viewOnly && this._player.currentTime < 1.0) {
+                        if (this._mediaSession.coordinator.canPlayPause && this._player.currentTime < 1.0) {
                             this._logger.sendTelemetryEvent(TelemetryEvents.MediaPlayerSynchronizer.UserTappedVideoToPlay);
                             this.play();
                         }
@@ -185,22 +196,30 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this._logger.sendTelemetryEvent(TelemetryEvents.MediaPlayerSynchronizer.SynchronizationStarted);
     }
 
-    public get catchupFastSeekPeriod(): number {
-        return this._catchupFastSeekPeriod.seconds;
-    }
-
-    public set catchupFastSeekPeriod(value: number) {
-        this._catchupFastSeekPeriod.seconds = value;
-    }
-
+    /**
+     * Media player being synchronized.
+     */
     public get player(): IMediaPlayer {
         return this._player;
     }
 
+    /**
+     * Synchronizers media session.
+     */
     public get mediaSession(): EphemeralMediaSession {
         return this._mediaSession;
     }
 
+    /**
+     * If true the client is in a view only mode.
+     * 
+     * @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.
+     */
     public get viewOnly(): boolean {
         return this._viewOnly;
     }
@@ -209,22 +228,40 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this._viewOnly = value;
         this.mediaSession.coordinator.canPlayPause = !value;
         this.mediaSession.coordinator.canSeek = !value;
+        this.mediaSession.coordinator.canSetTrack = !value;
+        this.mediaSession.coordinator.canSetTrackData = !value;
     }
 
+    /**
+     * Volume limiter used to temporarily reduce the videos volume when someone speaks in a meeting.
+     */
     public get volumeLimiter(): VolumeLimiter {
         return this._volumeLimiter;
     }
 
-    public addEventListener(event: MediaPlayerSynchronizerEvents, listener: () => void): this {
+    /**
+     * Registers a new event listener.
+     * @param event Name of the event to add.
+     * @param listener Function to call when the event is triggered.
+     */
+    public addEventListener(event: MediaPlayerSynchronizerEvents, listener: (evt: IMediaPlayerSynchronizerEvent) => void): this {
         this.on(event, listener);
         return this;
     }
 
-    public removeEventListener(event: MediaPlayerSynchronizerEvents, listener: () => void): this {
+    /**
+     * Un-registers an existing event listener.
+     * @param event Name of the event to remove.
+     * @param listener Function that was registered in call to `addEventListener()`.
+     */
+    public removeEventListener(event: MediaPlayerSynchronizerEvents, listener: (evt: IMediaPlayerSynchronizerEvent) => void): this {
         this.off(event, listener);
         return this;
     }
 
+    /**
+     * Ends synchronization of the current media player.
+     */
     public end(): void {
         if (this._onEnd) {
             try {
@@ -246,6 +283,15 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         }
     }
 
+    /**
+     * Begin a local seek operation.
+     * 
+     * @remarks
+     * UI can call this when a user grabs a timeline scrubber and starts scrubbing the video to a 
+     * new playback position. The synchronizer will being a new suspension which temporarily
+     * disconnects the client for the rest of the group for synchronization purposes. Calling
+     * `endSeek()` will end the suspension and seek the group to the users final seek position.
+     */
     public beginSeek(): void {
         if (this._seekSuspension) {
             throw new Error(`MediaPlayerSynchronizer: cannot begin seek. A seek is already in progress.`);
@@ -255,6 +301,10 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this._seekSuspension = this._mediaSession.coordinator.beginSuspension();
     }
 
+    /**
+     * Ends a seek operation that was started by calling `beginSeek()`.
+     * @param seekTo Playback position in seconds to seek the group to.
+     */
     public endSeek(seekTo: number): void {
         if (!this._seekSuspension) {
             throw new Error(`MediaPlayerSynchronizer: cannot end seek. No seek is in progress.`);
@@ -274,6 +324,13 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this.dispatchUserAction({action: 'seekto', seekTime: seekTo});
     }
 
+    /**
+     * Tells the group to begin playing the current video.
+     * 
+     * @remarks
+     * For proper operation apps should avoid calling `mediaSession.coordinator.play()` directly 
+     * and instead use the synchronizers `play()` method.  
+     */
     public play(): void {
         this._logger.sendTelemetryEvent(TelemetryEvents.MediaPlayerSynchronizer.PlayCalled);
         this._expectedPlaybackState = 'playing';
@@ -282,6 +339,13 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this.dispatchUserAction({action: 'play'});
     }
 
+    /**
+     * Tells the group to pause the current video.
+     * 
+     * @remarks
+     * For proper operation apps should avoid calling `mediaSession.coordinator.pause()` directly 
+     * and instead use the synchronizers `pause()` method.  
+     */
     public pause(): void {
         this._logger.sendTelemetryEvent(TelemetryEvents.MediaPlayerSynchronizer.PauseCalled);
         this._expectedPlaybackState = 'paused';
@@ -290,6 +354,13 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this.dispatchUserAction({action: 'pause'});
     }
 
+    /**
+     * Tells the group to seek the current video to a new playback position.
+     * 
+     * @remarks
+     * For proper operation apps should avoid calling `mediaSession.coordinator.seekTo()` directly 
+     * and instead use the synchronizers `seekTo()` method.  
+     */
     public seekTo(time: number): void {
         // Always seek player to new time.
         // - This resolves an issue where the timeline scrubber can temporarily snap back to the original
@@ -302,6 +373,13 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this.dispatchUserAction({action: 'seekto', seekTime: time});
     }
 
+    /**
+     * Tells the group to change to a new track.
+     * 
+     * @remarks
+     * For proper operation apps should avoid calling `mediaSession.coordinator.setTrack()` directly 
+     * and instead use the synchronizers `setTrack()` method.  
+     */
     public setTrack(track: ExtendedMediaMetadata, waitPoints?: CoordinationWaitPoint[]): void {
         this._logger.sendTelemetryEvent(TelemetryEvents.MediaPlayerSynchronizer.SetTrackCalled);
         this._mediaSession.coordinator.setTrack(track, waitPoints);
@@ -309,6 +387,13 @@ export class MediaPlayerSynchronizer extends EventEmitter {
         this.dispatchUserAction({action: 'settrack', metadata: track});
     }
 
+    /**
+     * Updates the current tracks data object.
+     * 
+     * @remarks
+     * For proper operation apps should avoid calling `mediaSession.coordinator.setTrackData()` directly 
+     * and instead use the synchronizers `setTrackData()` method.  
+     */
     public setTrackData(data: object|null): void {
         this._logger.sendTelemetryEvent(TelemetryEvents.MediaPlayerSynchronizer.SetTrackDataCalled);
         this._trackData = data;
@@ -334,23 +419,6 @@ export class MediaPlayerSynchronizer extends EventEmitter {
     }
 
     private async catchupPlayer(time: number): Promise<void> {
-        // Only fast seek if:
-        // - more then 2 seconds behind.
-        // - fast seek hasn't been disabled.
-        // - the current playback rate is 1.0.
-        if (time >= (this._player.currentTime + 2.0) && this.catchupFastSeekPeriod > 0 && this._player.playbackRate == 1.0) {
-            // Fast seek to new position
-            const suspension = await this._mediaSession.coordinator.beginSuspension();
-            const seekPeriod = Math.min(time - this._player.currentTime, this.catchupFastSeekPeriod);
-            const startTime = time - seekPeriod;
-            this._player.currentTime = startTime;
-            this._player.playbackRate = 4.0;
-            setTimeout(async () => {
-                this._player.playbackRate = 1.0;
-                await suspension.end();
-            }, (seekPeriod * 0.25) * 1000)
-        } else {
-            this._player.currentTime = time;
-        }
+        this._player.currentTime = time;
     }
 }

package/src/MediaSessionActionThrottler.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import { ExtendedMediaSessionActionDetails } from './MediaSessionExtensions';

package/src/MediaSessionExtensions.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 export interface MediaSessionCoordinatorSuspension {

package/src/RepeatedActionThrottler.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import { TimeInterval } from '@microsoft/live-share';

package/src/VolumeLimiter.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
  import { TimeInterval } from '@microsoft/live-share';
@@ -33,7 +33,7 @@ export class VolumeLimiter {
      * Time, in seconds, that the volume should be lowered.
      * 
      * @remarks
-     * Applications should periodically call `lowerVolume()` to keep teh volume lowered. 
+     * Applications should periodically call `lowerVolume()` to keep the volume lowered. 
      */
     public get duration(): number {
         return this._duration.seconds;

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 

package/src/internals/GroupCoordinatorState.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import { IEvent, IEphemeralEvent, EphemeralEvent, TimeInterval, IRuntimeSignaler, EphemeralTelemetryLogger } from '@microsoft/live-share';

package/src/internals/GroupPlaybackPosition.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import { EphemeralEvent, IRuntimeSignaler, TimeInterval } from '@microsoft/live-share';

package/src/internals/GroupPlaybackTrack.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import { IEvent } from '@microsoft/live-share';

package/src/internals/GroupPlaybackTrackData.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import { IEvent } from '@microsoft/live-share';

package/src/internals/GroupTransportState.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import { IEvent, EphemeralEvent } from '@microsoft/live-share';

package/src/internals/consts.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 /**

package/src/internals/index.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 export * from './consts';

package/src/test/GroupPlaybackPosition.spec.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import 'mocha';

package/src/test/GroupPlaybackTrack.spec.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import 'mocha';

package/src/test/SharedMediaSession.spec.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import 'mocha';

package/src/test/SharedMediaSessionCoordinator.spec.ts

@@ -1,6 +1,6 @@
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 
 import 'mocha';