OrchestratorTracker/client/src/proto/livepeer.proto

syntax = "proto3";

package net;
option go_package = "./net";

// RPC calls implemented by the orchestrator
service Orchestrator {

  // Called by the broadcaster to request transcoder info from an orchestrator.
  rpc GetOrchestrator(OrchestratorRequest) returns (OrchestratorInfo);
  rpc EndTranscodingSession(EndTranscodingSessionRequest)
      returns (EndTranscodingSessionResponse);
  rpc Ping(PingPong) returns (PingPong);
}

service AIWorker {

  // Called by the aiworker to register to an orchestrator. The orchestrator
  // notifies registered aiworkers of jobs as they come in.
  rpc RegisterAIWorker(RegisterAIWorkerRequest) returns (stream NotifyAIJob);
}

service Transcoder {

  // Called by the transcoder to register to an orchestrator. The orchestrator
  // notifies registered transcoders of segments as they come in.
  rpc RegisterTranscoder(RegisterRequest) returns (stream NotifySegment);
}

message PingPong {
  // Implementation defined
  bytes value = 1;
}

// sent by Broadcaster to Orchestrator to terminate the transcoding session and
// free resources (used for verification sessions)
message EndTranscodingSessionRequest {
  // Data for transcoding authentication
  AuthToken auth_token = 1;
}

message EndTranscodingSessionResponse {}

// This request is sent by the broadcaster in `GetTranscoder` to request
// information on which transcoder to use.
message OrchestratorRequest {

  // Ethereum address of the broadcaster
  bytes address = 1;

  // Broadcaster's signature over its address
  bytes sig = 2;

  // Features and constraints required by the broadcaster
  Capabilities capabilities = 3;

  // Don't throw error in case of missing capacity, used for refreshing session
  // when we don't need to check capacity
  bool ignoreCapacityCheck = 4;
}

/*
  OSInfo needed to negotiate storages that will be used.
  It carries info needed to write to the storage.
*/
message OSInfo {

  enum StorageType {
    DIRECT = 0;
    S3 = 1;
    GOOGLE = 2;
  }

  // Storage type: direct, s3, ipfs.
  StorageType storageType = 1;

  S3OSInfo s3info = 16;
}

message S3OSInfo {

  // Host to use to connect to S3
  string host = 1;

  // Key (prefix) to use when uploading the object.
  string key = 2;

  // POST policy that S3 owner node creates to give write access to other node.
  string policy = 3;

  // Signature for POST policy.
  string signature = 4;

  // Needed for POST policy.
  string credential = 5;

  // Needed for POST policy.
  string xAmzDate = 6;
}

// PriceInfo conveys pricing info for transcoding services
message PriceInfo {
  // price in wei
  int64 pricePerUnit = 1;

  // Pixels covered in the price
  // Set price to 1 wei and pixelsPerUnit > 1 to have a smaller price
  // granularity per pixel than 1 wei
  int64 pixelsPerUnit = 2;

  // Capability price is for
  uint32 capability = 3;

  // constraint price is for
  string constraint = 4;
}

message Capabilities {

  // Bit string of supported features - one bit per feature
  repeated uint64 bitstring = 1;

  // Bit string of features that are required to be supported
  repeated uint64 mandatories = 2;

  // Capacity corresponding to each capability
  map<uint32, uint32> capacities = 3;

  string version = 4;

  Constraints constraints = 5;

  // Non-binary constraints.
  message Constraints {
    string minVersion = 1;
    map<uint32, CapabilityConstraints> PerCapability = 2;
  }

  // Non-binary capability constraints, such as supported ranges.
  message CapabilityConstraints {
    message ModelConstraint {
      bool warm = 1;
      uint32 capacity = 2;
      string runnerVersion = 3;
      uint32 capacityInUse = 4;
    }

    map<string, ModelConstraint> models = 1;
  }
}

// The orchestrator sends this in response to `GetOrchestrator`, containing
// miscellaneous data related to the job.
message OrchestratorInfo {

  // URI of the transcoder to use for submitting segments.
  string transcoder = 1;

  // Parameters for probabilistic micropayment tickets
  TicketParams ticket_params = 2;

  // Price Info containing the price per pixel to transcode
  PriceInfo price_info = 3;

  // ETH address that should sign transcoded results
  bytes address = 4;

  // Features and constraints supported by the orchestrator
  Capabilities capabilities = 5;

  // Data for transcoding authentication
  AuthToken auth_token = 6;

  // Information on Orchestrator hardware
  repeated HardwareInformation hardware = 7;

  // Orchestrator returns info about own input object storage, if it wants it to
  // be used.
  repeated OSInfo storage = 32;

  // prices for capabilities
  repeated PriceInfo capabilities_prices = 33;
}

