Skip to main content
Version: 0.20.0

Livestreaming using WHIP/WHEP

tip

Make sure to read Livestreaming with Fishjam before reading this guide. This guide focuses on a low-level way to communicate with Fishjam.

The majority of use-cases should prefer to use the methods described in Livestreaming with Fishjam.

If you've reading this guide, it is more than likely that you've already heard of WHIP (WebRTC HTTP Ingress Protocol) and WHEP (WebRTC HTTP Egress Protocol). If not, then we recommend to read our article about WHIP/WHEP. In short, these are two protocols which standardize real-time livestreaming. This prevents vendor lock-in and allows implementations and solutions to be reused in different scenarios.

Fishjam supports both WHIP and WHEP, so you can choose how to publish and receive streams. For example, you can use OBS Studio to publish a livestream with WHIP and then receive the stream using any public online WHEP player you like.

WHIP with Fishjam​

WHIP is the protocol used by streamers to start publishing. To use WHIP you need two things:

  1. The URL of an HTTP endpoint implementing the WHIP specification.
  2. A token, used by the endpoint to authorize the streamer.

Getting the URL​

Fishjam's WHIP endpoint is available at

https://fishjam.io/api/v1/live/api/whip

You can paste this URL in your WHIP client of choice to start streaming.

Getting the token​

To authenticate a streamer, you need to first create a room of type livestream and a streamer token for that room. You can read about this in detail in Production Livestreaming with Server SDKs, but the TL;DR is

import { FishjamClient } from '@fishjam-cloud/js-server-sdk';

const fishjamClient = new FishjamClient({
    fishjamId,
    managementToken,
});

const room = await fishjamClient.createRoom({ roomType: 'livestream' });
const { token: streamerToken } = await fishjamClient.createLivestreamStreamerToken(room.id);

The created streamer token must be supplied in the HTTP headers of the WHIP request:

POST https://fishjam.io/api/v1/live/api/whip
Authorization: Bearer [STREAMER-TOKEN]

WHEP with Fishjam​

WHEP is the protocol used by viewers to start receiving a published livestream. The usage of WHEP is very similar to WHIP, as you need the following:

  1. The URL of an HTTP endpoint implementing the WHEP specification.
  2. (Optional) A token, used by the endpoint to authorize the viewer.

With Fishjam, if the livestream is private, then the token is required. On the other hand, if the livestream is public, then the token is omitted.

Private vs Public Livestreams explains private and public livestreams in more detail. In this guide we demonstrate how to view each livestream type using WHEP directly.

Private livestreams​

Getting the URL​

For private livestreams, Fishjam's WHEP endpoint is available at

https://fishjam.io/api/v1/live/api/whep

You can paste this URL in your WHEP client of choice to start viewing.

Getting the token​

To authenticate a viewer, you need to create a viewer token for a room of livestream type. You can read about this in detail in Production Livestreaming with Server SDKs, but the TL;DR is

import { FishjamClient } from '@fishjam-cloud/js-server-sdk';

const fishjamClient = new FishjamClient({
  fishjamId,
  managementToken,
});

const room = await fishjamClient.createRoom({ roomType: 'livestream', public: false });

// ...

const { token: viewerToken } = await fishjamClient.createLivestreamViewerToken(room.id);

The created viewer token must be supplied in the HTTP headers of the WHEP request:

POST https://fishjam.io/api/v1/live/api/whep
Authorization: Bearer [VIEWER-TOKEN]

Public livestreams​

For public livestreams, you don't need a token, however you still need a room of livestream type with the public flag enabled.

const room = await fishjamClient.createRoom({ roomType: 'livestream', public: true });
// now you can use room.id to start viewing

Once you have such a room, you can view a stream published to that room by supplying the following URL:

http://fishjam.io/api/v1/live/api/whep/[ROOM-ID]

See also​

More on livestreaming:

If livestreaming doesn't fit your use case: