feat: added OutputType field to the Clip resource to support MP4 clipping

Google APIs · copybara-github · commit c18013694a22 · 2025-05-14T11:21:37.000-07:00
feat: added DVRSession methods to support DVR feature
docs: Clarified GCS in the comment for method `DeleteClip` in service `LivestreamService`
docs: Updated comment for field `update_mask` in message `.google.cloud.video.livestream.v1.UpdateInputRequest` to indicate updates in `tier` field are allowed
docs: A comment for field `requested_cancellation` in message `.google.cloud.video.livestream.v1.OperationMetadata` is changed to clarify error type

PiperOrigin-RevId: 758761402
diff --git a/google/cloud/video/livestream/v1/livestream_grpc_service_config.json b/google/cloud/video/livestream/v1/livestream_grpc_service_config.json
@@ -6,7 +6,12 @@
       { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "ListInputs" },
       { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "GetInput" },
       { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "ListEvents" },
-      { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "GetEvent" }
+      { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "GetEvent" },
+      { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "ListClips" },
+      { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "GetClip" },
+      { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "GetAsset" },
+      { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "ListAssets" },
+      { "service": "google.cloud.video.livestream.v1.LivestreamService", "method": "GetPool" }
     ],
     "timeout": "60s",
     "retryPolicy": {
diff --git a/google/cloud/video/livestream/v1/outputs.proto b/google/cloud/video/livestream/v1/outputs.proto
@@ -17,6 +17,7 @@ syntax = "proto3";
 package google.cloud.video.livestream.v1;
 
 import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
 import "google/protobuf/duration.proto";
 import "google/type/datetime.proto";
 
diff --git a/google/cloud/video/livestream/v1/resources.proto b/google/cloud/video/livestream/v1/resources.proto
@@ -667,8 +667,20 @@ message Clip {
     string output_uri = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
   }
 
+  // OutputType represents the output type of the clip.
+  enum OutputType {
+    // OutputType is not specified.
+    OUTPUT_TYPE_UNSPECIFIED = 0;
+
+    // OutputType is a VOD manifest. This is the default value.
+    MANIFEST = 1;
+
+    // OutputType is an MP4 file.
+    MP4 = 2;
+  }
+
   // The resource name of the clip, in the following format:
-  // `projects/{project}/locations/{location}/channels/{c}/clips/{clipId}`.
+  // `projects/{project}/locations/{location}/channels/{channelId}/clips/{clipId}`.
   // `{clipId}` is a user-specified resource id that conforms to the following
   // criteria:
   //
@@ -715,6 +727,139 @@ message Clip {
   // allowed.
   repeated ClipManifest clip_manifests = 12
       [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. OutputType of the clip. If not specified, the default value is
+  // MANIFEST.
+  OutputType output_type = 13 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// TimeInterval represents a time interval.
+message TimeInterval {
+  // Optional. The start time of the interval.
+  google.protobuf.Timestamp start_time = 1
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The end time of the interval.
+  google.protobuf.Timestamp end_time = 2
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// DvrSession is a sub-resource under channel. Each DvrSession represents a DVR
+// recording of the live stream for a specific time range.
+message DvrSession {
+  option (google.api.resource) = {
+    type: "livestream.googleapis.com/DvrSession"
+    pattern: "projects/{project}/locations/{location}/channels/{channel}/dvrSessions/{dvr_session}"
+    plural: "dvrSessions"
+    singular: "dvrSession"
+  };
+
+  // State of the DVR session.
+  enum State {
+    // State is not specified.
+    STATE_UNSPECIFIED = 0;
+
+    // The operation is pending to be picked up by the server.
+    PENDING = 1;
+
+    // The session is being updated.
+    UPDATING = 2;
+
+    // The session is scheduled and waiting for the start time.
+    SCHEDULED = 3;
+
+    // The session is currently in progress and the outputs are available in the
+    // specified Cloud Storage bucket. For additional information, see the
+    // `dvr_manifests.output_uri` field.
+    LIVE = 4;
+
+    // Outputs are available in the specified Cloud Storage bucket. For
+    // additional information, see the `dvr_manifests.output_uri` field.
+    FINISHED = 5;
+
+    // The operation has failed. For additional information, see the `error`
+    // field.
+    FAILED = 6;
+
+    // The session is being deleted.
+    DELETING = 7;
+
+    // The session is being post processed.
+    POST_PROCESSING = 8;
+
+    // The session is in cooldown. The cooldown period lasts for 60 seconds.
+    // When the DVR session is updated by the user to have a new end time that
+    // is likely already in the past, the DVR manifest will end as soon as
+    // possible and the DVR session will move to this state. This is done to
+    // prevent the players to receive a manifest update that removes a segment
+    // that has already been played. After the cooldown period ends, a new
+    // manifest is generated that honors the new end time.
+    COOLDOWN = 9;
+
+    // The session is being stopped. The session will move to STOPPING state, if
+    // the parent channel is updated.
+    STOPPING = 10;
+  }
+
+  // DvrManifest identifies a source manifest and specifies a file name for the
+  // generated DVR manifest.
+  message DvrManifest {
+    // Required. A unique key that identifies a manifest config in the parent
+    // channel. This key is the same as `channel.manifests.key` for the selected
+    // manifest.
+    string manifest_key = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Output only. The output URI of the DVR manifest. The DVR output will be
+    // placed in a directory named `dvr/dvrSessionId/` under the parent
+    // channel's output uri. Format:
+    // {channel.output.uri}/dvr/{dvrSessionId}/{channel.manifests.fileName}
+    // Example: gs://my-bucket/outputs/dvr/my-dvr-session/main.m3u8
+    string output_uri = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+  }
+
+  // DvrWindow represents a DVR window.
+  message DvrWindow {
+    // The allowlist forms of a DVR window.
+    oneof kind {
+      // A time interval in the form of a tuple of Unix epoch time.
+      TimeInterval time_interval = 1;
+    }
+  }
+
+  // Identifier. The resource name of the DVR session, in the following format:
+  // `projects/{project}/locations/{location}/channels/{channelId}/dvrSessions/{dvrSessionId}`.
+  // `{dvrSessionId}` is a user-specified resource id that conforms to the
+  // following criteria:
+  //
+  // 1. 1 character minimum, 63 characters maximum
+  // 2. Only contains letters, digits, underscores, and hyphens
+  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // 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];
+
+  // Optional. User-defined key/value metadata.
+  map<string, string> labels = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. The state of the clip.
+  State state = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. An error object that describes the reason for the failure.
+  // This property only presents when `state` is `FAILED`.
+  google.rpc.Status error = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Required. A list of DVR manifests. Currently only one DVR manifest is
+  // allowed.
+  repeated DvrManifest dvr_manifests = 7
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The specified ranges of segments to generate a DVR recording.
+  repeated DvrWindow dvr_windows = 8 [(google.api.field_behavior) = REQUIRED];
 }
 
 // An asset represents a video or an image.
diff --git a/google/cloud/video/livestream/v1/service.proto b/google/cloud/video/livestream/v1/service.proto