// Data for transcoding authentication that is included in the OrchestratorInfo
// message during discovery
message AuthToken {
  // Record used to authenticate for a transcode session
  // Opaque to the receiver
  bytes token = 1;

  // ID of the transcode session that the token is authenticating for
  string session_id = 2;

  // Timestamp when the token expires
  int64 expiration = 3;
}

// Data included by the broadcaster when submitting a segment for transcoding.
message SegData {

  // Manifest ID this segment belongs to
  bytes manifestId = 1;

  // Sequence number of the segment to be transcoded
  int64 seq = 2;

  // Hash of the segment data to be transcoded
  bytes hash = 3;

  // Transcoding profiles to use
  bytes profiles = 4;

  // Broadcaster signature for the segment. Corresponds to:
  // broadcaster.sign(manifestId | seqNo | dataHash | profiles)
  bytes sig = 5;

  // Duration of the segment to be transcoded, in milliseconds
  int32 duration = 6;

  // Capabilities used by this segment.
  Capabilities capabilities = 7;

  // Data for transcoding authentication
  AuthToken auth_token = 8;

  // Calculate perceptual hash for this segment
  bool calc_perceptual_hash = 10;

  // Broadcaster's preferred storage medium(s)
  // XXX should we include this in a sig somewhere until certs are
  // authenticated?
  repeated OSInfo storage = 32;

  // Transcoding profiles to use. Supersedes `profiles` field
  // Deprecated by `fullProfiles2` but may still be used for mpegts formats
  repeated VideoProfile fullProfiles = 33;

  // Transcoding profiles to use. Supersedes `fullProfiles` field
  // Deprecated by `fullProfiles3` but may still be used for integer FPS
  repeated VideoProfile fullProfiles2 = 34;

  // Transcoding profiles to use. Supersedes `fullProfiles2` field
  repeated VideoProfile fullProfiles3 = 35;

  // Transcoding parameters specific to this segment
  SegParameters segment_parameters = 37;

  // Force HW Session Reinit
  bool ForceSessionReinit = 38;
}

message SegParameters {
  // Start timestamp from which to start encoding
  // Milliseconds, from start of the file
  uint64 from = 1;
  // Skip all frames after that timestamp
  // Milliseconds, from start of the file
  uint64 to = 2;
}

message VideoProfile {
  // Name of VideoProfile
  string name = 16;

  // Width of VideoProfile
  int32 width = 17;

  // Height of VideoProfile
  int32 height = 18;

  // Bitrate of VideoProfile
  int32 bitrate = 19;

  // FPS of VideoProfile
  uint32 fps = 20;

  // Desired output format
  enum Format {
    MPEGTS = 0;
    MP4 = 1;
  }
  Format format = 21;

  // FPS Denominator of VideoProfile
  uint32 fpsDen = 22;

  enum Profile {
    ENCODER_DEFAULT = 0;
    H264_BASELINE = 1;
    H264_MAIN = 2;
    H264_HIGH = 3;
    H264_CONSTRAINED_HIGH = 4;
  }
  // Desired codec profile
  Profile profile = 23;

  // GOP interval
  int32 gop = 24;

  enum VideoCodec {
    H264 = 0;
    H265 = 1;
    VP8 = 2;
    VP9 = 3;
  }

  // Encoder (video codec)
  VideoCodec encoder = 25;

  int32 colorDepth = 26;

  enum ChromaSubsampling {
    CHROMA_420 = 0;
    CHROMA_422 = 1;
    CHROMA_444 = 2;
  }
  ChromaSubsampling chromaFormat = 27;
  uint32 quality = 28;
}

// Individual transcoded segment data.
message TranscodedSegmentData {

  // URL where the transcoded data can be downloaded from.
  string url = 1;

  // Amount of pixels processed (output pixels)
  int64 pixels = 2;

  // URL where the perceptual hash data can be downloaded from (can be empty)
  string perceptual_hash_url = 3;
}

// A set of transcoded segments following the profiles specified in the job.
message TranscodeData {

  // Transcoded data, in the order specified in the job options
  repeated TranscodedSegmentData segments = 1;

  // Signature of the hash of the concatenated hashes
  bytes sig = 2;
}

