@microsoft/live-share-media 0.5.0 → 1.0.0-preview.1

package/src/{EphemeralMediaSession.ts → LiveMediaSession.ts}

@@ -4,23 +4,23 @@
  */
 
 import { DataObject, DataObjectFactory } from '@fluidframework/aqueduct';
-import { EphemeralTelemetryLogger, UserMeetingRole } from '@microsoft/live-share';
+import { LiveTelemetryLogger, UserMeetingRole } from '@microsoft/live-share';
 import { MediaPlayerSynchronizer } from './MediaPlayerSynchronizer';
 import { ITriggerActionEvent, TelemetryEvents } from './internals';
 import { MediaSessionCoordinatorEvents, ExtendedMediaSessionAction, ExtendedMediaSessionActionDetails } from './MediaSessionExtensions';
-import { EphemeralMediaSessionCoordinator, IMediaPlayerState } from './EphemeralMediaSessionCoordinator';
+import { LiveMediaSessionCoordinator, IMediaPlayerState } from './LiveMediaSessionCoordinator';
 import { MediaSessionActionThrottler } from './MediaSessionActionThrottler';
 import { RepeatedActionThrottler } from './RepeatedActionThrottler';
 import { IMediaPlayer } from './IMediaPlayer';
 
 /**
- * Ephemeral fluid object that synchronizes media playback across multiple clients.
+ * Live fluid object that synchronizes media playback across multiple clients.
  */
