OrchestratorTracker/client/src/proto/livepeer.proto

syntax = "proto3";

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 Ping(PingPong) returns (PingPong);
}

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;

}


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

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

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;

    // Non-binary capability constraints, such as supported ranges.
    message Constraints {
            // Empty for now
    }
}

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

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

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

// [EXPERIMENTAL]
// Describes a class that a model is trained to detect
message DetectorClass {
  // ID of the class to detect
  uint32 class_id = 1;

  // Name of the class to detect
  string class_name = 2;
}

// [EXPERIMENTAL]
// Describes the scene classification configuration
message SceneClassificationProfile {
  // Sample rate of the frames picked by the O for scene detection
  uint32 sample_rate = 1;

  // List of output classes the model is trained to detect
  repeated DetectorClass classes = 2;
}

// [EXPERIMENTAL]
// Describes the content detection configuration
message DetectorProfile {
  oneof value {
    SceneClassificationProfile scene_classification = 1;
  }
}

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

  // [EXPERIMENTAL]
  // Detector enabled for this segment
  bool detector_enabled = 9;

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

  // [EXPERIMENTAL]
  // Detector profiles to use
  repeated DetectorProfile detector_profiles = 36;
}

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

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

// [EXPERIMENTAL]
// Describes scene classification results
message SceneClassificationData {
  // Probability that the segment is detected as a particular classID (uint32)
  map<uint32, double> class_probs = 1;
}

// [EXPERIMENTAL]
// Describes detection results
message DetectData {
  oneof value {
    SceneClassificationData scene_classification = 1;
  }
}

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

    // [EXPERIMENTAL]
    // Detection result data in same order as SegData.detector_profiles
    repeated DetectData detections = 3;
}

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

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

    // 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"
}

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