@microsoft/live-share-media 0.5.1 → 1.0.0-preview.10

package/src/MediaSessionActionThrottler.ts

@@ -1,14 +1,16 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import { ExtendedMediaSessionActionDetails } from './MediaSessionExtensions';
-
-/**
- * Base class for action throttlers.
- */
-export abstract class MediaSessionActionThrottler {
-    public abstract throttled(details: ExtendedMediaSessionActionDetails, handler?: MediaSessionActionHandler): void;
-}
-
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { ExtendedMediaSessionActionDetails } from "./MediaSessionExtensions";
+
+/**
+ * Base class for action throttlers.
+ */
+export abstract class MediaSessionActionThrottler {
+    public abstract throttled(
+        details: ExtendedMediaSessionActionDetails,
+        handler?: MediaSessionActionHandler
+    ): void;
+}

package/src/MediaSessionExtensions.ts

@@ -1,42 +1,52 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-export interface MediaSessionCoordinatorSuspension {
-    waitPoint?: CoordinationWaitPoint;
-    end(seekTo?: number): void;
-}
-
-export type MediaSessionCoordinatorState = "closed" | "waiting" | "joined";
-
-export enum MediaSessionCoordinatorEvents {
-    coordinatorstatechange = 'coordinatorstatechange',
-    triggeraction = 'triggeraction'
-}
-
-export type ExtendedMediaSessionAction = MediaSessionAction |  "settrack" | "wait" | "catchup" | "datachange" | "blocked";
-
-export type ExtendedMediaSessionPlaybackState = MediaSessionPlaybackState | "suspended" | "waiting" | "ended";
-
-export interface ExtendedMediaMetadata extends MediaMetadata {
-    trackIdentifier: string;
-    liveStream: boolean;
-}
-
-export interface CoordinationWaitPoint {
-    position: number;
-    reason?: string;
-    maxClients?: number;
-}
-
-export interface ExtendedMediaSessionActionDetails  {
-    action: ExtendedMediaSessionAction;
-    fastSeek?: boolean | null;
-    seekOffset?: number | null;
-    seekTime?: number | null;
-    metadata?: ExtendedMediaMetadata | null;
-    suspension?: MediaSessionCoordinatorSuspension | null;
-    data?: object | null;
-    blocked?: ExtendedMediaSessionAction | null;
-}
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+export interface MediaSessionCoordinatorSuspension {
+    waitPoint?: CoordinationWaitPoint;
+    end(seekTo?: number): void;
+}
+
+export type MediaSessionCoordinatorState = "closed" | "waiting" | "joined";
+
+export enum MediaSessionCoordinatorEvents {
+    coordinatorstatechange = "coordinatorstatechange",
+    triggeraction = "triggeraction",
+}
+
+export type ExtendedMediaSessionAction =
+    | MediaSessionAction
+    | "settrack"
+    | "wait"
+    | "catchup"
+    | "datachange"
+    | "blocked";
+
+export type ExtendedMediaSessionPlaybackState =
+    | MediaSessionPlaybackState
+    | "suspended"
+    | "waiting"
+    | "ended";
+
+export interface ExtendedMediaMetadata extends MediaMetadata {
+    trackIdentifier: string;
+    liveStream: boolean;
+}
+
+export interface CoordinationWaitPoint {
+    position: number;
+    reason?: string;
+    maxClients?: number;
+}
+
+export interface ExtendedMediaSessionActionDetails {
+    action: ExtendedMediaSessionAction;
+    fastSeek?: boolean | null;
+    seekOffset?: number | null;
+    seekTime?: number | null;
+    metadata?: ExtendedMediaMetadata | null;
+    suspension?: MediaSessionCoordinatorSuspension | null;
+    data?: object | null;
+    blocked?: ExtendedMediaSessionAction | null;
+}

package/src/RepeatedActionThrottler.ts

