@whereby.com/browser-sdk 2.0.0-alpha2 → 2.0.0-alpha20

package/README.md

@@ -1,38 +1,87 @@
 # `@whereby.com/browser-sdk`
 
-> This is a pre-release of the v2 version of this library, adding support for more custom integration using React hooks and plain JavaScript classes in addition to the web component for embedding.
+> This is a pre-release of the v2 version of this library, adding support for
+> more custom integration using React hooks and plain JavaScript classes in
+> addition to the web component for embedding.
 
-Whereby browser SDK is a library for seamless integration of Whereby (https://whereby.com) video calls into your web application.
+Whereby browser SDK is a library for seamless integration of Whereby
+(https://whereby.com) video calls into your web application.
 
 ## Installation
 
-```
+```shell
 npm install @whereby.com/browser-sdk
 ```
+
 or
-```
+
+```shell
 yarn add @whereby.com/browser-sdk
 ```
 
 ## Usage
 
-> In order to make use of this functionality, you must have a Whereby account from which you can create room urls, either [manually or through our API](https://docs.whereby.com/creating-and-deleting-rooms).
+> In order to make use of this functionality, you must have a Whereby account
+> from which you can create room urls, either [manually or through our
+> API](https://docs.whereby.com/creating-and-deleting-rooms).
 
 ### React hooks
 
-The `useRoomConnection` hook provides a way to connect participants in a given room, subscribe to state updates, and perform actions on the connection, like toggling camera or microphone.
+#### useLocalMedia
+
+The `useLocalMedia` hook enables preview and selection of local devices (camera
+& microphone) prior to establishing a connection within a Whereby room. Use
+this hook to build rich pre-call experiences, allowing end users to confirm
+their device selection up-front. This hook works seamlessly with the
+`useRoomConnection` hook described below.
+
+```js
+import { useLocalMedia, VideoView } from "@whereby.com/browser-sdk";
+
+function MyPreCallUX() {
+    const localMedia = useLocalMedia({ audio: false, video: true });
+
+    const { currentCameraDeviceId, cameraDevices, localStream } = localMedia.state;
+    const { setCameraDevice, toggleCameraEnabled } = localMedia.actions;
+
+    return <div className="preCallView">
+        { /* Render any UI, making use of state */ }
+        { cameraDevices.map((d) => (
+            <p
+                key={d.deviceId}
+                onClick={() => {
+                    if (d.deviceId !== currentCameraDeviceId) {
+                        setCameraDevice(d.deviceId);
+                    }
+                }}
+            >
+                {d.label}
+            </p>
+        )) }
+        <VideoView muted stream={localStream} />
+    </div>;
+}
 
 ```
-import { useRoomConnection } from “@whereby.com/browser-sdk”;
+
+#### useRoomConnection
+
+The `useRoomConnection` hook provides a way to connect participants in a given
+room, subscribe to state updates, and perform actions on the connection, like
+toggling camera or microphone.
+
+```js
+import { useRoomConnection } from "@whereby.com/browser-sdk";
 
 function MyCallUX( { roomUrl, localStream }) {
-    const [state, actions, components ] = useRoomConnection(
+    const { state, actions, components } = useRoomConnection(
         "<room_url>"
         {
-                localMediaConstraints: {
+            localMedia: null, // Supply localMedia from `useLocalMedia` hook, or constraints
+            localMediaConstraints: {
                 audio: true,
                 video: true,
-            },
+            }
         }
     );
 
@@ -50,27 +99,50 @@ function MyCallUX( { roomUrl, localStream }) {
 
 ```
 
-### Web component for embedding
+#### Usage with Next.js
 
-Use the `<whereby-embed />` web component to make use of Whereby's pre-built responsive UI. Refer to our [documentation](https://docs.whereby.com/embedding-rooms/in-a-web-page/using-the-whereby-embed-element) to learn which attributes are supported.
+If you are integrating these React hooks with Next.js, you need to ensure your
+custom video experience components are rendered client side, as the underlying
+APIs we use are only available in the browser context. Simply add `"use
+client";` to the top of component, like in the following example:
 
+```js
+"use client";
 
-#### React
+import { VideoView, useLocalMedia } from "@whereby.com/browser-sdk";
 
-```
-import "@whereby.com/browser-sdk"
+export default function MyNextVideoExperience() {
+  const { state, actions } = useLocalMedia({ audio: false, video: true });
 
-const MyComponent = ({ roomUrl }) => {
-    return <whereby-embed chat="off" room={roomUrl} />
+  return (
+    <p>{ state.localStream && <VideoView muted stream={state.localStream} /> }</p>
+  );
 }
 
-export default MyComponent
+```
+
+### Web component for embedding
 
+Use the `<whereby-embed />` web component to make use of Whereby's pre-built
+responsive UI. Refer to our
+[documentation](https://docs.whereby.com/embedding-rooms/in-a-web-page/using-the-whereby-embed-element)
+to learn which attributes are supported.
+
+#### React
+
+```js
+import "@whereby.com/browser-sdk";
+
+const MyComponent = ({ roomUrl }) => {
+    return <whereby-embed chat="off" room={roomUrl} />;
+};
+
+export default MyComponent;
 ```
 
 #### In plain HTML
 
-```
+```html
 <html>
     <head>
         <script src="...."></script>
@@ -85,4 +157,6 @@ export default MyComponent
 
 **Note**
 
-Although we have just higlighted two combinations of how to load and use the web component, it should be possible to use this library with all the major frontend frameworks.
+Although we have just higlighted two combinations of how to load and use the
+web component, it should be possible to use this library with all the major
+frontend frameworks.