// Response that a transcoder sends after transcoding a segment.
message TranscodeResult {

  // Sequence number of the transcoded results.
  int64 seq = 1;

  // Result of transcoding can be an error, or successful with more info
  oneof result {
    string error = 2;
    TranscodeData data = 3;
  }

  // Used to notify a broadcaster of updated orchestrator information
  OrchestratorInfo info = 16;
}

// Response that an orchestrator sends after processing a payment.
message PaymentResult {
  // Used to notify a broadcaster of updated orchestrator information
  OrchestratorInfo info = 16;
}

// Sent by the transcoder to register itself to the orchestrator.
message RegisterRequest {

  // Shared secret for auth
  string secret = 1;

  // Transcoder capacity
  int64 capacity = 2;

  // Transcoder capabilities
  Capabilities capabilities = 3;
}

// Sent by the orchestrator to the transcoder
message NotifySegment {

  // URL of the segment to transcode.
  string url = 1;

  // Configuration for the transcoding job
  SegData segData = 3;

  // ID for this particular transcoding task.
  int64 taskId = 16;

  // Orchestrator identifier for segment metadata
  string orchId = 18;

  // All fields below are deprecated. May still be populated if necessary

  // Deprecated by segData. Job the segment belongs to.
  reserved 2; // Formerly "string job"

  // Deprecated by fullProfiles. Set of presets to transcode into.
  // Should be set to an invalid value to induce failures
  bytes profiles = 17;

  // Deprecated by segData. Transcoding configuration to use.
  reserved 33; // Formerly "repeated VideoProfile fullProfiles"
}

// Sent by the aiworker to register itself to the orchestrator.
message RegisterAIWorkerRequest {

  // Shared secret for auth
  string secret = 1;

  // AIWorker capabilities
  Capabilities capabilities = 2;

  // AIWorker hardware info
  repeated HardwareInformation hardware = 3;
}

// Data included by the gateway when submitting a AI job.
message AIJobData {
  // pipeline to use for the job
  string pipeline = 1;

  // AI job request data
  bytes requestData = 2;
}

// Sent by the orchestrator to the aiworker
message NotifyAIJob {
  // Configuration for the AI job
  AIJobData AIJobData = 1;

  // ID for this particular AI task.
  int64 taskId = 2;
}

// Required parameters for probabilistic micropayment tickets
message TicketParams {
  // ETH address of the recipient
  bytes recipient = 1;

  // Pay out (in Wei) to the recipient if the ticket wins
  bytes face_value = 2;

  // Probability that the ticket wins
  bytes win_prob = 3;

  // 32 byte keccak-256 hash commitment to a random number provided
  // by the recipient
  bytes recipient_rand_hash = 4;

  // Value generated by recipient that the recipient can use
  // to derive the random number corresponding to the recipient's hash
  // commitment
  bytes seed = 5;

  // Block number at which the current set of advertised TicketParams is no
  // longer valid
  bytes expiration_block = 6;

  // Expected ticket expiration params
  TicketExpirationParams expiration_params = 7;
}

// Sender Params (nonces and signatures)
message TicketSenderParams {
  // Monotonically increasing counter that makes the ticket
  // unique relative to a particular hash commitment to a recipient's random
  // number
  uint32 sender_nonce = 1;

  // Sender signature over the ticket
  bytes sig = 2;
}

// Ticket params for expiration related validation
message TicketExpirationParams {
  // Round during which tickets are created
  int64 creation_round = 1;

  // Block hash associated with creation_round
  bytes creation_round_block_hash = 2;
}

// Payment for transcoding video segments
// A payment can constitute of multiple tickets
// A broadcaster might need to send multiple tickets to top up his credit with
// an Orchestrator
message Payment {
  // Probabilistic micropayment ticket parameters
  // These remain the same even when sending multiple tickets
  TicketParams ticket_params = 1;

  // ETH address of the sender
  bytes sender = 2;

  // Ticket params for expiration related validation
  TicketExpirationParams expiration_params = 3;

  repeated TicketSenderParams ticket_sender_params = 4;

  // O's last known price
  PriceInfo expected_price = 5;
}

// GPU information used by worker on network
message GPUComputeInfo {
  // unique id
  string id = 1;

  // gpu name
  string name = 2;

  // compute version supported - major
  uint32 major = 4;

  // compute version supported - minor
  uint32 minor = 5;

  // GPU memory free
  int64 memory_free = 6;

  // GPU memory total
  int64 memory_total = 7;
}

// Hardware information for worker on network
message HardwareInformation {
  // pipeline hardware supports
  string pipeline = 1;

  // model_id hardware supports
  string model_id = 2;

  // hardware for pipeline and model_id
  map<string, GPUComputeInfo> gpu_info = 3;
}