@microsoft/live-share-media 1.4.0 → 1.4.2

package/bin/cjs/LiveMediaSessionCoordinator.d.ts

@@ -0,0 +1,304 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+import { UserMeetingRole } from "@microsoft/live-share";
+import { IRuntimeSignaler, LiveShareRuntime } from "@microsoft/live-share/internal";
+import { CoordinationWaitPoint, ExtendedMediaMetadata, ExtendedMediaSessionPlaybackState, MediaSessionCoordinatorSuspension } from "./MediaSessionExtensions.js";
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import { IEvent } from "@fluidframework/core-interfaces";
+/**
+ * Most recent state of the media session.
+ */
+export interface IMediaPlayerState {
+    /**
+     * Metadata for the sessions current track.
+     */
+    metadata: ExtendedMediaMetadata | null;
+    /**
+     * Optional track data object being synchronized.
+     *
+     * @remarks
+     * This can be used to sync things like pitch, roll, and yaw when watching 360 videos together.
+     */
+    trackData: object | null;
+    /**
+     * Sessions current playback state.
+     */
+    playbackState: ExtendedMediaSessionPlaybackState;
+    /**
+     * Sessions current position state if known.
+     */
+    positionState?: MediaPositionState;
+}
+/**
+ * @hidden
+ */
+export interface ILiveMediaSessionCoordinatorEvents extends IEvent {
+    /**
+     * Event listener for events emitted
+     * @param event update
+     * @param listener listener function
+     * @param listener.event the event instance
+     */
+    (event: string, listener: (event: any) => void): void;
+}
+/**
+ * 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 declare class LiveMediaSessionCoordinator extends TypedEventEmitter<ILiveMediaSessionCoordinatorEvents> {
+    private readonly _id;
+    private readonly _runtime;
+    private readonly _liveRuntime;
+    private readonly _logger;
+    private readonly _getPlayerState;
+    private _positionUpdateInterval;
+    private _maxPlaybackDrift;
+    private _lastWaitPoint?;
+    private initializeState;
+    private _playEvent?;
+    private _pauseEvent?;
+    private _seekToEvent?;
+    private _rateChangeEvent?;
+    private _setTrackEvent?;
+    private _setTrackDataEvent?;
+    private _positionUpdateEvent?;
+    private _synchronizer?;
+    private _groupState?;
+    /**
+     * @hidden
+     * Applications shouldn't directly create new coordinator instances.
+     */
+    constructor(id: string, runtime: IRuntimeSignaler, liveRuntime: LiveShareRuntime, getPlayerState: () => IMediaPlayerState);
+    /**
+     * Controls whether or not the local client is allowed to instruct the group to play or pause.
+     *
+     * @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 play/pause media, you should use "role based verification" to enforce those policies.
+     */
+    canPlayPause: boolean;
+    /**
+     * Controls whether or not the local client is allowed to seek the group to a new playback
+     * position.
+     *
+     * @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 playback position, you should use "role based verification" to enforce those policies.
+     */
+    canSeek: boolean;
+    /**
+     * Controls whether or not the local client is allowed to change tracks.
+     *
+     * @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 tracks, you should use "role based verification" to enforce those policies.
+     */
+    canSetTrack: boolean;
+    /**
+     * Controls whether or not the local client is allowed to change the tracks custom data object.
+     *
+     * @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.
+     */
+    canSetTrackData: boolean;
+    /**
+     * 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.
+     */
+    canSetPlaybackRate: boolean;
+    /**
+     * Controls whether or not the local client is allowed to send position updates to the group.
+     *
+     * @remarks
+     * This flag largely meant to limit the number of signals sent to the group for performance reasons.
+     * It does not provide any security in itself.
+     */
+    canSendPositionUpdates: boolean;
+    /**
+     * Returns true if the local client is in a suspended state.
+     */
+    get isSuspended(): boolean;
+    /**
+     * Controls whether or not to scale {@link maxPlaybackDrift} by the number of users in the session.
+     *
+     * @remarks
+     * As more clients join a session, it is more likely that some users will fall behind the presenter.
+     * It is also less likely that users will notice drift as more clients are added.
+     * It is usually helpful to be more lenient as more clients are added so everyone can watch all the content.
+     * Default value is true.
+     */
+    get shouldScaleMaxPlaybackDrift(): boolean;
+    set shouldScaleMaxPlaybackDrift(value: boolean);
+    /**
+     * Max amount of playback drift allowed in seconds.
+     * This will scale automatically according to the number of participants in the session when {@link shouldScaleMaxPlaybackDrift} is true.
+     *
+     * @remarks
+     * Should the local clients playback position lag by more than the specified value, the coordinator will trigger a `catchup` action.
+     * Default value is `1.5` seconds.
+     */
+    get maxPlaybackDrift(): number;
+    set maxPlaybackDrift(value: number);
+    /**
+     * Controls whether or not to compute {@link positionUpdateInterval} based on whether user has initiated a playback command.
+     * Default value is true.
+     *
+     * @remarks
+     * When true, users that are simply watching but not controlling playback will report their positions less frequently.
+     * When a user has sent a transport command, they will begin sending position updates more frequently.
+     * Most Live Share apps have a concept of a primary presenter, and don't allow anyone to pause/play for the group.
+     * By ensuring only one/few users broadcast updates frequently, the server load is reduced considerably.
+     */
+    get shouldScalePositionUpdateInterval(): boolean;
+    set shouldScalePositionUpdateInterval(value: boolean);
+    /**
+     * Frequency with which position updates are broadcast to the rest of the group in seconds.
+     * When {@link shouldScalePositionUpdateInterval} is set to `true`, the value set is the minimum value.
+     * The value returned is the actual value used to send updates by the local user, which may be larger than the value set.
+     *
+     * @remarks
+     * Defaults to a minimum value of `2` seconds.
+     */
+    get positionUpdateInterval(): number;
+    set positionUpdateInterval(value: number);
+    /**
+     * Instructs the group to play the current track.
+     *
+     * @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
+     */
+    play(): Promise<void>;
+    /**
+     * Instructs the group to pause the current track.
+     *
+     * @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
+     */
+    pause(): Promise<void>;
+    /**
+     * Instructs the group to seek to a new position within the current track.
+     *
+     * @remarks
+     * 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
+     */
+    seekTo(time: number): Promise<void>;
+    /**
+     * Sets the playback rate for everyone in the session.
+     *
+     * @param playbackRate the playback rate to set.
+     *
+     * @throws
+     * Throws an exception if the session/coordinator hasn't been initialized or {@link canSetPlaybackRate} is false.
+     */
+    setPlaybackRate(playbackRate: number): Promise<void>;
+    /**
+     * Instructs the group to load a new track.
+     *
+     * @remarks
+     * Throws an exception if the session/coordinator hasn't been initialized or `canSetTrack` is
+     * 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
+     */
+    setTrack(metadata: ExtendedMediaMetadata | null, waitPoints?: CoordinationWaitPoint[]): Promise<void>;
+    /**
+     * Updates the track data object for the current track.
+     *
+     * @remarks
+     * The track data object can be used by applications to synchronize things like pitch, roll,
+     * and yaw of a 360 video. This data object will be reset to null anytime the track changes.
+     *
+     * 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
+     */
+    setTrackData(data: object | null): Promise<void>;
+    /**
+     * Begins a new local suspension.
+     *
+     * @remarks
+     * Suspension temporarily suspend the clients local synchronization with the group. This can
+     * be useful for displaying ads to users or temporarily disconnecting from the session while
+     * the user seeks the video using a timeline scrubber.
+     *
+     * Multiple simultaneous suspensions are allowed and when the last suspension ends the local
+     * client will be immediately re-synchronized with the group.
+     *
+     * A "Dynamic Wait Point" can be specified when `beginSuspension()` is called and the wait
+     * point will be broadcast to all other clients in the group.  Those clients will then
+     * automatically enter a suspension state once they reach the positions specified by the
+     * wait point. Clients that are passed the wait point will immediately suspend.
+     *
+     * Any wait point based suspension (dynamic or static) will result in all clients remaining
+     * in a suspension state until the list client ends their suspension. This behavior can be
+     * conditionally bypassed by settings the wait points `maxClients` value.
+     *
+     * Throws an exception if the session/coordinator hasn't been initialized.
+     * @param waitPoint Optional. Dynamic wait point to broadcast to all of the clients.
+     * @returns The suspension object. Call `end()` on the returned suspension to end the suspension.
+     */
+    beginSuspension(waitPoint?: CoordinationWaitPoint): MediaSessionCoordinatorSuspension;
+    /**
+     * @hidden
+     * Called by MediaSession to verify the coordinator has been initialized.
+     */
+    get isInitialized(): boolean;
+    /**
+     * @hidden
+     * Called by MediaSession to start coordinator.
+     */
+    initialize(acceptTransportChangesFrom?: UserMeetingRole[]): Promise<void>;
+    /**
+     * @hidden
+     * Called by the MediaSession to detect if a wait point has been hit.
+     */
+    findNextWaitPoint(): CoordinationWaitPoint | null;
+    /**
+     * @hidden
+     * Called by MediaSession to trigger the sending of a position update.
+     */
+    sendPositionUpdate(state: IMediaPlayerState, targetClientId?: string): void;
+    protected createChildren(acceptTransportChangesFrom?: UserMeetingRole[]): Promise<void>;
+    private getPlayerPosition;
+}
+//# sourceMappingURL=LiveMediaSessionCoordinator.d.ts.map

package/bin/cjs/LiveMediaSessionCoordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LiveMediaSessionCoordinator.d.ts","sourceRoot":"","sources":["../../src/LiveMediaSessionCoordinator.ts"],"names":[],"mappings":"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"}