@microsoft/live-share-media 0.1.2 → 0.2.2

package/.vscode/settings.json

@@ -0,0 +1,2 @@
+{
+}

package/LICENSE

@@ -0,0 +1,87 @@
+MICROSOFT SOFTWARE LICENSE TERMS 
+
+MICROSOFT LIVE SHARE SDK – PRE-RELEASE VERSION 
+________________________________________
+
+These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW.  BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS. 
+
+1. INSTALLATION AND USE RIGHTS.  
+	a) General. You may install and use any number of copies of the software to develop and test your applications, solely for the purpose stated in 1(b) below and otherwise for your internal business purposes. 
+	b) Purpose. The use of this license provided under these terms is specifically limited to developing applications that interact solely within the Microsoft Teams Ecosystem. You may distribute the software according to Section 3 of these terms.  
+	c) Third Party Components. The software may include third party components with separate legal notices or governed by other agreements, as may be described in the ThirdPartyNotices file(s) accompanying the software. 
+	d) Microsoft Terms of Use. Some features of the software provide access to, or rely on, online services. The use of those services (but not the software) is governed by separate terms. This includes the Microsoft APIs Terms of Use which can be found at https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use and the Supplemental Terms of Use for Microsoft Azure which can be found at https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms. Please read them. The services may not be available in all regions. 
+
+2. PRE-RELEASE SOFTWARE.  The software is a pre-release version, and comes with no warranties as provided under Section 13.  It may not operate correctly.  We may change or discontinue the software at any time without notice.  We may also choose not to make this software generally commercially available.  It may be different from the commercially released version.  
+
+3. DISTRIBUTABLE CODE. The software contains code you are permitted to distribute (i.e. make available for third parties) in applications you develop, as described in this Section.  
+	a) Distribution Rights. The code and test files are distributable if included with the software.  
+		i. Third Party Distribution. You may permit distributors of your applications to copy and distribute any of this distributable code you elect to distribute with your applications. 
+	b) Distribution Requirements. For any code you distribute, you must: 
+		i. adhere to the Purpose stated in Section 1(b); and  
+		ii. indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your applications, except to the extent that any claim is based solely on the unmodified distributable code. 
+	c) Distribution Restrictions. You may not: 
+		i. use Microsoft’s trademarks or trade dress in your application in any way that suggests your application comes from or is endorsed by Microsoft; or 
+		ii. modify or distribute the source code of any distributable code so that any part of it becomes subject to any license that requires that the distributable code, any other part of the software, or any of Microsoft’s other intellectual property be disclosed or distributed in source code form, or that others have the right to modify it. 
+
+4. SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to): 
+	a) remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software;software; 
+	b) use the software in any way that is against the law or to create or propagate malware; or 
+	c) share, publish, distribute, or lease the software (except for any distributable code, subject to the terms above), provide the software as a stand-alone offering for others to use, or transfer the software or this agreement to any third party. 
+
+5. Data Protection. There are also some features in the software that may enable you to collect data from users of your applications. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to and obtaining consent from users of your applications. You can learn more about data collection and use in the help documentation and the privacy statement at https://aka.ms/privacy. Your use of the software operates as your consent to these practices.  
+
+6. CODE OF CONDUCT. By agreeing to these license terms, you’re agreeing that, when using the software, you will follow these rules: 
+	a) Don’t do anything illegal.
+	b) Don’t engage in any activity that exploits, harms, or threatens to harm children.  
+	c) Don’t send spam. Spam is unwanted or unsolicited bulk email, postings, contact requests, SMS (text messages), or instant messages.
+	d) Don’t publicly display or use the software to share inappropriate content or material (involving, for example, nudity, bestiality, pornography, offensive language, graphic violence, or criminal activity).  
+	e) Don’t engage in activity that is fraudulent, false or misleading (e.g., asking for money under false pretenses, impersonating someone else, manipulating the software to increase play count, or affect rankings, ratings, or comments). 
+	f) Don’t circumvent any restrictions on access to or availability of the software. 
+	g) Don’t engage in activity that is harmful to you, the software, or others (e.g., transmitting viruses, stalking, posting terrorist content, communicating hate speech, or advocating violence against others). 
+	h) Don’t infringe upon the rights of others (e.g., unauthorized sharing of copyrighted music or other copyrighted material, resale or other distribution of Bing maps, or photographs). 
+	i) Don’t engage in activity that violates the privacy of others. 
+	j) Don’t help others break these rules. 
+
+7. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit https://aka.ms/exporting. 
+
+8. SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind. 
+
+9. ENTIRE AGREEMENT. This agreement, terms referenced herein, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software.  
+
+10. APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles, except that the FAA governs everything related to arbitration. If you acquired the software in any other country, its laws apply, except that the FAA governs everything related to arbitration. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court (excluding arbitration). If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court (excluding arbitration). 
+
+11. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you: 
+	a. Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights. 
+	b. Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software. 
+	c. Germany and Austria. 
+		• Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software. 
+		• Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law. 
+		• Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence. 
+
+12. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. 
+
+13. PRE-RELEASE DISCLAIMER. AS A PRE-RELEASE VERSION, THIS SOFTWARE AND UNDERLYING SERVICES, ARE PROVIDED "AS-IS," "WITH ALL FAULTS," AND "AS AVAILABLE," AND ARE EXCLUDED FROM THE SERVICE LEVEL AGREEMENTS AND LIMITED WARRANTY. Pre-release versions may not be covered by customer support, and may be subject to reduced or different security, compliance and privacy commitments, as further explained in the Microsoft Privacy Statement, Microsoft Azure Trust Center, the Product Terms, the DPA, and any additional notices provided with the software. Where applicable, the following terms in the DPA do not apply to Previews: Processing of Personal Data; GDPR, Data Security.  
+
+14. LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT, OR INCIDENTAL DAMAGES. 
+
+	This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law. 
+	
+	It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages. 
+	
+	Please note: As this software is distributed in Canada, some of the clauses in this agreement are provided below in French. 
+
+	Remarque: Ce logiciel étant distribué au Canada, certaines des clauses dans ce contrat sont fournies ci-dessous en français. 
+
+	EXONÉRATION DE GARANTIE. Le logiciel visé par une licence est offert « tel quel ». Toute utilisation de ce logiciel est à votre seule risque et péril. Microsoft n’accorde aucune autre garantie expresse. Vous pouvez bénéficier de droits additionnels en vertu du droit local sur la protection des consommateurs, que ce contrat ne peut modifier. La ou elles sont permises par le droit locale, les garanties implicites de qualité marchande, d’adéquation à un usage particulier et d’absence de contrefaçon sont exclues. 
+
+	LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES DOMMAGES. Vous pouvez obtenir de Microsoft et de ses fournisseurs une indemnisation en cas de dommages directs uniquement à hauteur de 5,00 $ US. Vous ne pouvez prétendre à aucune indemnisation pour les autres dommages, y compris les dommages spéciaux, indirects ou accessoires et pertes de bénéfices. 
+
+	Cette limitation concerne: 
+
+	•	tout ce qui est relié au logiciel, aux services ou au contenu (y compris le code) figurant sur des sites Internet tiers ou dans des programmes tiers; et 
+
+	•	les réclamations au titre de violation de contrat ou de garantie, ou au titre de responsabilité stricte, de négligence ou d’une autre faute dans la limite autorisée par la loi en vigueur. 
+
+	Elle s’applique également, même si Microsoft connaissait ou devrait connaître l’éventualité d’un tel dommage. Si votre pays n’autorise pas l’exclusion ou la limitation de responsabilité pour les dommages indirects, accessoires ou de quelque nature que ce soit, il se peut que la limitation ou l’exclusion ci-dessus ne s’appliquera pas à votre égard. 
+
+	EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques. Vous pourriez avoir d’autres droits prévus par les lois de votre pays. Le présent contrat ne modifie pas les droits que vous confèrent les lois de votre pays si celles-ci ne le permettent pas. 