@@ -1,56 +1,74 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import { TimeInterval } from '@microsoft/live-share';
-import { MediaSessionActionThrottler } from './MediaSessionActionThrottler';
-import { ExtendedMediaSessionActionDetails, ExtendedMediaSessionAction } from './MediaSessionExtensions';
-
-/**
- *  A Throttler that passes through all actions but will only let an action be repeated once every 2 seconds.
- */
-export class RepeatedActionThrottler extends MediaSessionActionThrottler {
-    private static FILTERED_ACTIONS: ExtendedMediaSessionAction[] = ['play', 'pause', 'seekto', 'catchup'];
-    private _repeatInterval = new TimeInterval(2000);
-    private _lastActionSentTime?: number;
-    private _lastActionSent?: string;
-
-    public get repeatInterval(): number {
-        return this._repeatInterval.seconds;
-    }
-
-    public set repeatInterval(value: number) {
-        this._repeatInterval.seconds = value;
-    }
-
-    public throttled(details: ExtendedMediaSessionActionDetails, handler?: MediaSessionActionHandler): void {
-        if (handler) {
-            if (RepeatedActionThrottler.FILTERED_ACTIONS.indexOf(details.action) >= 0) {
-                const changeKey = this.getChangeKey(details);
-                const now = new Date().getTime();
-                if (this._lastActionSent && changeKey == this._lastActionSent) {
-                    if (now - this._lastActionSentTime! >= this._repeatInterval.milliseconds) {
-                        handler(details as MediaSessionActionDetails);
-                        this._lastActionSentTime = now;
-                    }
-                } else {
-                    handler(details as MediaSessionActionDetails);
-                    this._lastActionSent = changeKey;
-                    this._lastActionSentTime = now;
-                }
-            } else {
-                handler(details as MediaSessionActionDetails);
-            }
-        }
-    }
-
-    private getChangeKey(details: ExtendedMediaSessionActionDetails): string {
-        switch (details.action) {
-            case 'seekto':
-                return `seekto:${details.seekTime}`;
-            default:
-                return details.action;
-        }
-    }
-}
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { TimeInterval } from "@microsoft/live-share";
+import { MediaSessionActionThrottler } from "./MediaSessionActionThrottler";
+import {
+    ExtendedMediaSessionActionDetails,
+    ExtendedMediaSessionAction,
+} from "./MediaSessionExtensions";
+
+/**
+ *  A Throttler that passes through all actions but will only let an action be repeated once every 2 seconds.
+ */
+export class RepeatedActionThrottler extends MediaSessionActionThrottler {
+    private static FILTERED_ACTIONS: ExtendedMediaSessionAction[] = [
+        "play",
+        "pause",
+        "seekto",
+        "catchup",
+    ];
+    private _repeatInterval = new TimeInterval(2000);
+    private _lastActionSentTime?: number;
+    private _lastActionSent?: string;
+
+    public get repeatInterval(): number {
+        return this._repeatInterval.seconds;
+    }
+
+    public set repeatInterval(value: number) {
+        this._repeatInterval.seconds = value;
+    }
+
+    public throttled(
+        details: ExtendedMediaSessionActionDetails,
+        handler?: MediaSessionActionHandler
+    ): void {
+        if (handler) {
+            if (
+                RepeatedActionThrottler.FILTERED_ACTIONS.indexOf(
+                    details.action
+                ) >= 0
+            ) {
+                const changeKey = this.getChangeKey(details);
+                const now = new Date().getTime();
+                if (this._lastActionSent && changeKey == this._lastActionSent) {
+                    if (
+                        now - this._lastActionSentTime! >=
+                        this._repeatInterval.milliseconds
+                    ) {
+                        handler(details as MediaSessionActionDetails);
+                        this._lastActionSentTime = now;
+                    }
+                } else {
+                    handler(details as MediaSessionActionDetails);
+                    this._lastActionSent = changeKey;
+                    this._lastActionSentTime = now;
+                }
+            } else {
+                handler(details as MediaSessionActionDetails);
+            }
+        }
+    }
+
+    private getChangeKey(details: ExtendedMediaSessionActionDetails): string {
+        switch (details.action) {
+            case "seekto":
+                return `seekto:${details.seekTime}`;
+            default:
+                return details.action;
+        }
+    }
+}

package/src/VolumeManager.ts

@@ -0,0 +1,197 @@
+/**
+ * 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

@@ -1,15 +1,14 @@
-/**
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-
-export * from './EphemeralMediaSession';
-export * from './EphemeralMediaSessionCoordinator';
-export * from './EphemeralMediaSessionCoordinatorSuspension';
-export * from './IMediaPlayer';
-export * from './MediaPlayerSynchronizer';
-export * from './MediaSessionActionThrottler';
-export * from './MediaSessionExtensions';
-export * from './RepeatedActionThrottler';
-export * from './VolumeLimiter';
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+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 "./VolumeManager";