Hosts & Co-hosts

Hosts and co-hosts are the people who can broadcast video and audio in a stream. Everyone else is a viewer.

A typical use: Alice hosts a live interview and brings Bob "on stage" as a guest. Alice is the HOST. Bob becomes a CO_HOST for as long as he's on.

Where this fits: you've created a stream. Now your backend makes a credential for each person who will broadcast, and sends it to their app. The person you named in hostIdentity when creating the stream is already registered as HOST, but still needs addHost to get credentials.

Add or remove a host

On your backend, after your own check that this user may broadcast:

const credential = await livqeno.liveStreams.addHost(streamId, { identity: 'bob', role: 'CO_HOST' });
await livqeno.liveStreams.removeHost(streamId, 'bob');

from livqeno import AddHostParams
 
credential = livqeno.live_streams.add_host(stream_id, AddHostParams(identity="bob", role="CO_HOST"))
livqeno.live_streams.remove_host(stream_id, "bob")

Terminal

curl -X POST "$LIVQENO_API_URL/v1/live-streams/$STREAM_ID/hosts" \
  -H "Authorization: Bearer $LIVQENO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identity": "bob", "role": "CO_HOST"}'
 
curl -X DELETE "$LIVQENO_API_URL/v1/live-streams/$STREAM_ID/hosts/bob" \
  -H "Authorization: Bearer $LIVQENO_API_KEY"

What addHost does:

Registers the person as a host of this stream (or updates them, if they already are).
Adds them to the stream's chat with the matching scope.
Returns their credentials: an rtc token that can broadcast and a chat token.
Sends the live_stream.host_joined webhook. Note that this fires when the credentials are made, not when the host actually connects.

Which role do they get?

Pass role: 'HOST' or role: 'CO_HOST' to set it.
Leave role out for someone new, and they become CO_HOST.
Leave role out for someone already registered, and they keep their role. So refreshing a host's credentials never demotes them.

HOST vs. CO_HOST

	`HOST`	`CO_HOST`
Broadcast audio/video	✓	✓
Chat moderation scope	`ADMIN`	`MODERATOR`

Both can broadcast exactly the same things. The difference is the chat scope, and the label your app shows. Adding and removing hosts is always done by your backend with the API key, so it's up to your app to decide whether a co-host may bring on other guests.

What removing a host does

removeHost marks the person as removed (removedAt is set) and takes them out of the stream's chat. Their past chat messages stay. Your backend gets the live_stream.host_left webhook.

Join as a host

Send the credential from addHost to the host's app, unchanged. In the host's app, join and turn on the camera and mic. Turning a device on is what broadcasts it:

import { LiveStream } from '@livqeno/live';
 
const stream = await LiveStream.join(credentials); // role: 'HOST' or 'CO_HOST'
 
await stream.room.enableCamera();
await stream.room.enableMicrophone();

import { useLiveStreamHost } from '@livqeno/react';
 
const { camera, microphone, isHost } = useLiveStreamHost();
await camera.enable();

This hook throws for a VIEWER. For viewers, use useLiveStreamViewer() instead of checking isHost yourself.

import { joinLiveStream } from '@livqeno/react-native';
 
const stream = await joinLiveStream(credentials);
await stream.room.enableCamera();

final stream = await LivqenoLiveStream.join(credentials);
await stream.room.enableCamera();

On every SDK, isHost is true for both HOST and CO_HOST. To tell them apart, check role.

Common errors

Error	Cause	Fix
`RAVEN_STREAM_INVALID_STATE` on `addHost`	The stream has `ENDED`.	You can't add hosts to an ended stream. Create a new one.
`RAVEN_USAGE_LIMIT_EXCEEDED` (403) on `addHost`	The account has used all 100 live-streaming host-hours.	See paid plans. Viewer credentials still work.
`RAVEN_STREAM_NOT_FOUND`	Wrong stream id, or the stream is in another project or environment.	Use the id from `create()`.
`RAVEN_NOT_FOUND` on `removeHost`	That person was never added, or was already removed.	Check the host list with `get()` or `livqeno streams inspect` first.

Production tips

To refresh a host's credentials, call addHost again with the same identity. Do this when the host rejoins, or after a reconnect fails because the token expired. It also re-activates a removed host.
Only call addHost from your backend, after your own permission check. It's the only way to give someone broadcast access.

Next steps

Viewers: give the audience watch-only credentials.
Moderation: what hosts can do in chat.
Network quality: keep a host's broadcast going when their network drops.