package/README.md

@@ -1,10 +1,30 @@
-# Typescript Teams Collaboration SDK
+# Microsoft Live Share Media
 
-This will be the future home of the TypeScript SDK. For now, enjoy some contracts for the communication protocol!
+Easily add media synchronization to your Teams meeting app, powered by [Fluid Framework](https://fluidframework.com/).
 
-# Building SDK
+This package is an extension of Microsoft Live Share, and requires the `@microsoft/live-share` extension. You can find it on NPM [here](https://www.npmjs.com/package/@microsoft/live-share).
 
-Navigate to the `/javascript` folder and perform:
+You can find our API reference documentation at [aka.ms/livesharedocs](https://aka.ms/livesharedocs).
+
+## Installing
+
+To add the latest version of the SDK to your application using NPM:
+
+```bash
+npm install @microsoft/live-share --save
+npm install @microsoft/live-share-media --save
+```
+
+or using [Yarn](https://yarnpkg.com/):
+
+```bash
+yarn add @microsoft/live-share
+yarn add @microsoft/live-share-media
+```
+
+## Building package
+
+After cloning the [GitHub repository](https://www.github.com/microsoft/live-share-sdk), navigate to the root folder and perform:
 
 ```bash
 npm install --legacy-peer-dep
@@ -13,98 +33,104 @@ npm run build
 
 This will use lerna to hoist and build all dependencies.
 
-## Basic implementation example
-
-3PP App gets loaded with:
-
-> https://3ppApp.com/playback#teamsCollab=1&teamsCollabToken=eyasdfasdf&teamsCollabSpaceId=call_asdf-asdf-asdf-asdfasdfasd
-
-```typescript
-let mediaPlayer = <yourCode>.player;
-// Get an SDK instance based on a URI or token provided to you
-let collab = CollaborationSDK.initializeFromUri(window.location.origin);
-// let isAuth = await collab.auth.isAuthenticated();
-// let collab = CollaborationSDK.initializeWithToken(keychain.token);
-
-// // Can potentially be removed if we do this check as part of setupSessionHandler.
-// let userState = await collab.getUserState();
-// // internally we do collab.collabSpaceId = userState.collabSpaceId
-// if (!userState) {
-//     // Stop here, no need to connect
-//     // You can check again later with the same sdk instance
-//     return;
-// }
-
-// Connect to the Collab Session.
-let sessionHandler = await collab.setupSessionHandler();
-
-// set up an event listener for session change to connect if a new session gets initiated
-sessionHandler.on('sessionStart', newSession => appSetupSession(newSession));
-sessionHandler.on('sessionEnd', session => appEndSession(session));
-
-let sessions = sessionHandler.getAllSessionsForApp();
-if (session.length === 0) {
-    // No session active, either wait for sessionStart or create a new session right now
-    let session = sessionHandler.createMediaSession(); // A. send post to cloud api to say session has been created; B. SessionCreated event on PPS socket
-    setupSession(session);
-} else {
-    let mediaSession = sessions.find(session => session.type === 'mediaSession');
-    let dataSession = sessions.find(session => session.type === 'dataSession');
-    setupSession(mediaSession, mediaPlayer);
-}
-
-function setupSession(session, mediaPlayer) {
-    const mediaState = session.getState();
-    mediaPlayer.load(mediaState.url);
-
-    // Handle a Collaboration events
-    session.setActionHandler('play', (data, isSelf) => {
-        if (!isSelf) {
-            mediaPlayer.play();
-        }
-    });
-    session.setActionHandler('seek', data => {
-        mediaPlayer.seekTo(data.timestamp);
-    });
-
-    // Handle mediaPlayer events
-    mediaPlayer.on('pause', () => {
-        session.postEvent('pause');
-    });
-    mediaPlayer.on('play', () => {
-        session.postEvent('play');
-    });
-    mediaPlayer.on('positionUpdate', position => {
-        session.setPositionState({ position });
-    });
-}
+## How to use this extension
+
+```html
+<body>
+  <video id="player">
+    <source src="YOUR_VIDEO_SRC" type="video/mp4" />
+  </video>
+  <div class="player-controls">
+    <button id="play-button">Play</button>
+    <button id="pause-button">Pause</button>
+    <button id="restart-button">Restart</button>
+    <button id="change-track-button">Change track</button>
+  </div>
+</body>
 ```
 
-## Custom Activity handler example
+```javascript
+import * as microsoftTeams from "@microsoft/teams-js";
+import { TeamsFluidClient } from "@microsoft/live-share";
+import { EphemeralMediaSession } from "@microsoft/live-share-media";
+
+// Initialize the Teams Client SDK
+await microsoftTeams.app.initialize();
+
+// Setup the Fluid container
+const client = new TeamsFluidClient();
+const schema = {
+  initialObjects: {
+    mediaSession: EphemeralMediaSession,
+    ...,
+  },
+};
+const { container } = await client.joinContainer(schema);
+const { mediaSession } = container.initialObjects;
+
+// Get the player from your document and create synchronizer
+const player = document.getElementById("player");
+const synchronizer = mediaSession.synchronize(player);
+
+// Define roles you want to allow playback control and start sync
+const allowedRoles = ["Organizer", "Presenter"];
+await mediaSession.start(allowedRoles);
+
+// Intercept user play, pause, seek, and set track actions through synchronizer
+
+document.getElementById("play-button").onclick = () => {
+  synchronizer.play();
+};
+
+document.getElementById("pause-button").onclick = () => {
+  synchronizer.pause();
+};
+
+document.getElementById("restart-button").onclick = () => {
+  synchronizer.seekTo(0);
+};
+
+document.getElementById("change-track-button").onclick = () => {
+  synchronizer.setTrack({
+    trackIdentifier: "SOME_OTHER_VIDEO_SRC",
+  });
+};
+```
 
-```typescript
-async function someCustomCode() {
-  class JamysActivitySession implements IActivitySession<StateDataType> {
-    // Custom code here
-  }
+## Code samples
 
-  let sdk: ICollaborationSDK;
-  sdk.defineSessionType("jamysActivitySession", JamysActivitySession);
-  const sessionHandler = await sdk.connectToSession();
+There are several code samples that are hosted in a separate GitHub repository.
 
-  // On client A
-  sessionHandler.createSession<JamysActivitySession>("jamysActivitySession");
+| Sample name          | Description                                                                                                                               | Javascript                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| React Video          | Basic example showing how the EphemeralMediaSession object works with HTML5 video.                                                        | [View](https://aka.ms/liveshare-reactvideo)    |
+| React Media Template | Enable all connected clients to watch videos together, build a shared playlist, transfer whom is in control, and annotate over the video. | [View](https://aka.ms/liveshare-mediatemplate) |
 
-  // on Client B if out of band from receiving the sessionChange
-  sessionHandler.getCurrentSession<JamysActivitySession>(
-    "jamysActivitySession"
-  );
+## Package Compatibility
 
-  // On client C which handles a sessionChange event
-  sessionHandler.on("sessionChange", (event) => {
-    if (event.type === "jamysActivitySession") {
-      const jSession = event.session as JamysActivitySession;
-    }
-  });
-}
-```
+The Live Share SDK contains dependencies for [@microsoft/teams-js](https://www.npmjs.com/package/@microsoft/teams-js) and [fluid-framework](https://www.npmjs.com/package/fluid-framework) packages among others. Both of these packages are sensitive to the package version your app any libraries use. You will likely run into issues if the package version your app uses doesn't match the version other libraries you depend on use.
+
+**It is critical that your app use the package dependencies listed in the table below.** Lookup the version of the `@microsoft/live-share` you're using and set any other dependencies in your package.json file to match:
+
+| @microsoft/live-share | @microsoft/teams-js  | fluid-framework | @microsoft/live-share-media | @fluidframework/test-client-utils |
+| --------------------- | -------------------- | --------------- | --------------------------- | --------------------------------- |
+| ~0.2.1                | 2.0.0-experimental.0 | ~0.59.0         | ~0.2.1 (optional)           | ~0.59.0 (optional)                |
+
+## Contributing
+
+There are several ways you can [contribute](../../CONTRIBUTING.md) to this project:
+
+- [Submit bugs](https://github.com/microsoft/live-share-sdk/issues) and help us verify fixes as they are checked in.
+- Review the source code changes.
+- Engage with other Live Share developers on [StackOverflow](https://stackoverflow.com/questions/tagged/live-share).
+- [Contribute bug fixes](../../CONTRIBUTING.md).
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact opencode@microsoft.com with any additional questions or comments.
+
+## Reporting Security Issues
+
+Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the [MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/default).
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Licensed under a special [Microsoft](../../LICENSE) License.

package/bin/EphemeralMediaSession.d.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 { DataObject, DataObjectFactory } from '@fluidframework/aqueduct';
 import { EphemeralTelemetryLogger, UserMeetingRole } from '@microsoft/live-share';
@@ -9,10 +9,13 @@ import { ExtendedMediaSessionAction } from './MediaSessionExtensions';
 import { EphemeralMediaSessionCoordinator, IMediaPlayerState } from './EphemeralMediaSessionCoordinator';
 import { MediaSessionActionThrottler } from './MediaSessionActionThrottler';
 import { IMediaPlayer } from './IMediaPlayer';
+/**
+ * Ephemeral fluid object that synchronizes media playback across multiple clients.
+ */
 export declare class EphemeralMediaSession extends DataObject {
     private _actionThrottler;
     private _logger?;
-    private _onRequestPlayerState?;
+    private _requestPlayerStateHandler?;
     private _coordinator?;
     private readonly _actionHandlers;
     private _synchronizing?;
@@ -26,16 +29,60 @@ export declare class EphemeralMediaSession extends DataObject {
      * The objects fluid type factory.
      */
     static readonly factory: DataObjectFactory<EphemeralMediaSession, import("@fluidframework/aqueduct").DataObjectTypes>;
-    protected hasInitialized(): Promise<void>;
+    /**
+     * Extension point that lets applications replace the default logic for throttling the sessions
+     * local sync behavior.
+     *
+     * @remarks
+     * The `EphemeralMediaCoordinator` 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.
+     *
+     * By default, a `RepeatedAction` throttler is used which prevents the same sync action from
+     * being sent within an adjustable time period.
+     */
     get actionThrottler(): MediaSessionActionThrottler;
     set actionThrottler(value: MediaSessionActionThrottler);
+    /**
+     * Returns true if the object has been started.
+     */
     get isStarted(): boolean;
+    /**
+     * The group coordinator for the session.
+     */
     get coordinator(): EphemeralMediaSessionCoordinator;
-    set onRequestPlayerState(handler: () => IMediaPlayerState);
+    /**
+     * Returns the logger used by the session and coordinator.
+     *
+     * @remarks
+     * This is used by the `MediaPlayerSynchronizer` to log events.
+     */
     get logger(): EphemeralTelemetryLogger;
+    /**
+     * Starts the object.
+     * @param acceptTransportChangesFrom Optional. List of roles allowed to group transport
+     * operations like play/pause/seek/setTrack.
+     */
     start(acceptTransportChangesFrom?: UserMeetingRole[]): Promise<void>;
+    /**
+     * Registers an action handler with the session.
+     * @param action Name of the action to register a handler for.
+     * @param handler Function called when the action is triggered.
+     */
     setActionHandler(action: ExtendedMediaSessionAction, handler: MediaSessionActionHandler | null): void;
+    /**
+     * Registers a handler that will be queried anytime the group coordinate needs to know the
+     * local players transport state and position.
+     */
+    setRequestPlayerStateHandler(handler: () => IMediaPlayerState): void;
+    /**
+     * Begins synchronizing the playback of a media element.
+     * @param player Something that "looks like" and HTML Media Element.
+     * @returns A new synchronizer instance. Call `synchronizer.end()` to stop synchronizing the elements playback.
+     */
     synchronize(player: IMediaPlayer): MediaPlayerSynchronizer;
+    protected hasInitialized(): Promise<void>;
     private checkWaitPointHit;
     private getCurrentPlayerState;
     private dispatchAction;

package/bin/EphemeralMediaSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EphemeralMediaSession.d.ts","sourceRoot":"","sources":["../src/EphemeralMediaSession.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,OAAO,EAAiC,0BAA0B,EAAqC,MAAM,0BAA0B,CAAC;AACxI,OAAO,EAAE,gCAAgC,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACzG,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,qBAAa,qBAAsB,SAAQ,UAAU;IACjD,OAAO,CAAC,gBAAgB,CAA8D;IACtF,OAAO,CAAC,OAAO,CAAC,CAA2B;IAC3C,OAAO,CAAC,qBAAqB,CAAC,CAA0B;IACxD,OAAO,CAAC,YAAY,CAAC,CAAmC;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqD;IACrF,OAAO,CAAC,cAAc,CAAC,CAA0B;IAGjD,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,eAAe,CAAa;IAEpC;;OAEG;IACF,gBAAuB,QAAQ,+CAA+C;IAE/E;;OAEG;IACF,gBAAuB,OAAO,+FAK7B;cAEc,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAuC/C,IAAW,eAAe,IAAI,2BAA2B,CAExD;IAED,IAAW,eAAe,CAAC,KAAK,EAAE,2BAA2B,EAE5D;IAED,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED,IAAW,WAAW,IAAI,gCAAgC,CAEzD;IAED,IAAW,oBAAoB,CAAC,OAAO,EAAE,MAAM,iBAAiB,EAE/D;IAED,IAAW,MAAM,IAAI,wBAAwB,CAE5C;IAEY,KAAK,CAAC,0BAA0B,CAAC,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1E,gBAAgB,CAAC,MAAM,EAAE,0BAA0B,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,IAAI;IAWrG,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,uBAAuB;IA+BjE,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,cAAc;CAMzB"}
+{"version":3,"file":"EphemeralMediaSession.d.ts","sourceRoot":"","sources":["../src/EphemeralMediaSession.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,OAAO,EAAiC,0BAA0B,EAAqC,MAAM,0BAA0B,CAAC;AACxI,OAAO,EAAE,gCAAgC,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACzG,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;GAEG;AACF,qBAAa,qBAAsB,SAAQ,UAAU;IAClD,OAAO,CAAC,gBAAgB,CAA8D;IACtF,OAAO,CAAC,OAAO,CAAC,CAA2B;IAC3C,OAAO,CAAC,0BAA0B,CAAC,CAA0B;IAC7D,OAAO,CAAC,YAAY,CAAC,CAAmC;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqD;IACrF,OAAO,CAAC,cAAc,CAAC,CAA0B;IAGjD,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,eAAe,CAAa;IAEpC;;OAEG;IACF,gBAAuB,QAAQ,+CAA+C;IAE/E;;OAEG;IACF,gBAAuB,OAAO,+FAK7B;IAEF;;;;;;;;;;;;OAYG;IACH,IAAW,eAAe,IAAI,2BAA2B,CAExD;IAED,IAAW,eAAe,CAAC,KAAK,EAAE,2BAA2B,EAE5D;IAED;;OAEG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;OAEG;IACH,IAAW,WAAW,IAAI,gCAAgC,CAEzD;IAED;;;;;OAKG;IACH,IAAW,MAAM,IAAI,wBAAwB,CAE5C;IAED;;;;OAIG;IACU,KAAK,CAAC,0BAA0B,CAAC,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjF;;;;OAIG;IACI,gBAAgB,CAAC,MAAM,EAAE,0BAA0B,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,IAAI;IAW5G;;;OAGG;IACI,4BAA4B,CAAC,OAAO,EAAE,MAAM,iBAAiB;IAIpE;;;;OAIG;IACI,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,uBAAuB;cA+BjD,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAuC/C,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,cAAc;CAMzB"}

package/bin/EphemeralMediaSession.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
+ * Licensed under the Microsoft Live Share SDK License.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -21,6 +21,9 @@ const internals_1 = require("./internals");
 const MediaSessionExtensions_1 = require("./MediaSessionExtensions");
 const EphemeralMediaSessionCoordinator_1 = require("./EphemeralMediaSessionCoordinator");
 const RepeatedActionThrottler_1 = require("./RepeatedActionThrottler");
+/**
+ * Ephemeral fluid object that synchronizes media playback across multiple clients.
+ */
 class EphemeralMediaSession extends aqueduct_1.DataObject {
     constructor() {
         super(...arguments);
@@ -28,67 +31,61 @@ class EphemeralMediaSession extends aqueduct_1.DataObject {
         this._actionHandlers = new Map();
         this._lastUpdateTime = 0;
     }
-    hasInitialized() {
-        return __awaiter(this, void 0, void 0, function* () {
-            this._logger = new live_share_1.EphemeralTelemetryLogger(this.runtime);
-            // Create coordinator and listen for triggered actions
-            this._coordinator = new EphemeralMediaSessionCoordinator_1.EphemeralMediaSessionCoordinator(this.runtime, () => this.getCurrentPlayerState());
-            this._coordinator.on(MediaSessionExtensions_1.MediaSessionCoordinatorEvents.triggeraction, (event) => {
-                // Pre-process actions
-                const details = event.details;
-                const seekTime = typeof details.seekTime == 'number' ? details.seekTime : -1;
-                switch (details.action) {
-                    case 'play':
-                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.PlayAction, null, { position: seekTime });
-                        break;
-                    case 'pause':
-                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.PauseAction, null, { position: seekTime });
-                        break;
-                    case 'seekto':
-                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.SeekToAction, null, { position: seekTime });
-                        break;
-                    case 'settrack':
-                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.SetTrackAction);
-                        break;
-                    case 'datachange':
-                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.DataChangeAction);
-                        break;
-                    case 'catchup':
-                        // Default to seekto if catchup not implemented
-                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.CatchUpAction, null, { position: seekTime });
-                        if (!this._actionHandlers.has('catchup')) {
-                            details.action = 'seekto';
-                        }
-                        break;
-                }
-                // Dispatch action
-                this.dispatchAction(details);
-            });
-        });
-    }
+    /**
+     * Extension point that lets applications replace the default logic for throttling the sessions
+     * local sync behavior.
+     *
+     * @remarks
+     * The `EphemeralMediaCoordinator` 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.
+     *
+     * By default, a `RepeatedAction` throttler is used which prevents the same sync action from
+     * being sent within an adjustable time period.
+     */
     get actionThrottler() {
         return this._actionThrottler;
     }
     set actionThrottler(value) {
         this._actionThrottler = value;
     }
+    /**
+     * Returns true if the object has been started.
+     */
     get isStarted() {
         return this.coordinator.isStarted;
     }
+    /**
+     * The group coordinator for the session.
+     */
     get coordinator() {
         return this._coordinator;
     }
-    set onRequestPlayerState(handler) {
-        this._onRequestPlayerState = handler;
-    }
+    /**
+     * Returns the logger used by the session and coordinator.
+     *
+     * @remarks
+     * This is used by the `MediaPlayerSynchronizer` to log events.
+     */
     get logger() {
         return this._logger;
     }
+    /**
+     * Starts the object.
+     * @param acceptTransportChangesFrom Optional. List of roles allowed to group transport
+     * operations like play/pause/seek/setTrack.
+     */
     start(acceptTransportChangesFrom) {
         return __awaiter(this, void 0, void 0, function* () {
             this.coordinator.start(acceptTransportChangesFrom);
         });
     }
+    /**
+     * Registers an action handler with the session.
+     * @param action Name of the action to register a handler for.
+     * @param handler Function called when the action is triggered.
+     */
     setActionHandler(action, handler) {
         if (handler) {
             // add handler
@@ -99,6 +96,18 @@ class EphemeralMediaSession extends aqueduct_1.DataObject {
             this._actionHandlers.delete(action);
         }
     }
+    /**
+     * Registers a handler that will be queried anytime the group coordinate needs to know the
+     * local players transport state and position.
+     */
+    setRequestPlayerStateHandler(handler) {
+        this._requestPlayerStateHandler = handler;
+    }
+    /**
+     * Begins synchronizing the playback of a media element.
+     * @param player Something that "looks like" and HTML Media Element.
+     * @returns A new synchronizer instance. Call `synchronizer.end()` to stop synchronizing the elements playback.
+     */
     synchronize(player) {
         // A session can only synchronize one player at a time
         if (this._synchronizing) {
@@ -125,6 +134,44 @@ class EphemeralMediaSession extends aqueduct_1.DataObject {
             this._synchronizing = undefined;
         });
     }
+    hasInitialized() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this._logger = new live_share_1.EphemeralTelemetryLogger(this.runtime);
+            // Create coordinator and listen for triggered actions
+            this._coordinator = new EphemeralMediaSessionCoordinator_1.EphemeralMediaSessionCoordinator(this.runtime, () => this.getCurrentPlayerState());
+            this._coordinator.on(MediaSessionExtensions_1.MediaSessionCoordinatorEvents.triggeraction, (event) => {
+                // Pre-process actions
+                const details = event.details;
+                const seekTime = typeof details.seekTime == 'number' ? details.seekTime : -1;
+                switch (details.action) {
+                    case 'play':
+                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.PlayAction, null, { position: seekTime });
+                        break;
+                    case 'pause':
+                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.PauseAction, null, { position: seekTime });
+                        break;
+                    case 'seekto':
+                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.SeekToAction, null, { position: seekTime });
+                        break;
+                    case 'settrack':
+                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.SetTrackAction);
+                        break;
+                    case 'datachange':
+                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.DataChangeAction);
+                        break;
+                    case 'catchup':
+                        // Default to seekto if catchup not implemented
+                        this.logger.sendTelemetryEvent(internals_1.TelemetryEvents.MediaSession.CatchUpAction, null, { position: seekTime });
+                        if (!this._actionHandlers.has('catchup')) {
+                            details.action = 'seekto';
+                        }
+                        break;
+                }
+                // Dispatch action
+                this.dispatchAction(details);
+            });
+        });
+    }
     checkWaitPointHit(state) {
         // Was a wait point hit?
         if (state.positionState && this.coordinator.isStarted) {
@@ -141,10 +188,10 @@ class EphemeralMediaSession extends aqueduct_1.DataObject {
         }
     }
     getCurrentPlayerState() {
-        if (!this._onRequestPlayerState) {
+        if (!this._requestPlayerStateHandler) {
             throw new Error(`SharedMediaSession: no getPlayerState callback configured.`);
         }
-        return this._onRequestPlayerState();
+        return this._requestPlayerStateHandler();
     }
     dispatchAction(details) {
         if (this._actionHandlers.has(details.action)) {