{
  "swagger": "2.0",
  "info": {
    "title": "Video segment service",
    "version": "0.1507.0",
    "description": "Send your API key as a bearer token: `Authorization: Bearer <api key>`."
  },
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "ApiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "Your API key as a bearer token: `Authorization: Bearer <api key>`."
    }
  },
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/video/v1/videos/{videoRid}/{videoFileRid}/create-segments": {
      "post": {
        "operationId": "VideoSegmentService_createVideoFileSegments",
        "summary": "Create video file segments",
        "tags": [
          "Video Segment Service"
        ],
        "parameters": [
          {
            "name": "videoRid",
            "in": "path",
            "type": "string",
            "format": "rid",
            "x-alias": "VideoRid",
            "required": true
          },
          {
            "name": "videoFileRid",
            "in": "path",
            "type": "string",
            "format": "rid",
            "x-alias": "VideoFileRid",
            "required": true
          },
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/CreateSegmentsRequest"
            },
            "required": true,
            "x-example": {
              "requests": [
                {
                  "dataHandle": {
                    "type": "s3",
                    "s3": "<s3 path>"
                  },
                  "frameRate": 1,
                  "durationSeconds": 1,
                  "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                      "mediaTimestamps": [
                        1
                      ],
                      "absoluteTimestamps": [
                        {
                          "seconds": 1,
                          "nanos": 1
                        }
                      ]
                    }
                  },
                  "segmentEndTimestamp": {
                    "seconds": 1,
                    "nanos": 1
                  }
                }
              ],
              "seriesUuid": "<series uuid>",
              "overWriteSegments": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/CreateSegmentsResponse"
            },
            "x-example": {
              "segments": [
                {
                  "rid": "<segment rid>",
                  "videoRid": "<video rid>",
                  "dataHandle": {
                    "type": "s3",
                    "s3": "<s3 path>"
                  },
                  "frameRate": 1,
                  "durationSeconds": 1,
                  "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                      "mediaTimestamps": [
                        1
                      ],
                      "absoluteTimestamps": [
                        {
                          "seconds": 1,
                          "nanos": 1
                        }
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      }
    },
    "/video/v1/videos/{videoRid}/streams/{streamUuid}/create-segments": {
      "post": {
        "operationId": "VideoSegmentService_createVideoStreamSegments",
        "summary": "Create video stream segments",
        "tags": [
          "Video Segment Service"
        ],
        "description": "Creates segments for a video stream. Similar to createVideoFileSegments but for streaming video.",
        "parameters": [
          {
            "name": "videoRid",
            "in": "path",
            "type": "string",
            "format": "rid",
            "x-alias": "VideoRid",
            "required": true
          },
          {
            "name": "streamUuid",
            "in": "path",
            "type": "string",
            "format": "uuid",
            "required": true
          },
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/CreateSegmentsRequest"
            },
            "required": true,
            "x-example": {
              "requests": [
                {
                  "dataHandle": {
                    "type": "s3",
                    "s3": "<s3 path>"
                  },
                  "frameRate": 1,
                  "durationSeconds": 1,
                  "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                      "mediaTimestamps": [
                        1
                      ],
                      "absoluteTimestamps": [
                        {
                          "seconds": 1,
                          "nanos": 1
                        }
                      ]
                    }
                  },
                  "segmentEndTimestamp": {
                    "seconds": 1,
                    "nanos": 1
                  }
                }
              ],
              "seriesUuid": "<series uuid>",
              "overWriteSegments": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/CreateSegmentsResponse"
            },
            "x-example": {
              "segments": [
                {
                  "rid": "<segment rid>",
                  "videoRid": "<video rid>",
                  "dataHandle": {
                    "type": "s3",
                    "s3": "<s3 path>"
                  },
                  "frameRate": 1,
                  "durationSeconds": 1,
                  "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                      "mediaTimestamps": [
                        1
                      ],
                      "absoluteTimestamps": [
                        {
                          "seconds": 1,
                          "nanos": 1
                        }
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      }
    },
    "/video/v1/videos/{videoRid}/get-segment-by-timestamp": {
      "post": {
        "operationId": "VideoSegmentService_getSegmentByTimestamp",
        "summary": "Get segment by timestamp",
        "tags": [
          "Video Segment Service"
        ],
        "description": "Returns metadata for the segment within a video containing the requested absolute timestamp.",
        "deprecated": true,
        "x-deprecated": "Replaced by VideoService#getSegmentByTimestampV2, which addresses the video channel series (channel + tags) instead of a Video rid.",
        "parameters": [
          {
            "name": "videoRid",
            "in": "path",
            "type": "string",
            "format": "rid",
            "x-alias": "VideoRid",
            "required": true
          },
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/GetSegmentByTimestampRequest"
            },
            "required": true,
            "x-example": {
              "timestamp": {
                "seconds": 1,
                "nanos": 1
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/Segment"
            },
            "x-example": {
              "rid": "<segment rid>",
              "videoRid": "<video rid>",
              "dataHandle": {
                "type": "s3",
                "s3": "<s3 path>"
              },
              "frameRate": 1,
              "durationSeconds": 1,
              "timestamps": {
                "type": "timestampMappings",
                "timestampMappings": {
                  "mediaTimestamps": [
                    1
                  ],
                  "absoluteTimestamps": [
                    {
                      "seconds": 1,
                      "nanos": 1
                    }
                  ]
                }
              }
            }
          },
          "204": {
            "description": "No content, when there is nothing to return."
          }
        }
      }
    }
  },
  "definitions": {
    "Handle": {
      "type": "object",
      "x-union": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "s3"
          ]
        },
        "s3": {
          "type": "string",
          "x-alias": "S3Path"
        }
      },
      "required": [
        "type"
      ],
      "description": "Set `type` to the name of one of the other fields, and set only that field.",
      "example": {
        "type": "s3",
        "s3": "string"
      }
    },
    "Timestamp": {
      "description": "Deprecated for new APIs. Use google.protobuf.Timestamp for absolute instants in proto APIs.\n\nThis legacy nanosecond precision timestamp type is represented by an epoch time in seconds and a nanosecond offset. The nanosecond offset is from the start of the epoch second, so must be less than 1 billion.",
      "type": "object",
      "properties": {
        "seconds": {
          "type": "integer",
          "format": "int64"
        },
        "nanos": {
          "type": "integer",
          "format": "int64"
        }
      },
      "required": [
        "seconds",
        "nanos"
      ]
    },
    "CreateSegment": {
      "type": "object",
      "properties": {
        "dataHandle": {
          "$ref": "#/definitions/Handle"
        },
        "frameRate": {
          "type": "number",
          "format": "double",
          "description": "The average frame rate (FPS) of the segment calculated as total frames / duration in seconds."
        },
        "durationSeconds": {
          "type": "number",
          "format": "double"
        },
        "timestamps": {
          "$ref": "#/definitions/SegmentTimestamps"
        },
        "segmentEndTimestamp": {
          "$ref": "#/definitions/Timestamp"
        }
      },
      "required": [
        "dataHandle",
        "frameRate",
        "durationSeconds",
        "timestamps",
        "segmentEndTimestamp"
      ]
    },
    "CreateSegmentsRequest": {
      "type": "object",
      "properties": {
        "requests": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CreateSegment"
          }
        },
        "seriesUuid": {
          "type": "string",
          "format": "uuid"
        },
        "overWriteSegments": {
          "type": "boolean",
          "description": "If true, overlapping segments from other video files within the same video will be deleted before inserting new segments. The cached segment metadata for affected files will be recomputed."
        }
      },
      "example": {
        "requests": [
          {
            "dataHandle": {
              "type": "s3",
              "s3": "<s3 path>"
            },
            "frameRate": 1,
            "durationSeconds": 1,
            "timestamps": {
              "type": "timestampMappings",
              "timestampMappings": {
                "mediaTimestamps": [
                  1
                ],
                "absoluteTimestamps": [
                  {
                    "seconds": 1,
                    "nanos": 1
                  }
                ]
              }
            },
            "segmentEndTimestamp": {
              "seconds": 1,
              "nanos": 1
            }
          }
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": true
      }
    },
    "CreateSegmentsResponse": {
      "type": "object",
      "properties": {
        "segments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Segment"
          }
        }
      }
    },
    "GetSegmentByTimestampRequest": {
      "type": "object",
      "properties": {
        "timestamp": {
          "$ref": "#/definitions/Timestamp"
        },
        "viewRangeStart": {
          "allOf": [
            {
              "$ref": "#/definitions/Timestamp"
            }
          ],
          "description": "The start of the view range used to dynamically calculate media timestamps. The first segment with an overlap with the time bounds will have its minimum media timestamp set to 0, with every subsequent segment building media time cumulatively from that offset. This will determine the starting media timestamp of the returned segment. The view range should be the same as the one requested to get the playlist and segment summaries."
        }
      },
      "required": [
        "timestamp"
      ],
      "example": {
        "timestamp": {
          "seconds": 1,
          "nanos": 1
        }
      }
    },
    "Segment": {
      "type": "object",
      "properties": {
        "rid": {
          "type": "string",
          "format": "rid",
          "x-alias": "SegmentRid"
        },
        "videoRid": {
          "type": "string",
          "format": "rid",
          "x-alias": "VideoRid"
        },
        "dataHandle": {
          "$ref": "#/definitions/Handle"
        },
        "frameRate": {
          "type": "number",
          "format": "double",
          "description": "The average frame rate (FPS) of the segment calculated as total frames / duration in seconds."
        },
        "durationSeconds": {
          "type": "number",
          "format": "double",
          "description": "The duration of a segment in media time."
        },
        "timestamps": {
          "allOf": [
            {
              "$ref": "#/definitions/SegmentTimestamps"
            }
          ],
          "description": "for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps."
        }
      },
      "required": [
        "rid",
        "videoRid",
        "dataHandle",
        "frameRate",
        "durationSeconds",
        "timestamps"
      ]
    },
    "SegmentTimestamps": {
      "description": "A video segment will either contain timestamps or timestamp mappings depending on whether it is intended to be frame-mapped. Without a frame-timestamp mapping manifest file, a list of absolute timestamps will be automatically assigned to each segment based on media timestamps.. Otherwise, media timestamps will be extracted and mapped to those in the provided manifest.\n\nSet `type` to the name of one of the other fields, and set only that field.",
      "type": "object",
      "x-union": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "timestampMappings"
          ]
        },
        "timestampMappings": {
          "$ref": "#/definitions/TimestampMappings"
        }
      },
      "required": [
        "type"
      ],
      "example": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      }
    },
    "TimestampMappings": {
      "description": "contains 2 equal-length lists, which contain the video media time and user-provided absolute time for the frame at each index. Enables frame-mapping on the front-end.",
      "type": "object",
      "properties": {
        "mediaTimestamps": {
          "type": "array",
          "items": {
            "type": "number",
            "format": "double"
          }
        },
        "absoluteTimestamps": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Timestamp"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Video Segment Service",
      "x-displayName": "Video segment service",
      "description": "Upon ingestion, every video is split into smaller segments. The Video Segment Service manages operations on videos at the segment-level."
    }
  ]
}