Live streaming

A live stream is a channel where a small number of people publish and everyone else only watches. The split is decided by the role your server puts in each token, not by anything the client asks for.

Hosts and audience#

POST /v1/token accepts a role of host, cohost or audience. The role determines the permissions baked into the token.

Every role can subscribe, and every role can publish data messages, so audience members can still take part in chat and reactions. See data messages.

Issuing the two kinds of token

app.post('/api/stream-token', async (req, res) => {
  const user = await authenticate(req);
  if (!user) return res.status(401).json({ error: 'Sign in first' });

  const stream = await db.streams.find(req.body.channel);

  // YOUR rule for who is allowed on stage.
  const role = stream.hostUserId === user.id ? 'host'
             : stream.invitedGuests.includes(user.id) ? 'cohost'
             : 'audience';

  const { token, wsUrl } = await applooma.createToken({
    roomName: req.body.channel,
    identity: user.id,
    role,
    metadata: { name: user.displayName },
  });

  res.json({ token, wsUrl, role });
});

Joining as host and as audience#

The client code is the same on both sides except for the role passed to joinChannel. When the role is audience the SDK does not turn on the microphone or camera at all, even if you pass camera: true.

import AppEngine from '@applooma/rtc-web';

const engine = AppEngine.create({ appId: 'YOUR_APP_ID' });

const { token, wsUrl } = await fetchStreamToken('friday-show');
await engine.joinChannel(token, wsUrl, {
  role: 'host',
  camera: true,
  microphone: true,
});

engine.attachLocalVideo(document.getElementById('preview'));

Bringing in an external encoder#

If the host broadcasts from OBS, a hardware encoder, or any other tool that speaks RTMP or WHIP, create an ingest. The ingest joins your channel as a publishing participant, so the audience sees it exactly like any other host.

POST /v1/streams/ingest — API key auth.

curl -X POST https://api.applooma.dev/v1/streams/ingest \
  -H "x-applooma-key: ak_your_key" \
  -H "x-applooma-secret: as_your_secret" \
  -H "Content-Type: application/json" \
  -d '{ "roomName": "friday-show", "name": "studio", "type": "rtmp" }'

# → 201
# {
#   "ingestId": "IN_xxxxxxxx",
#   "url": "rtmp://ingest.applooma.dev/x",
#   "streamKey": "…",
#   "roomName": "friday-show",
#   "status": "ready"
# }

In OBS, put url in Server and streamKey in Stream Key, then press Start Streaming. For type: "whip" the url is a WHIP endpoint instead, used by browser-based and WebRTC encoders.

Deleting an ingest

DELETE /v1/streams/ingest/:ingestId

curl -X DELETE https://api.applooma.dev/v1/streams/ingest/IN_xxxxxxxx \
  -H "x-applooma-key: ak_your_key" \
  -H "x-applooma-secret: as_your_secret"

# → { "deleted": true }
# → 404 { "error": "Ingest not found" }  if the id belongs to another project

Pushing the channel out to YouTube, Facebook or Twitch#

A media push composites everyone publishing in the channel into a single video and sends it to external RTMP destinations. This is how you simulcast your in-app stream to social platforms.

POST /v1/streams/push — API key auth.

curl -X POST https://api.applooma.dev/v1/streams/push \
  -H "x-applooma-key: ak_your_key" \
  -H "x-applooma-secret: as_your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "roomName": "friday-show",
    "urls": [
      "rtmp://a.rtmp.youtube.com/live2/YOUR-KEY",
      "rtmp://live.twitch.tv/app/YOUR-KEY"
    ]
  }'

# → 201
# { "pushId": "EG_xxxxxxxx", "roomName": "friday-show", "destinations": 2, "status": "active" }

curl -X POST https://api.applooma.dev/v1/streams/push/EG_xxxxxxxx/stop \
  -H "x-applooma-key: ak_your_key" \
  -H "x-applooma-secret: as_your_secret"

# → { "pushId": "EG_xxxxxxxx", "status": "stopped" }
# → 404 { "error": "Push not found or already stopped" }

What the push looks like

• The output is a grid composite of everyone publishing, not a single participant's feed.
• Up to three destinations per push. If you need more, start a second push for the same channel.
• Only rtmp:// and rtmps:// destinations are accepted; anything else is rejected with 400.

Next#