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;
}

message RoomEgress {
  RoomCompositeEgressRequest room = 1;
  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;
}

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;
  repeated string destination_sids = 4;
}

message SendDataResponse {
  //
}

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