diff --git a/docs/tutorials/common/_starting-jellyfish-backend.mdx b/docs/tutorials/common/_starting-jellyfish-media-server.mdx similarity index 88% rename from docs/tutorials/common/_starting-jellyfish-backend.mdx rename to docs/tutorials/common/_starting-jellyfish-media-server.mdx index 5ce034a5..a6368db1 100644 --- a/docs/tutorials/common/_starting-jellyfish-backend.mdx +++ b/docs/tutorials/common/_starting-jellyfish-media-server.mdx @@ -1,4 +1,4 @@ -For testing, we'll run the backend locally using Docker image: +For testing, we'll run the Jellyfish Media Server locally using Docker image: ```bash docker run -p 50000-50050:50000-50050/udp \ @@ -14,7 +14,7 @@ docker run -p 50000-50050:50000-50050/udp \ ghcr.io/jellyfish-dev/jellyfish:0.1.0-5e95d59 ``` -Make sure to set `INTEGRATED_TURN_IP` and `VIRTUAL_HOST` to your local IP address. Without it, the mobile device won't be able to connect to the backend. +Make sure to set `INTEGRATED_TURN_IP` and `VIRTUAL_HOST` to your local IP address. Without it, the mobile device won't be able to connect to the Jellyfish. :::tip diff --git a/docs/tutorials/dashboard.mdx b/docs/tutorials/dashboard.mdx new file mode 100644 index 00000000..81d8485d --- /dev/null +++ b/docs/tutorials/dashboard.mdx @@ -0,0 +1,169 @@ +--- +title: Jellyfish Dashboard +--- + +import { ImageWrapper } from "./ImageWrapper"; +import StartingJellyfishMediaServer from "./common/_starting-jellyfish-media-server.mdx"; +import StartingJellyfishDashboard from "./common/_starting-dashboard.mdx"; + +# The Whats and Hows of Jellyfish Dashboard + +## What is Jellyfish Dashboard? + +Jellyfish Dashboard is a web application that allows you to manage your Jellyfish Media Server instance. +It is a React application that uses the [Jellyfish React Client API](https://github.com/jellyfish-dev/react-client-sdk) +for adding and receiving tracks and [Jellyfish Server API](https://github.com/jellyfish-dev/jellyfish/blob/main/openapi.yaml) +for adding peers, creating rooms etc. + +It was created to help Jellyfish developers in testing but was later extended and adapted as a tool for tutorials and demos. +Here, we present a short introduction to the dashboard and its features. + +## How to start Jellyfish Dashboard? + + + +## How to start Jellyfish Media Server? + + + +## How to use Jellyfish Dashboard? + +Since we have Dashboard and Jellyfish Media Server up and running, we can dive into +the features. + +### Connecting to the server + +We started the dashboard and the Jellyfish Media Server separately, so we need to connect them. + +1. Open the dashboard in your browser. Open the side menu and fill in the parameters: + +![Dashboard server connection](/img/tutorials/dashboard/dashboard_server.png) + +- **Server token** - a token necessary to authenticate the dashboard with the Jellyfish. For now, it's simply `development`, +but it is meant to authenticate the dashboard to the Jellyfish, so the good practice is to use a token that is hard to guess. +- **WS/WSS** - whether to use a secure or insecure connection. , it's `ws`, but if the Jellyfish uses secure WebSocket, use `wss`. +- **HTTP/HTTPS** - whether to use a secure or insecure connection. By default, it's `http`, but if the Jellyfish uses secure HTTP, use `https`. +- **Server URL** - URL of the Jellyfish server. Here, `localhost:5002` would be a local build, but it can be any URL that points to the Jellyfish. +- **Socket Path** - path to the WebSocket endpoint. The default value is `/socket/peer/websocket`. + +2. Click **Connect to server**. If everything is correct, a server will appear in the list of connected servers: + +![Connected dashboard](/img/tutorials/dashboard/dashboard_connected.png) + +### Creating a room + +There are plenty of settings that You can adjust in a room: + +![Adding Room](/img/tutorials/dashboard/dashboard_add_room.png) + +- **h264 or vp8** - video codec used in the room. If you want to use `HLS` streaming, you need to use `h264`. +- **Max Peers** - maximum number of peers that can join to the room. + +When you select the settings, click the **Add room** button. If everything is correct, a room will appear in the list of rooms: + +![Room added](/img/tutorials/dashboard/dashboard_room_added.png) + +### Adding and connecting peers to the room + +Using the **Create peer** button, you can create a peer that will be ready to connect to the room. + +![Peer created](/img/tutorials/dashboard/dashboard_peer_created.png) + +The peer has its `ID` and `Token`. +The `ID` is used to identify the peer in the Jellyfish Server, and the `Token` is used to authenticate the peer with the Jellyfish Server. + +Dashboard has an option to copy both of those values to the clipboard. +You can also create a QR code with the peer's `Token` to make connecting to Jellyfish with a mobile device easier. + +![Peer copied](/img/tutorials/dashboard/dashboard_peer_copied.png) + +To connect the peer to the room, you can either press the **Connect** button in the peer's row, or scan the QR code with your mobile app, and connect there. + +### Sending tracks + +When the peer connects to the room, you will see the track menu. +It allows you to send tracks to the room. + +![Track menu](/img/tutorials/dashboard/dashboard_track_menu.png) + +You can select the _audio or video tracks_ you want to send to the room. +Apart from your camera/microphone, there is an option to pick one from a list of _mock tracks_ that we prepared. + +You can also select the _resolution_ of the video track or if you want, send the video as a _simulcast_ stream. + +There is also an option to add custom _metadata_ (in JSON format) to the track. +The peer will send metadata with the track to the room. Each recipient will be able to see it. + +When you select the track, click the **Add track** button. +If everything is correct, client will send the track to the room and other peers will be able to see and hear you. + +### Receiving tracks + +When the peer connects to the room, it will automatically receive tracks from other peers. + +**Congrats! The basic utils of the dashboard are now covered. Next, we will dive into useful features that will help you with testing.** + +## A ton of information that the dashboard provides + +### Server logs in console + + +On the side menu, you can set up the dashboard to display React Client logs in the console. +Logs are great for debugging purposes and provide insight into the various communications that occur between the dashboard and the Jellyfish Server. +You can also register your event handlers in your Jellyfish-based projects, both in the +[React Client SDK](https://github.com/jellyfish-dev/react-client-sdk) and the[TS Client SDK](https://github.com/jellyfish-dev/ts-client-sdk). +These logs can show you when particular events occur and provide data that you can use in your own handlers + + + + + +### Server/Room/Client state + +Each server, room, and client has its state. You can see the state of each of them in the dashboard by clicking appropriate buttons. + +![Server state](/img/tutorials/dashboard/dashboard_states.png) + +### Server events + +Apart from the state, you can also see the events that occur on the server. + +You can see them after clicking the **Show Server Events** button. + +![Server events](/img/tutorials/dashboard/dashboard_server_events.png) + +## HLS and RTSP streaming + +The dashboard allows adding HLS and RTSP streams in the room. +You can set up the streams and see them in the room. It will look like this: + +![HLS and RTSP](/img/tutorials/dashboard/dashboard_hls_rtsp.png) + +## Loadbalancing in Dashboard + +Jellyfish Server supports load balancing. +This means you can run multiple instances of the server and use them simultaneously to distribute the load evenly among them. +The dashboard reflects this feature. +If you run multiple Jellyfish instances (which [Docker Compose](https://github.com/jellyfish-dev/jellyfish/blob/main/docker-compose.yaml) does by default), +connect one server to the dashboard. +When a server opens a room on a different instance, the Dashboard will automatically connect to it and display the room. +When Jellyfish runs in a cluster, and the Dashboard requests a new room, it's created on the Jellyfish instance with the lowest load. +Information about the specific Jellyfish instance that hosts the newly created room is returned in the HTTP response body. + +## Summary + +Congrats on finishing the tutorial! You should now be able to use the dashboard to its full potential. + +But this was just the beginning. +Jellyfish Client API is a powerful tool that allows you to create your own web or mobile multimedia application. +Check out the other tutorials to learn more about the Jellyfish Client API and how to use it in your projects. + +You can also take a look at our fully featured [Videoroom Demo example](https://github.com/jellyfish-dev/react-native-membrane-webrtc/tree/master/example): + + + +It's written in React Native, but it uses the same Jellyfish Client API as the dashboard, so you can learn a lot from it. diff --git a/docs/tutorials/minimal-working-example-react.mdx b/docs/tutorials/minimal-working-example-react.mdx index 64ee1840..3ac9b895 100644 --- a/docs/tutorials/minimal-working-example-react.mdx +++ b/docs/tutorials/minimal-working-example-react.mdx @@ -4,7 +4,7 @@ title: React import { ImageWrapper } from "./ImageWrapper"; import JellyfishArchitecture from "./common/_jellyfish-architecture.mdx"; -import StartingJellyfishBackend from "./common/_starting-jellyfish-backend.mdx"; +import StartingJellyfishBackend from "./common/_starting-jellyfish-media-server.mdx"; import StartingJellyfishDashboard from "./common/_starting-dashboard.mdx"; # React Minimal Working Example diff --git a/sidebars.js b/sidebars.js index 02a70d21..eff52d45 100644 --- a/sidebars.js +++ b/sidebars.js @@ -59,6 +59,7 @@ const sidebars = { collapsible: true, collapsed: false, items: [ + "tutorials/dashboard", { type: 'category', label: 'Minimal Working Examples', diff --git a/static/img/tutorials/dashboard/dashboard_add_room.png b/static/img/tutorials/dashboard/dashboard_add_room.png new file mode 100644 index 00000000..1f200a11 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_add_room.png differ diff --git a/static/img/tutorials/dashboard/dashboard_connected.png b/static/img/tutorials/dashboard/dashboard_connected.png new file mode 100644 index 00000000..499a40d5 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_connected.png differ diff --git a/static/img/tutorials/dashboard/dashboard_hls_rtsp.png b/static/img/tutorials/dashboard/dashboard_hls_rtsp.png new file mode 100644 index 00000000..5138460b Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_hls_rtsp.png differ diff --git a/static/img/tutorials/dashboard/dashboard_peer_copied.png b/static/img/tutorials/dashboard/dashboard_peer_copied.png new file mode 100644 index 00000000..64200546 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_peer_copied.png differ diff --git a/static/img/tutorials/dashboard/dashboard_peer_created.png b/static/img/tutorials/dashboard/dashboard_peer_created.png new file mode 100644 index 00000000..3b85786b Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_peer_created.png differ diff --git a/static/img/tutorials/dashboard/dashboard_room_added.png b/static/img/tutorials/dashboard/dashboard_room_added.png new file mode 100644 index 00000000..13ab4397 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_room_added.png differ diff --git a/static/img/tutorials/dashboard/dashboard_server.png b/static/img/tutorials/dashboard/dashboard_server.png new file mode 100644 index 00000000..7e2ef6e8 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_server.png differ diff --git a/static/img/tutorials/dashboard/dashboard_server_events.png b/static/img/tutorials/dashboard/dashboard_server_events.png new file mode 100644 index 00000000..f6db7ff9 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_server_events.png differ diff --git a/static/img/tutorials/dashboard/dashboard_server_logs.png b/static/img/tutorials/dashboard/dashboard_server_logs.png new file mode 100644 index 00000000..15f1e4a9 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_server_logs.png differ diff --git a/static/img/tutorials/dashboard/dashboard_states.png b/static/img/tutorials/dashboard/dashboard_states.png new file mode 100644 index 00000000..11d718d2 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_states.png differ diff --git a/static/img/tutorials/dashboard/dashboard_track_menu.png b/static/img/tutorials/dashboard/dashboard_track_menu.png new file mode 100644 index 00000000..10eec454 Binary files /dev/null and b/static/img/tutorials/dashboard/dashboard_track_menu.png differ