- export class EphemeralMediaSession extends DataObject {
+ export class LiveMediaSession extends DataObject {
     private _actionThrottler: MediaSessionActionThrottler = new RepeatedActionThrottler();
-    private _logger?: EphemeralTelemetryLogger;
+    private _logger?: LiveTelemetryLogger;
     private _requestPlayerStateHandler?: () => IMediaPlayerState;
-    private _coordinator?: EphemeralMediaSessionCoordinator;
+    private _coordinator?: LiveMediaSessionCoordinator;
     private readonly _actionHandlers: Map<string, MediaSessionActionHandler> = new Map();
     private _synchronizing?: MediaPlayerSynchronizer;
 
@@ -37,8 +37,8 @@ import { IMediaPlayer } from './IMediaPlayer';
      * The objects fluid type factory.
      */
      public static readonly factory = new DataObjectFactory(
-        EphemeralMediaSession.TypeName,
-        EphemeralMediaSession,
+        LiveMediaSession.TypeName,
+        LiveMediaSession,
         [],
         {}
     );
@@ -48,7 +48,7 @@ import { IMediaPlayer } from './IMediaPlayer';
      * local sync behavior.
      * 
      * @remarks
-     * The `EphemeralMediaCoordinator` is fairly aggressive at wanting to keep the local media player 
+     * The `LiveMediaCoordinator` is fairly aggressive at wanting to keep the local media player 
      * in sync with the rest of the group. This aggressiveness can result in the coordinator sending 
      * new sync actions before the local player has finished responding to the previous sync action. 
      * The `ActionThrottler` gives apps fine grain control over how aggressive they want sync to be.
@@ -82,7 +82,7 @@ import { IMediaPlayer } from './IMediaPlayer';
     /**
      * The group coordinator for the session.
      */
-    public get coordinator(): EphemeralMediaSessionCoordinator {
+    public get coordinator(): LiveMediaSessionCoordinator {
         return this._coordinator!;
     }
 
@@ -92,7 +92,7 @@ import { IMediaPlayer } from './IMediaPlayer';
      * @remarks
      * This is used by the `MediaPlayerSynchronizer` to log events.
      */
-    public get logger(): EphemeralTelemetryLogger {
+    public get logger(): LiveTelemetryLogger {
         return this._logger!;
     }
 
@@ -105,16 +105,6 @@ import { IMediaPlayer } from './IMediaPlayer';
         return this.coordinator.initialize(acceptTransportChangesFrom);
     }
 
-    /**
-     * @deprecated initialize should be used instead
-     * initialize the object.
-     * @param acceptTransportChangesFrom Optional. List of roles allowed to group transport 
-     * operations like play/pause/seek/setTrack.
-     */
-    public start(acceptTransportChangesFrom?: UserMeetingRole[]): Promise<void> {
-        return this.initialize(acceptTransportChangesFrom)
-    }
-
     /**
      * Registers an action handler with the session.
      * @param action Name of the action to register a handler for.
@@ -176,10 +166,10 @@ import { IMediaPlayer } from './IMediaPlayer';
     }
 
     protected async hasInitialized(): Promise<void> {
-        this. _logger = new EphemeralTelemetryLogger(this.runtime);
+        this. _logger = new LiveTelemetryLogger(this.runtime);
 
         // Create coordinator and listen for triggered actions
-        this._coordinator = new EphemeralMediaSessionCoordinator(this.runtime, () => this.getCurrentPlayerState());
+        this._coordinator = new LiveMediaSessionCoordinator(this.runtime, () => this.getCurrentPlayerState());
         this._coordinator.on(MediaSessionCoordinatorEvents.triggeraction, (event: ITriggerActionEvent) => {
             // Pre-process actions
             const details = event.details;

package/src/{EphemeralMediaSessionCoordinator.ts → LiveMediaSessionCoordinator.ts}

@@ -3,10 +3,10 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-import { EphemeralEventScope, EphemeralTelemetryLogger, EphemeralEventTarget, IEphemeralEvent, IRuntimeSignaler, TimeInterval, UserMeetingRole } from '@microsoft/live-share';
+import { LiveEventScope, LiveTelemetryLogger, LiveEventTarget, ILiveEvent, IRuntimeSignaler, TimeInterval, UserMeetingRole } from '@microsoft/live-share';
 import { CoordinationWaitPoint, ExtendedMediaSessionActionDetails, ExtendedMediaMetadata, ExtendedMediaSessionPlaybackState, MediaSessionCoordinatorEvents, MediaSessionCoordinatorState, MediaSessionCoordinatorSuspension } from './MediaSessionExtensions';
 import { TelemetryEvents, ITransportCommandEvent, ISetTrackEvent, IPositionUpdateEvent, GroupCoordinatorState, GroupCoordinatorStateEvents, ITriggerActionEvent, ISetTrackDataEvent } from './internals';
-import { EphemeralMediaSessionCoordinatorSuspension } from './EphemeralMediaSessionCoordinatorSuspension';
+import { LiveMediaSessionCoordinatorSuspension } from './LiveMediaSessionCoordinatorSuspension';
 import EventEmitter from "events";
 
 /**
@@ -38,13 +38,13 @@ export interface IMediaPlayerState {
 }
 
 /**
- * The `EphemeralMediaSessionCoordinator` tracks the playback & position state of all other 
+ * The `LiveMediaSessionCoordinator` tracks the playback & position state of all other 
  * clients being synchronized with. It is responsible for keeping the local media player
  * in sync with the group.  
  */
-export class EphemeralMediaSessionCoordinator extends EventEmitter  {
+export class LiveMediaSessionCoordinator extends EventEmitter  {
     private readonly _runtime: IRuntimeSignaler;
-    private readonly _logger: EphemeralTelemetryLogger;
+    private readonly _logger: LiveTelemetryLogger;
     private readonly _getPlayerState: () => IMediaPlayerState;
     private _positionUpdateInterval = new TimeInterval(2000);
     private _maxPlaybackDrift = new TimeInterval(1000);
@@ -52,13 +52,13 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
     private _hasInitialized = false;
 
     // Broadcast events
-    private _playEvent?: EphemeralEventTarget<ITransportCommandEvent>;
-    private _pauseEvent?: EphemeralEventTarget<ITransportCommandEvent>;
-    private _seekToEvent?: EphemeralEventTarget<ITransportCommandEvent>;
-    private _setTrackEvent?: EphemeralEventTarget<ISetTrackEvent>;
-    private _setTrackDataEvent?: EphemeralEventTarget<ISetTrackDataEvent>;
-    private _positionUpdateEvent?: EphemeralEventTarget<IPositionUpdateEvent>;
-    private _joinedEvent?: EphemeralEventTarget<IEphemeralEvent>;
+    private _playEvent?: LiveEventTarget<ITransportCommandEvent>;
+    private _pauseEvent?: LiveEventTarget<ITransportCommandEvent>;
+    private _seekToEvent?: LiveEventTarget<ITransportCommandEvent>;
+    private _setTrackEvent?: LiveEventTarget<ISetTrackEvent>;
+    private _setTrackDataEvent?: LiveEventTarget<ISetTrackDataEvent>;
+    private _positionUpdateEvent?: LiveEventTarget<IPositionUpdateEvent>;
+    private _joinedEvent?: LiveEventTarget<ILiveEvent>;
 
     // Distributed state
     private _groupState?: GroupCoordinatorState;
@@ -70,7 +70,7 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
     constructor(runtime: IRuntimeSignaler, getPlayerState: () => IMediaPlayerState) {
         super();
         this._runtime = runtime;
-        this._logger = new EphemeralTelemetryLogger(runtime);
+        this._logger = new LiveTelemetryLogger(runtime);
         this._getPlayerState = getPlayerState;
     }
 
@@ -177,15 +177,15 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
      */
     public play(): void {
         if (!this._hasInitialized) {
-            throw new Error(`EphemeralMediaSessionCoordinator.play() called before initialize() called.`);
+            throw new Error(`LiveMediaSessionCoordinator.play() called before initialize() called.`);
         }
 
         if (!this._groupState?.playbackTrack.current.metadata) {
-            throw new Error(`EphemeralMediaSessionCoordinator.play() called before MediaSession.metadata assigned.`);
+            throw new Error(`LiveMediaSessionCoordinator.play() called before MediaSession.metadata assigned.`);
         }
 
         if (!this.canPlayPause) {
-            throw new Error(`EphemeralMediaSessionCoordinator.play() operation blocked.`);
+            throw new Error(`LiveMediaSessionCoordinator.play() operation blocked.`);
         }
 
         // Get projected position
@@ -208,15 +208,15 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
      */
     public pause(): void {
         if (!this._hasInitialized) {
-            throw new Error(`EphemeralMediaSessionCoordinator.pause() called before initialize() called.`);
+            throw new Error(`LiveMediaSessionCoordinator.pause() called before initialize() called.`);
         }
 
         if (!this._groupState?.playbackTrack.current.metadata) {
-            throw new Error(`EphemeralMediaSessionCoordinator.pause() called before MediaSession.metadata assigned.`);
+            throw new Error(`LiveMediaSessionCoordinator.pause() called before MediaSession.metadata assigned.`);
         }
 
         if (!this.canPlayPause) {
-            throw new Error(`EphemeralMediaSessionCoordinator.pause() operation blocked.`);
+            throw new Error(`LiveMediaSessionCoordinator.pause() operation blocked.`);
         }
 
         // Get projected position
@@ -240,15 +240,15 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
      */
     public seekTo(time: number): void {
         if (!this._hasInitialized) {
-            throw new Error(`EphemeralMediaSessionCoordinator.seekTo() called before initialize() called.`);
+            throw new Error(`LiveMediaSessionCoordinator.seekTo() called before initialize() called.`);
         }
 
         if (!this._groupState?.playbackTrack.current.metadata) {
-            throw new Error(`EphemeralMediaSessionCoordinator.seekTo() called before MediaSession.metadata assigned.`);
+            throw new Error(`LiveMediaSessionCoordinator.seekTo() called before MediaSession.metadata assigned.`);
         }
 
         if (!this.canSeek) {
-            throw new Error(`EphemeralMediaSessionCoordinator.seekTo() operation blocked.`);
+            throw new Error(`LiveMediaSessionCoordinator.seekTo() operation blocked.`);
         }
 
         // Send transport command
@@ -270,11 +270,11 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
      */
     public setTrack(metadata: ExtendedMediaMetadata|null, waitPoints?: CoordinationWaitPoint[]): void {
         if (!this._hasInitialized) {
-            throw new Error(`EphemeralMediaSessionCoordinator.setTrack() called before initialize() called.`);
+            throw new Error(`LiveMediaSessionCoordinator.setTrack() called before initialize() called.`);
         }
 
         if (!this.canSetTrack) {
-            throw new Error(`EphemeralMediaSessionCoordinator.setTrack() operation blocked.`);
+            throw new Error(`LiveMediaSessionCoordinator.setTrack() operation blocked.`);
         }
 
         // Send transport command
@@ -298,11 +298,11 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
      */
      public setTrackData(data: object|null): void {
         if (!this._hasInitialized) {
-            throw new Error(`EphemeralMediaSessionCoordinator.setTrackData() called before initialize() called.`);
+            throw new Error(`LiveMediaSessionCoordinator.setTrackData() called before initialize() called.`);
         }
 
         if (!this.canSetTrackData) {
-            throw new Error(`EphemeralMediaSessionCoordinator.setTrackData() operation blocked.`);
+            throw new Error(`LiveMediaSessionCoordinator.setTrackData() operation blocked.`);
         }
 
         // Send transport command
@@ -338,11 +338,11 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
      */
     public beginSuspension(waitPoint?: CoordinationWaitPoint): MediaSessionCoordinatorSuspension {
         if (!this._hasInitialized) {
-            throw new Error(`EphemeralMediaSessionCoordinator.beginSuspension() called before initialize() called.`);
+            throw new Error(`LiveMediaSessionCoordinator.beginSuspension() called before initialize() called.`);
         }
 
         if (!this._groupState?.playbackTrack.current.metadata) {
-            throw new Error(`EphemeralMediaSessionCoordinator.beginSuspension() called before MediaSession.metadata assigned.`);
+            throw new Error(`LiveMediaSessionCoordinator.beginSuspension() called before MediaSession.metadata assigned.`);
         }
 
         // Tell group state that suspension is started
@@ -356,7 +356,7 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
         }
 
         // Return new suspension object
-        return new EphemeralMediaSessionCoordinatorSuspension(waitPoint, time => {
+        return new LiveMediaSessionCoordinatorSuspension(waitPoint, time => {
             if (waitPoint) {
                 this._logger.sendTelemetryEvent(TelemetryEvents.SessionCoordinator.EndSuspensionAndWait, null, {position: waitPoint.position, maxClients: waitPoint.maxClients});
             } else {
@@ -384,7 +384,7 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
      */
     public async initialize(acceptTransportChangesFrom?: UserMeetingRole[]): Promise<void> {
         if (this._hasInitialized) {
-            throw new Error(`EphemeralMediaSessionCoordinator.initialize() already initialized.`);
+            throw new Error(`LiveMediaSessionCoordinator.initialize() already initialized.`);
         }
 
         // Create children
@@ -406,7 +406,7 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
      */
     public sendPositionUpdate(state: IMediaPlayerState): void {
         if (!this._hasInitialized) {
-            throw new Error(`EphemeralMediaSessionCoordinator.sendPositionUpdate() called before initialize() called.`);
+            throw new Error(`LiveMediaSessionCoordinator.sendPositionUpdate() called before initialize() called.`);
         }
 
         // Send position update event
@@ -416,29 +416,29 @@ export class EphemeralMediaSessionCoordinator extends EventEmitter  {
     
     protected async createChildren(acceptTransportChangesFrom?: UserMeetingRole[]): Promise<void> {
         // Create event scopes
-        const scope = new EphemeralEventScope(this._runtime, acceptTransportChangesFrom);
-        const unrestrictedScope = new EphemeralEventScope(this._runtime);
+        const scope = new LiveEventScope(this._runtime, acceptTransportChangesFrom);
+        const unrestrictedScope = new LiveEventScope(this._runtime);
 
         // Initialize internal coordinator state
         this._groupState = new GroupCoordinatorState(this._runtime, this._maxPlaybackDrift, this._positionUpdateInterval, this._getPlayerState);
         this._groupState.on(GroupCoordinatorStateEvents.triggeraction, evt => this.emit(evt.name, evt));
 
         // Listen for track changes
-        this._setTrackEvent = new EphemeralEventTarget<ISetTrackEvent>(scope, 'setTrack', (event, local) => this._groupState!.handleSetTrack(event, local));
-        this._setTrackDataEvent = new EphemeralEventTarget<ISetTrackDataEvent>(scope, 'setTrackData', (event, local) => this._groupState!.handleSetTrackData(event, local));
+        this._setTrackEvent = new LiveEventTarget<ISetTrackEvent>(scope, 'setTrack', (event, local) => this._groupState!.handleSetTrack(event, local));
+        this._setTrackDataEvent = new LiveEventTarget<ISetTrackDataEvent>(scope, 'setTrackData', (event, local) => this._groupState!.handleSetTrackData(event, local));
 
         // Listen for transport commands
-        this._playEvent = new EphemeralEventTarget(scope, 'play', (event, local) => this._groupState!.handleTransportCommand(event, local));
-        this._pauseEvent = new EphemeralEventTarget(scope, 'pause', (event, local) => this._groupState!.handleTransportCommand(event, local));
-        this._seekToEvent = new EphemeralEventTarget(scope, 'seekTo', (event, local) => this._groupState!.handleTransportCommand(event, local));
+        this._playEvent = new LiveEventTarget(scope, 'play', (event, local) => this._groupState!.handleTransportCommand(event, local));
+        this._pauseEvent = new LiveEventTarget(scope, 'pause', (event, local) => this._groupState!.handleTransportCommand(event, local));
+        this._seekToEvent = new LiveEventTarget(scope, 'seekTo', (event, local) => this._groupState!.handleTransportCommand(event, local));
 
         // Listen for position updates
-        this._positionUpdateEvent = new EphemeralEventTarget(unrestrictedScope, 'positionUpdate', (event, local) => this._groupState!.handlePositionUpdate(event, local));
+        this._positionUpdateEvent = new LiveEventTarget(unrestrictedScope, 'positionUpdate', (event, local) => this._groupState!.handlePositionUpdate(event, local));
 
         // Listen for joined event
-        this._joinedEvent = new EphemeralEventTarget(unrestrictedScope, 'joined', (evt, local) => {
+        this._joinedEvent = new LiveEventTarget(unrestrictedScope, 'joined', (evt, local) => {
             // Immediately send a position update
-            this._logger.sendTelemetryEvent(TelemetryEvents.SessionCoordinator.RemoteJoinReceived, null, {correlationId: EphemeralTelemetryLogger.formatCorrelationId(evt.clientId, evt.timestamp)});
+            this._logger.sendTelemetryEvent(TelemetryEvents.SessionCoordinator.RemoteJoinReceived, null, {correlationId: LiveTelemetryLogger.formatCorrelationId(evt.clientId, evt.timestamp)});
             const state = this._getPlayerState();
             const update = this._groupState!.createPositionUpdateEvent(state);
             this._positionUpdateEvent?.sendEvent(update);

package/src/{EphemeralMediaSessionCoordinatorSuspension.ts → LiveMediaSessionCoordinatorSuspension.ts}

@@ -5,7 +5,7 @@
 
 import { MediaSessionCoordinatorSuspension, CoordinationWaitPoint } from './MediaSessionExtensions';
 
-export class EphemeralMediaSessionCoordinatorSuspension implements MediaSessionCoordinatorSuspension {
+export class LiveMediaSessionCoordinatorSuspension implements MediaSessionCoordinatorSuspension {
     private _waitPoint?: CoordinationWaitPoint;
     private _onEnd: (seekTo?: number) => void;
 

package/src/MediaPlayerSynchronizer.ts

@@ -3,11 +3,11 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-import { EphemeralTelemetryLogger, IEvent, TimeInterval } from '@microsoft/live-share';
+import { LiveTelemetryLogger, IEvent, TimeInterval } from '@microsoft/live-share';
 import EventEmitter from 'events';
 import { ExtendedMediaSessionAction, ExtendedMediaSessionPlaybackState, ExtendedMediaMetadata, CoordinationWaitPoint, ExtendedMediaSessionActionDetails, MediaSessionCoordinatorEvents, MediaSessionCoordinatorSuspension } from './MediaSessionExtensions';
-import { EphemeralMediaSession } from './EphemeralMediaSession';
-import { VolumeLimiter } from './VolumeLimiter';
+import { VolumeManager } from './VolumeManager';
+import { LiveMediaSession } from './LiveMediaSession';
 import { IMediaPlayer } from './IMediaPlayer';
 import { TelemetryEvents } from './internals';
 
@@ -50,10 +50,10 @@ export class MediaPlayerSynchronizer extends EventEmitter {
     private static SESSION_ACTIONS: ExtendedMediaSessionAction[] = ['play', 'pause', 'seekto', 'settrack', 'datachange', 'catchup', 'wait'];
     private static PLAYER_EVENTS: string[] = ['playing', 'pause', 'ratechange', 'timeupdate', 'ended', 'loadedmetadata', 'blocked'];
 
-    private _logger: EphemeralTelemetryLogger;
+    private _logger: LiveTelemetryLogger;
     private _player: IMediaPlayer;
-    private _mediaSession: EphemeralMediaSession;
-    private _volumeLimiter: VolumeLimiter;
+    private _mediaSession: LiveMediaSession;
+    private _volumeManager: VolumeManager;
     private _onEnd?: () => void;
     private _onPlayerEvent: EventListener;
     private _seekSuspension?: MediaSessionCoordinatorSuspension;
@@ -67,12 +67,12 @@ export class MediaPlayerSynchronizer extends EventEmitter {
      * @param mediaSession Group MediaSession object being used.
      * @param onEnd Optional. Function to call when synchronizers `end()` method is called.
      */
-    constructor(player: IMediaPlayer, mediaSession: EphemeralMediaSession, onEnd: () => void) {
+    constructor(player: IMediaPlayer, mediaSession: LiveMediaSession, onEnd: () => void) {
         super();
         this._player = player;
         this._mediaSession = mediaSession;
         this._logger = mediaSession.logger;
-        this._volumeLimiter = new VolumeLimiter(player);
+        this._volumeManager = new VolumeManager(player);
         this._onEnd = onEnd;
 
         // Listen for player state requests
@@ -124,15 +124,21 @@ export class MediaPlayerSynchronizer extends EventEmitter {
                             this.play();
                         }
                     }
-                    // block play if player state is playing when expected synced state is paused
-                    // needed for YouTube because cannot tell if its a user initiated event, so disallow play (except when starting)
+                    // block play if player state is playing when expected synced state is paused.
+                    // needed because cannot tell if its a user initiated event, so disallow play
                     if (this._expectedPlaybackState === 'paused') {
                         this._player.pause();
                     }
+
+                    // block play if player state is playing when expected synced state is none.
+                    // needed because user who is not in control should not be able to start, so disallow play
+                    if (this._expectedPlaybackState === 'none') {
+                        this._player.pause();
+                    }
                     break;
                 case 'pause':
                     // block pause if player state is paused when expected synced state is playing
-                    // needed for YouTube because cannot tell if its a user initiated event, so disallow pause
+                    // needed because cannot tell if its a user initiated event, so disallow pause
                     if (this._expectedPlaybackState === 'playing') {
                         this._player.play();
                     }
@@ -232,7 +238,7 @@ export class MediaPlayerSynchronizer extends EventEmitter {
     /**
      * Synchronizers media session.
      */
-    public get mediaSession(): EphemeralMediaSession {
+    public get mediaSession(): LiveMediaSession {
         return this._mediaSession;
     }
 
@@ -261,8 +267,8 @@ export class MediaPlayerSynchronizer extends EventEmitter {
     /**
      * Volume limiter used to temporarily reduce the videos volume when someone speaks in a meeting.
      */
-    public get volumeLimiter(): VolumeLimiter {
-        return this._volumeLimiter;
+    public get volumeManager(): VolumeManager {
+        return this._volumeManager;
     }
 
     /**

package/src/VolumeManager.ts

@@ -0,0 +1,185 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { TimeInterval } from '@microsoft/live-share';
+import { IMediaPlayer } from './IMediaPlayer';
+
+export enum LimitLevelType { fixed, percentage }
+
+/**
+ * Smooth audio level changes when volume is modified, or if volume limiting has started/ended.
+ */
+export class VolumeManager {
+    private readonly _player: IMediaPlayer;
+    private readonly _volumeChangeDuration = new TimeInterval(500);
+
+    // defaults to player volume
+    private _volume = 0.0;
+    private _isLimiting = false;
+    private _limitLevel = 0.1
+    private _limitLevelType: LimitLevelType = LimitLevelType.fixed;
+    private _startTime = 0;
+    private _startVolume = 0;
+    private _running = false;
+
+    constructor(player: IMediaPlayer) {
+        this._player = player;
+        this._volume = this._player.volume;
+    }
+
+    /**
+     * The selected volume.
+     *
+     * @remarks
+     * Expressed as a value between 0.0 and 1.0. The default value is 1.0.
+     * Can be used for things like volume sliders.
+     *
+     * Does not return the current volume if limiting is enabled, but the desired volume.
+     */
+    public get volume(): number {
+        return this._volume;
+    }
+
+    public set volume(value: number) {
+        if (value < 0 || value > 1.0) {
+            throw new Error(`VolumeManager: cannot set volume to ${value}. Level must be between 0.0 and 1.0.`);
+        }
+
+        this._volume = value;
+        this.startAdjusting();
+    }
+
+    /**
+     * Target level to lower volume to.
+     *
+     * @remarks
+     * Expressed as a value between 0.0 and 1.0. The value is applied based upon the configured
+     * `levelType`. The default value is 0.1.
+     *
+     * For a level type of `LevelType.fixed` the value is the exact level the volume will be
+     * lowered to. The default value of 0.1 would cause the volume to be lowered to 0.1.
+     *
+     * For a level type of `LevelType.percentage` the value is the percentage by which the volume
+     * level should be lowered to. The default value of 0.1 would cause the volume to be lowered
+     * to 10% of its starting value.
+     */
+    public get limitLevel(): number {
+        return this._limitLevel;
+    }
+
+    public set limitLevel(value: number) {
+        if (value < 0 || value > 1.0) {
+            throw new Error(`VolumeManager: cannot set level to ${value}. Level must be between 0.0 and 1.0.`);
+        }
+
+        this._limitLevel = value;
+    }
+
+    /**
+     * The type of level represented by the `limitLevel` property.
+     */
+    public get limitLevelType(): LimitLevelType {
+        return this._limitLevelType;
+    }
+
+    public set limitLevelType(value: LimitLevelType) {
+        this._limitLevelType = value;
+    }
+
+    /**
+     * Amount of time, in seconds, it should take to change the volume up or down to the desired level.
+     *
+     * @remarks
+     * Default `volumeChangeDuration` is 0.5 seconds.
+     */
+    public get volumeChangeDuration(): number {
+        return this._volumeChangeDuration.seconds;
+    }
+
+    public set volumeChangeDuration(value: number) {
+        this._volumeChangeDuration.seconds = Math.abs(value);
+    }
+
+    /**
+     * Whether or not volume limiting is currently enabled.
+     */
+    public get isLimiting(): boolean {
+        return this._isLimiting;
+    }
+
+    /**
+     * Limits volume based on `limitLevel` and `limitLevelType` properties.
+     * @see `limitLevel`
+     * @see `limitLevelType`
+     */
+    public startLimiting(): void {
+        this._isLimiting = true;
+        this.startAdjusting();
+    }
+
+    /**
+     * Disables volume limit.
+     */
+    public stopLimiting(): void {
+        this._isLimiting = false;
+        this.startAdjusting();
+    }
+
+    private startAdjusting() {
+        const adjustVolume = () => {
+            // Schedule next animation frame if volume change not finished
+            if (this.millisSinceVolumeChangeStart() <= this._volumeChangeDuration.milliseconds) {
+                this._player.volume = this.computeInterpolatedVolume();
+                this.scheduleAnimationFrame(adjustVolume);
+            } else {
+                this._player.volume = this.computeTargetVolume();
+                this._running = false;
+            }
+        }
+
+        this._startTime = new Date().getTime();
+        this._startVolume = this._player.volume;
+        if (!this._running) {
+            this._running = true
+            this.scheduleAnimationFrame(adjustVolume);
+        }
+    }
+
+    private scheduleAnimationFrame(callback: FrameRequestCallback): void {
+        if (typeof requestAnimationFrame == "function") {
+            requestAnimationFrame(callback);
+        } else {
+            setTimeout(callback, 20);
+        }
+    }
+
+    private computeInterpolatedVolume(): number {
+        const volumeChangeMillis = this._volumeChangeDuration.milliseconds
+        const volumeDifference = this.computeTargetVolume() - this._startVolume
+        const adjustmentFromStart = volumeDifference / volumeChangeMillis * this.millisSinceVolumeChangeStart()
+        return this._startVolume + adjustmentFromStart;
+    }
+
+    private computeTargetVolume(): number {
+        if (this._limitLevelType == LimitLevelType.percentage) {
+            if (this._isLimiting) {
+                return this._volume * this._limitLevel;
+            } else {
+                return this._volume;
+            }
+        } else {
+            if (this._isLimiting && this._volume > this._limitLevel) {
+                return this._limitLevel;
+            } else {
+                return this._volume;
+            }
+        }
+    }
+
+    private millisSinceVolumeChangeStart(): number {
+        const now = new Date().getTime();
+        return now - this._startTime;
+    }
+}

package/src/index.ts

@@ -4,12 +4,12 @@
  */
 
 
-export * from './EphemeralMediaSession';
-export * from './EphemeralMediaSessionCoordinator';
-export * from './EphemeralMediaSessionCoordinatorSuspension';
+export * from './LiveMediaSession';
+export * from './LiveMediaSessionCoordinator';
+export * from './LiveMediaSessionCoordinatorSuspension';
 export * from './IMediaPlayer';
 export * from './MediaPlayerSynchronizer';
 export * from './MediaSessionActionThrottler';
 export * from './MediaSessionExtensions';
 export * from './RepeatedActionThrottler';
-export * from './VolumeLimiter';
+export * from './VolumeManager';