synctv/synctv-proto/proto/providers/emby.proto

// Emby-compatible Provider Client API
//
// This is the client-facing gRPC API for provider type `emby`, which supports
// Emby-compatible server API.
//
// SECURITY: Login transmits the Emby API key as plaintext. Deployments MUST use
// TLS for all connections to this service.

syntax = "proto3";

package synctv.provider.emby;

import "proto/buf/validate/validate.proto";
import "proto/providers/common.proto";

// Login request
message LoginRequest {
  string host = 1 [(buf.validate.field).string.min_len = 1];
  string username = 2 [(buf.validate.field).string.min_len = 1]; // Target Emby username to bind and validate
  oneof credential {
    string password = 3; // Plaintext password; empty explicitly selects passwordless login. Requires TLS in transit.
    string api_key = 4; // SECURITY: Plaintext credential - requires TLS in transit.
  }
  string instance_name = 5; // Optional provider instance name
}

// Login response
message LoginResponse {
  string user_id = 1;
  string username = 2;
  bool is_admin = 3;
  string server_id = 4; // SHA-256(host) identifier for stored credential
}

enum ListMode {
  LIST_MODE_FOLDER = 0;
  LIST_MODE_FAVORITE_ITEMS = 1;
  LIST_MODE_FAVORITE_PEOPLE = 2;
  LIST_MODE_PERSON_ITEMS = 3;
  LIST_MODE_CONTINUE_WATCHING = 4;
  LIST_MODE_NEXT_UP = 5;
  LIST_MODE_RECENTLY_ADDED = 6;
  LIST_MODE_PLAYLISTS = 7;
  LIST_MODE_COLLECTIONS = 8;
  LIST_MODE_GENRES = 9;
  LIST_MODE_GENRE_ITEMS = 10;
}

// List items request. The backend maps this discovery intent to a source config.
message ListRequest {
  string server_id = 1 [(buf.validate.field).string.min_len = 1]; // Stored credential identifier
  ListMode mode = 2;
  uint64 start_index = 3;
  uint64 limit = 4;
  string search_term = 5;
  string instance_name = 6; // Optional provider instance name
  string target_id = 7; // Folder, person, or genre identifier for targeted modes
  repeated string item_types = 8;
}

// List items response
message ListResponse {
  repeated MediaItem items = 1;
  uint64 total = 2;
  synctv.provider.common.DiscoveredSource source = 3;
}

// Media item information
message MediaItem {
  string id = 1;
  string name = 2;
  string type = 3;
  string parent_id = 4;
  string series_name = 5;
  string series_id = 6;
  string season_name = 7;
  string thumbnail = 8; // Server-relative thumbnail URL when available
  string description = 9;
  bool is_container = 10;
  synctv.provider.common.DiscoveredSource source = 11;
}

// Get user info request
message GetMeRequest {
  string server_id = 1 [(buf.validate.field).string.min_len = 1]; // Stored credential identifier
  string instance_name = 2; // Optional provider instance name
}

// Get user info response
message GetMeResponse {
  string id = 1;
  string name = 2;
}

// Logout request
message LogoutRequest {
  string server_id = 1 [(buf.validate.field).string.min_len = 1]; // Which credential to unbind
}

// Logout response
message LogoutResponse {
  string message = 1;
}

// Get binds request
message GetBindsRequest {
  string instance_name = 1; // Optional provider instance name
}

// Get binds response
message GetBindsResponse {
  repeated BindInfo binds = 1;
}

message GetThumbnailRequest {
  string server_id = 1 [(buf.validate.field).string.min_len = 1];
  string item_id = 2 [(buf.validate.field).string.min_len = 1];
  uint32 max_height = 3 [(buf.validate.field).uint32.lte = 1920];
  uint32 max_width = 4 [(buf.validate.field).uint32.lte = 1920];
}

// Saved credential information
message BindInfo {
  string id = 1;
  string server_id = 2;
  string host = 3;
  string user_id = 4;
  int64 created_at = 5; // Unix epoch timestamp
  string provider_instance_name = 6; // Empty when the credential is not instance-scoped
}