livekit_room.proto

// Copyright 2023 LiveKit, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package livekit;
option go_package = "github.com/livekit/protocol/livekit";
option csharp_namespace = "LiveKit.Proto";
option ruby_package = "LiveKit::Proto";

import "livekit_models.proto";
import "livekit_egress.proto";

// Room service that can be performed on any node
// they are Twirp-based HTTP req/responses
service RoomService {
  // Creates a room with settings. Requires `roomCreate` permission.
  // This method is optional; rooms are automatically created when clients connect to them for the first time.
  rpc CreateRoom(CreateRoomRequest) returns (Room);

  // List rooms that are active on the server. Requires `roomList` permission.
  rpc ListRooms(ListRoomsRequest) returns (ListRoomsResponse);

  // Deletes an existing room by name or id. Requires `roomCreate` permission.
  // DeleteRoom will disconnect all participants that are currently in the room.
  rpc DeleteRoom(DeleteRoomRequest) returns (DeleteRoomResponse);

  // Lists participants in a room, Requires `roomAdmin`
  rpc ListParticipants(ListParticipantsRequest) returns (ListParticipantsResponse);

  // Get information on a specific participant, Requires `roomAdmin`
  rpc GetParticipant(RoomParticipantIdentity) returns (ParticipantInfo);

  // Removes a participant from room. Requires `roomAdmin`
  rpc RemoveParticipant(RoomParticipantIdentity) returns (RemoveParticipantResponse);

  // Mute/unmute a participant's track, Requires `roomAdmin`
  rpc MutePublishedTrack(MuteRoomTrackRequest) returns (MuteRoomTrackResponse);

  // Update participant metadata, will cause updates to be broadcasted to everyone in the room. Requires `roomAdmin`
  rpc UpdateParticipant(UpdateParticipantRequest) returns (ParticipantInfo);

  // Subscribes or unsubscribe a participant from tracks. Requires `roomAdmin`
  rpc UpdateSubscriptions(UpdateSubscriptionsRequest) returns (UpdateSubscriptionsResponse);

  // Send data over data channel to participants in a room, Requires `roomAdmin`
  rpc SendData(SendDataRequest) returns (SendDataResponse);

  // Update room metadata, will cause updates to be broadcasted to everyone in the room, Requires `roomAdmin`
  rpc UpdateRoomMetadata (UpdateRoomMetadataRequest) returns (Room);
}

message CreateRoomRequest {
  // name of the room
  string name = 1;
  // number of seconds to keep the room open if no one joins
  uint32 empty_timeout = 2;
  // limit number of participants that can be in a room
  uint32 max_participants = 3;
  // override the node room is allocated to, for debugging
  string node_id = 4;
  // metadata of room
  string metadata = 5;
  // egress
  RoomEgress egress = 6;
  // playout delay of subscriber
  uint32 min_playout_delay = 7;
  uint32 max_playout_delay = 8;
  // improves A/V sync when playout_delay set to a value larger than 200ms. It will disables transceiver re-use 
  // so not recommended for rooms with frequent subscription changes
  bool sync_streams = 9;
}

message RoomEgress {
  RoomCompositeEgressRequest room = 1;
  AutoParticipantEgress participant = 3;
  AutoTrackEgress tracks = 2;
}

message ListRoomsRequest {
  // when set, will only return rooms with name match
  repeated string names = 1;
}

message ListRoomsResponse {
  repeated Room rooms = 1;
}

message DeleteRoomRequest {
  // name of the room
  string room = 1;
}

message DeleteRoomResponse {
}

message ListParticipantsRequest {
  // name of the room
  string room = 1;
}

message ListParticipantsResponse {
  repeated ParticipantInfo participants = 1;
}

message RoomParticipantIdentity {
  // name of the room
  string room = 1;
  // identity of the participant
  string identity = 2;
}

message RemoveParticipantResponse {
}

message MuteRoomTrackRequest {
  // name of the room
  string room = 1;
  string identity = 2;
  // sid of the track to mute
  string track_sid = 3;
  // set to true to mute, false to unmute
  bool muted = 4;
}

message MuteRoomTrackResponse {
  TrackInfo track = 1;
}

message UpdateParticipantRequest {
  string room = 1;
  string identity = 2;
  // metadata to update. skipping updates if left empty
  string metadata = 3;
  // set to update the participant's permissions
  ParticipantPermission permission = 4;
  // display name to update
  string name = 5;
}

message UpdateSubscriptionsRequest {
  string room = 1;
  string identity = 2;
  // list of sids of tracks
  repeated string track_sids = 3;
  // set to true to subscribe, false to unsubscribe from tracks
  bool subscribe = 4;
  // list of participants and their tracks
  repeated ParticipantTracks participant_tracks = 5;
}

message UpdateSubscriptionsResponse {
  // empty for now
}

message SendDataRequest {
  string room = 1;
  bytes data = 2;
  DataPacket.Kind kind = 3;
  // mark deprecated
  repeated string destination_sids = 4 [deprecated=true];
  // when set, only forward to these identities
  repeated string destination_identities = 6;
  optional string topic = 5;

  // NEXT_ID: 7
}

message SendDataResponse {
  //
}

message UpdateRoomMetadataRequest {
  string room = 1;
  // metadata to update. skipping updates if left empty
  string metadata = 2;
}