Federation

Instances can be connected: another vibe-live's live streams on your dashboard, its people writing in your chat -- and yours on theirs. Every connection is agreed by both admins, and every capability goes one way at a time, so you can take without giving, or give without taking.

Everything here is in Settings → Federation, in sections that fold: Asking to connect and Servers you might know (open when there is something to decide), Connected servers, Refused, and Signing in from other servers. In the list each server is one line -- its name, and which way streams and chat cross (both ways, theirs here, ours there, off), flagged in red when they declined something you allow or have not answered. Click it to open its boxes. The same settings can be made from a shell with vibe-live peer (see below).

Following is not part of this

Anybody on the fediverse -- another vibe-live, Mastodon, GoToSocial -- can follow a streamer here and get their "went live" posts, and your people can follow anybody elsewhere. That needs no connection and no admin: a follow carries no content, and anyone could follow from the other side anyway. What this page controls is content crossing between instances.

Adding another instance

Type its address (other.example) and Add a server. It starts with everything off: writing a name down grants nothing.
Tell the other admin your address -- the page shows it ("They add this instance as ..."). They add you the same way.
Tick what you allow. Each box shows whether it is actually in force.

When another instance adds yours first

If another instance adds yours before you add it, it appears under Asking to connect at the top of the page, with when it added you. Add puts it in your list with everything off -- then tick what you allow, as with any server. Dismiss hides it; it comes back only if that instance stops asking for a day and then adds you again.

Only real requests are shown: the other instance is asked, in the background, whether it has actually added yours, so nobody can make a request appear in another instance's name. A request that has stopped asking for a day disappears on its own.

stateDiagram-v2
  state "checked in the background" as Checking
  state "Asking to connect" as Asking
  state "in your list, everything off" as Peer
  state "hidden" as Hidden
  [*] --> Checking: they add your instance
  Checking --> Asking: they confirm it
  Checking --> [*]: they did not add you
  Asking --> Peer: Add
  Asking --> Hidden: Dismiss
  Asking --> [*]: a day without asking
  Hidden --> [*]: a day without asking

Servers you might know

Your connections can tell you about theirs, and you about yours -- only with everybody's agreement. Two more boxes on each server do it:

Box	You allow	It works when they also allow
Name them to our other servers	this server is named to your other connections	letting you name them
Let them name us	that server names you to its connections	naming you

So a server that connected with you quietly is never announced: it is named only if it ticked Let them name us on its side.

What your connections name to you appears under Servers you might know, with who named each one. Add makes it one of your servers with everything off, and the other side sees an ordinary request; Refuse moves it to Refused, and no connection offers it again until you Restore it. A suggestion nobody has named for a week disappears. Your list then shows servers you added yourself and those accepted from suggestions, each under its own heading.

Lists are only ever exchanged between connected servers, signed by each server's own key, and only your direct connections are named -- never what they were told by theirs.

The four boxes

Box	You allow	It works when they also allow
Show their streams	their live streams on your dashboard	sharing theirs with you
Share ours	your streams on their dashboard	showing yours
Their people chat here	their people writing in your chats -- from their own instance, or signed in here	sharing their people with you
Ours chat there	your people writing in their chats, from here	accepting yours

In a server's row the boxes come in pairs, one line per thing that crosses: Here is what they do on yours (their streams, their people), There is what you do on theirs. Streams, then chat, then naming (see above); Sign-in, which has no counterpart, comes after the pairs.

Each box has a reading beside it:

checking...: you just saved it, and your server is asking theirs what they allow now. It is replaced within seconds.
on -- they agree: in force.
off -- they do not allow it: you allow it, they do not. Their decision, not a fault.
off -- no answer from them yet: they could not be asked, or not recently. It counts as no until they answer.
off: you do not allow it.

flowchart LR
  T1["Their streams<br/>(they share them)"] -->|"you tick Show their streams"| Y1["Your dashboard"]
  Y2["Your streams<br/>(you tick Share ours)"] -->|"they show yours"| T2["Their dashboard"]

Chat has the same shape: Their people chat here on your side with their sharing on theirs, Ours chat there with their accepting.

So "show their streams, share nothing" is a one-way link: their streams appear here, yours stay home. It is a normal setup, not a broken one.

Chat on their streams happens in their room. When your people watch one of their streams here, the chat beside it is the streamer's own chat on their instance, passed through yours. With Ours chat there in force, your signed-in people write in it as @name@your.instance, and the streamer sees them by name among their viewers. Without it -- or for somebody not signed in -- the chat can be read, not written, and the page says why. Either way, everybody watching from here counts in the streamer's viewer count, and the count shown here is theirs.

A long list can be filtered by name, narrowed to the servers where something crosses, where they declined something, where they have not answered, or where nothing is allowed -- and sorted by name or by when each last answered.

Changes take effect within seconds, on both sides. Saving a row asks that server at once, and also tells it your answer changed, so it asks you again at once too (an older server that does not understand this learns at its next check, within half an hour). Otherwise each instance asks its peers every half hour. If a peer stops answering for six hours, whatever it allowed stops counting until it answers again. Removing a peer, or unticking a box, hides what already arrived at once.

A streamer can keep their own stream home with Let my stream be shown on other instances, whatever the boxes say.

Relaying their streams through this server

Normally, people here who watch a stream from another server fetch it from that server, each of them. Relay their streams through this server (in each server's row, off by default) asks that server to send each of its live streams here once instead. People here then watch it from this server: it reaches them from closer, the other server sends one copy whatever your audience, and it never sees their addresses. This server makes the qualities for them, which costs this server's processor rather than theirs.

It works only where everything agrees:

their streams are shown here (Their streams here in force);
that server lets your server relay them -- it does for any server it shares its streams with;
the streamer lets their stream be shown on other instances;
that server's media engine can send a stream on: the built-in engine; OvenMediaEngine where its REST API is configured (the same setting that lets an admin end a stuck stream); LiveKit where Egress is set up, at the cost of one encode on that server.

When any of these is missing, people here simply watch from that server, as before. The switch takes effect within a minute, and someone already watching keeps their player until they reload.

Visitors from other instances

People with an account on another instance can sign in here with it, to watch, follow and -- where Their people chat here is in force -- chat. They can never stream here.

People with accounts elsewhere may sign in here turns this on or off for everyone.
Each server's Sign-in box shuts out that one server.

Unlike streams and chat, sign-in is open by default and needs no agreement: somebody watching with an account from elsewhere is ordinary use.

From a shell

vibe-live peer list                            # a table: each direction, and whether it is in force
vibe-live peer list --json                     # the same, for scripts
vibe-live peer set other.example --streams --chat
vibe-live peer set other.example --show-streams --accept-chat   # take, do not give
vibe-live peer set other.example --share-streams --share-chat   # give, do not take
vibe-live peer set other.example --block-signin
vibe-live peer set other.example --streams --propagate --let-propagate   # and naming, both ways
vibe-live peer forget other.example
vibe-live peer requests [--json]               # instances that added this one first

--streams and --chat are both directions. A flag left out is turned off: peer set writes the whole row, as the page does.

Diagrams drawn by Mermaid (MIT license).