resources.proto

// Copyright 2021 Google LLC
//
// 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 google.cloud.video.livestream.v1;

import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/video/livestream/v1/outputs.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";

option csharp_namespace = "Google.Cloud.Video.LiveStream.V1";
option go_package = "google.golang.org/genproto/googleapis/cloud/video/livestream/v1;livestream";
option java_multiple_files = true;
option java_outer_classname = "ResourcesProto";
option java_package = "com.google.cloud.video.livestream.v1";
option php_namespace = "Google\\Cloud\\Video\\LiveStream\\V1";
option ruby_package = "Google::Cloud::Video::LiveStream::V1";

// Input resource represents the endpoint from which the channel ingests
// the input stream.
message Input {
  option (google.api.resource) = {
    type: "livestream.googleapis.com/Input"
    pattern: "projects/{project}/locations/{location}/inputs/{input}"
  };

  // The type of the input.
  enum Type {
    // Input type is not specified.
    TYPE_UNSPECIFIED = 0;

    // Input will take an rtmp input stream.
    RTMP_PUSH = 1;

    // Input will take an srt (Secure Reliable Transport) input stream.
    SRT_PUSH = 2;
  }

  // Tier of the input specification.
  enum Tier {
    // Tier is not specified.
    TIER_UNSPECIFIED = 0;

    // Resolution < 1280x720. Bitrate <= 6 Mbps. FPS <= 60.
    SD = 1;

    // Resolution <= 1920x1080. Bitrate <= 25 Mbps. FPS <= 60.
    HD = 2;

    // Resolution <= 4096x2160. Not supported yet.
    UHD = 3;
  }

  // Security rules for access control. Each field represents one security rule.
  // Only when the source of the input stream satisfies all the fields, this
  // input stream can be accepted.
  message SecurityRule {
    // At least one ip range must match unless none specified. The IP range is
    // defined by CIDR block: for example, `192.0.1.0/24` for a range and
    // `192.0.1.0/32` for a single IP address.
    repeated string ip_ranges = 1;
  }

  // The resource name of the input, in the form of:
  // `projects/{project}/locations/{location}/inputs/{inputId}`.
  string name = 1;

  // Output only. The creation time.
  google.protobuf.Timestamp create_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The update time.
  google.protobuf.Timestamp update_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // User-defined key/value metadata.
  map<string, string> labels = 4;

  // Source type.
  Type type = 5;

  // Tier defines the maximum input specification that is accepted by the
  // video pipeline. The billing is charged based on the tier specified here.
  // See [Pricing](https://cloud.google.com/livestream/pricing) for more detail.
  // The default is `HD`.
  Tier tier = 14;

  // Output only. URI to push the input stream to.
  // Its format depends on the input [type][google.cloud.video.livestream.v1.Input.type], for example:
  //
  // *  `RTMP_PUSH`: `rtmp://1.2.3.4/live/{STREAM-ID}`
  // *  `SRT_PUSH`: `srt://1.2.3.4:4201?streamid={STREAM-ID}`
  string uri = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Preprocessing configurations.
  PreprocessingConfig preprocessing_config = 9;

  // Security rule for access control.
  SecurityRule security_rules = 12;

  // Output only. The information for the input stream. This field will be present only when
  // this input receives the input stream.
  InputStreamProperty input_stream_property = 15 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Channel resource represents the processor that does a user-defined
// "streaming" operation, which includes getting an input stream through an
// input, transcoding it to multiple renditions, and publishing output live
// streams in certain formats (for example, HLS or DASH) to the specified
// location.
message Channel {
  option (google.api.resource) = {
    type: "livestream.googleapis.com/Channel"
    pattern: "projects/{project}/locations/{location}/channels/{channel}"
  };

  // Location of output file(s) in a Google Cloud Storage bucket.
  message Output {
    // URI for the output file(s). For example, `gs://my-bucket/outputs/`.
    string uri = 1;
  }

  // State of streaming operation that the channel is running.
  enum StreamingState {
    // Streaming state is not specified.
    STREAMING_STATE_UNSPECIFIED = 0;

    // Channel is getting the input stream, generating the live streams to the
    // specified output location.
    STREAMING = 1;

    // Channel is waiting for the input stream through the input. Live streams
    // do not start yet.
    AWAITING_INPUT = 2;

    // Channel is running, but has trouble publishing the live streams onto the
    // specified output location (for example, the specified Cloud Storage
    // bucket is not writable).
    STREAMING_ERROR = 4;

    // Channel is generating live streams with no input stream. Live streams are
    // filled out with black screen, while input stream is missing.
    STREAMING_NO_INPUT = 5;

    // Channel is stopped, finishing live streams.
    STOPPED = 6;

    // Channel is starting.
    STARTING = 7;

    // Channel is stopping.
    STOPPING = 8;
  }

  // The resource name of the channel, in the form of:
  // `projects/{project}/locations/{location}/channels/{channelId}`.
  string name = 1;

  // Output only. The creation time.
  google.protobuf.Timestamp create_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The update time.
  google.protobuf.Timestamp update_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // User-defined key/value metadata.
  map<string, string> labels = 4;

  // A list of input attachments that this channel uses.
  // One channel can have multiple inputs as the input sources. Only one
  // input can be selected as the input source at one time.
  repeated InputAttachment input_attachments = 16;

  // Output only. The [InputAttachment.key][google.cloud.video.livestream.v1.InputAttachment.key] that serves as the current input source. The
  // first input in the [input_attachments][google.cloud.video.livestream.v1.Channel.input_attachments] is the initial input source.
  string active_input = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. Information about the output (that is, the Cloud Storage bucket to store
  // the generated live stream).
  Output output = 9 [(google.api.field_behavior) = REQUIRED];

  // List of elementary streams.
  repeated ElementaryStream elementary_streams = 10;

  // List of multiplexing settings for output streams.
  repeated MuxStream mux_streams = 11;

  // List of output manifests.
  repeated Manifest manifests = 12;

  // List of output sprite sheets.
  repeated SpriteSheet sprite_sheets = 13;

  // Output only. State of the streaming operation.
  StreamingState streaming_state = 14 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. A description of the reason for the streaming error. This property is
  // always present when [streaming_state][google.cloud.video.livestream.v1.Channel.streaming_state] is
  // [STREAMING_ERROR][google.cloud.video.livestream.v1.Channel.StreamingState.STREAMING_ERROR].
  google.rpc.Status streaming_error = 18 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Configuration of platform logs for this channel.
  LogConfig log_config = 19;
}

// Configuration of platform logs.
// See [Using and managing platform
// logs](https://cloud.google.com/logging/docs/api/platform-logs#managing-logs)
// for more information about how to view platform logs through Cloud Logging.
message LogConfig {
  // The severity level of platform logging for this channel. Logs with a
  // severity level higher than or equal to the chosen severity level will be
  // logged and can be viewed through Cloud Logging.
  // The severity level of a log is ranked as followed from low to high: DEBUG <
  // INFO < NOTICE < WARNING < ERROR < CRITICAL < ALERT < EMERGENCY.
  // See
  // [LogSeverity](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity)
  // for more information.
  enum LogSeverity {
    // Log severity is not specified. This is the same as log severity is OFF.
    LOG_SEVERITY_UNSPECIFIED = 0;

    // Log is turned off.
    OFF = 1;

    // Log with severity higher than or equal to DEBUG are logged.
    DEBUG = 100;

    // Logs with severity higher than or equal to INFO are logged.
    INFO = 200;

    // Logs with severity higher than or equal to WARNING are logged.
    WARNING = 400;

    // Logs with severity higher than or equal to ERROR are logged.
    ERROR = 500;
  }

  // The severity level of platform logging for this resource.
  LogSeverity log_severity = 1;
}

// Properties of the input stream.
message InputStreamProperty {
  // The time that the current input stream is accepted and the connection is
  // established.
  google.protobuf.Timestamp last_establish_time = 1;

  // Properties of the video streams.
  repeated VideoStreamProperty video_streams = 2;

  // Properties of the audio streams.
  repeated AudioStreamProperty audio_streams = 3;
}

// Properties of the video stream.
message VideoStreamProperty {
  // Index of this video stream.
  int32 index = 1;

  // Properties of the video format.
  VideoFormat video_format = 2;
}

// Properties of the video format.
message VideoFormat {
  // Video codec used in this video stream.
  string codec = 1;

  // The width of the video stream in pixels.
  int32 width_pixels = 2;

  // The height of the video stream in pixels.
  int32 height_pixels = 3;

  // The frame rate of the input video stream.
  double frame_rate = 4;
}

// Properties of the audio stream.
message AudioStreamProperty {
  // Index of this audio stream.
  int32 index = 1;

  // Properties of the audio format.
  AudioFormat audio_format = 2;
}

// Properties of the audio format.
message AudioFormat {
  // Audio codec used in this audio stream.
  string codec = 1;

  // The number of audio channels.
  int32 channel_count = 2;

  // A list of channel names specifying the layout of the audio channels.
  repeated string channel_layout = 3;
}

// A group of information for attaching an input resource to this channel.
message InputAttachment {
  // Configurations to follow when automatic failover happens.
  message AutomaticFailover {
    // The [InputAttachment.key][google.cloud.video.livestream.v1.InputAttachment.key]s of inputs to failover to when this input is
    // disconnected. Currently, only up to one backup input is supported.
    repeated string input_keys = 1;
  }

  // A unique key for this input attachment.
  string key = 1;

  // The resource name of an existing input, in the form of:
  // `projects/{project}/locations/{location}/inputs/{inputId}`.
  string input = 2 [(google.api.resource_reference) = {
                      type: "livestream.googleapis.com/Input"
                    }];

  // Automatic failover configurations.
  AutomaticFailover automatic_failover = 3;
}

// Event is a sub-resource of a channel, which can be scheduled by the user to
// execute operations on a channel resource without having to stop the channel.
message Event {
  option (google.api.resource) = {
    type: "livestream.googleapis.com/Event"
    pattern: "projects/{project}/locations/{location}/channels/{channel}/events/{event}"
  };

  // Inserts a new ad opportunity.
  message AdBreakTask {
    // Duration of an ad opportunity. Must be greater than 0.
    google.protobuf.Duration duration = 1;
  }

  // State of the event
  enum State {
    // Event state is not specified.
    STATE_UNSPECIFIED = 0;

    // Event is scheduled but not executed yet.
    SCHEDULED = 1;

    // Event is being executed.
    RUNNING = 2;

    // Event has been successfully executed.
    SUCCEEDED = 3;

    // Event fails to be executed.
    FAILED = 4;

    // Event has been created but not scheduled yet.
    PENDING = 5;
  }

  // The resource name of the event, in the form of:
  // `projects/{project}/locations/{location}/channels/{channelId}/events/{eventId}`.
  string name = 1;

  // Output only. The creation time.
  google.protobuf.Timestamp create_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The update time.
  google.protobuf.Timestamp update_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // User-defined key/value metadata.
  map<string, string> labels = 4;

  // Required. Operation to be executed by this event.
  oneof task {
    // Required. Inserts a new ad opportunity.
    AdBreakTask ad_break = 6 [(google.api.field_behavior) = REQUIRED];
  }

  // When this field is set to true, the event will be executed at the earliest
  // time that the server can schedule the event and [execution_time][google.cloud.video.livestream.v1.Event.execution_time] will be
  // populated with the time that the server actually schedules the event.
  bool execute_now = 9;

  // The time when the event should be executed. When [execute_now][google.cloud.video.livestream.v1.Event.execute_now] is set to
  // `true`, this field should not be set in `CreateEvent` request and will be
  // populated with the time that the server schedules the event.
  google.protobuf.Timestamp execution_time = 10;

  // Output only. The state of the event.
  State state = 11 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. An error object that describes the reason for the failure.
  // This property is always present when `state` is `FAILED`.
  google.rpc.Status error = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
}