API

API

The following API is in place. Changes will be documented in this Wiki.

Server

Helpers

The following interfaces are referenced throughout this documentation.

export interface ClientState {
  uuid?: string;
  clientName: string;
  currentlyWatching: string;
  videoState: VideoState;
}

export interface VideoState {
  paused: boolean;
  tick: number;
}

export interface PartyState {
  isActive: true;
  partyId: string;
  peers: ClientState[];
}

export interface ChatMessage {
  type: "chatMessage";
  data: {
    text: string;
    timestamp: number;
  };
}

type mediaCommands = "play" | "pause" | "seek";

Servers must act on the following instructions.

Join a party instruction

A client wishes to join a party. He thereby subscribes to video updates (play, pause, seek) & party state updates (e.g. when somebody joins or leaves the party).

export interface SendJoin {
  type: "join";
  data: {
    guid: string;
    partyId: string;
    clientState: ClientState;
  };
}

Leaving a party is handled when a Websocket closes. There is no specific instruction to leave a party.

Forward instruction

The server may be asked to forward a instruction to all clients of a given party. The server will forward instructions of type videoUpdate, of which valid variants are play, pause & seek, as well as instructions of type chatMessage. Note that the server checks the type of forward commands and restricts it to chatMessage and videoUpdate in order to prevent unauthorized commands from being forwarded. Furthermore, the server will add a peer to commandToForward.data, so that clients can figure out who the command originates from.

export interface SendForward {
  type: "forward";
  data: {
    commandToForward: forwardInstruction;
  };
}
type forwardInstruction = SendVideoUpdate | SendChatMessage;

export interface SendVideoUpdate {
  type: "videoUpdate";
  data: {
    variant: mediaCommands;
    tick: number;
  };
}

export interface SendChatMessage {
  type: "forward";
  data: {
    commandToForward: ChatMessage;
  };
}

Client Update Instruction

Clients can send this instruction, if they wish to update their client state.

export interface SendUpdateClientState {
  type: "clientUpdate";
  data: {
    newClientState: {
      currentlyWatching: string;
      videoState: VideoState;
    };
  };
}

Clients

Clients must act on the following instructions:

Set UUID instruction

The server responds to a client's join request with the Set UUID instruction. This is necessary so that the client can identify himself using his uuid.

export interface ReceiveSetUUID {
  type: "setUUID";
  data: {
    uuid: string;
  };
}

Video Update Instruction

The server can tell clients to play, pause or seek within the context of the video currently present in the client's tab's DOM.

export interface ReceivePartyState {
  type: "partyStateUpdate";
  data: {
    partyState: PartyState;
  };
}

Party State Update Instruction

The server can instruct clients to update their party state. Among other things, this tells the client which peers are currently present in the party and what Website they're currently on.

export interface ReceiveVideoUpdate {
  type: "videoUpdate";
  data: {
    variant: mediaCommands;
    tick: number;
    peer: {
      uuid: string;
    };
  };
}