flow-docs

OptaVision Recorder Endpoint

This documentation describes the /optavision/record endpoint on the flow platform, which allows initiating a recording on the flow platform.

Endpoint

URL: /optavision/record

HTTP method: POST

Description

This endpoint allows users to start a recording on the flow platform. The script will launch an Amazon ECS task and update the data in the DynamoDB flow-channels table. Once the recording is complete, the video will be automatically uploaded to the CMS.

If there is already a recording running on the given channel, the request will be rejected, and the user will receive a 409 Conflict error code in the response.

Input Parameters

The following parameters are expected in the POST request:

• channel: The identifier of the channel on which we want to start the recording.
• url: The URL where the recording takes place.
• title (optional): The title of the recording.
• fixture (optional): The identifier of the fixture to use. Defaults to the channel identifier.
• fps (optional): The number of frames per second. Defaults to 30.
• size (optional): The resolution of the recording. Possible values: ‘2160p’, ‘1440p’, ‘1080p’, ‘720p’, ‘480p’. Defaults to ‘720p’.
• mode (optional): The recording mode. Possible values: ‘canvas’, ‘screenshot’. Defaults to ‘canvas’.
• duration (optional): The duration of the recording in seconds. Defaults to 20.

Responses

The endpoint can return the following responses:

• 200 OK: The channel data has been successfully updated in the DynamoDB, and the ECS Task has started.
• 409 Conflict: The requested operation cannot be performed because a recording is already running on this channel.

Example Request

POST /optavision/record
Content-Type: application/json

{
  "channel": "fbr-test",
  "url": "https://docs.performgroup.io/3d-core?fbr=true",
  "title": "test",
  "fixture": "fbr-dummy-fixture",
  "fps": 30,
  "size": "720p",
  "mode": "canvas",
  "duration": 20
}

Example Response

{
  "statusCode": 200,
  "body": {
    "db": {
      "channel": "fbr-test",
      "title": "test",
      "url": "https://docs.performgroup.io/3d-core?fbr=true",
      "start": 1647356200000,
      "stop": 1647359800000,
      "provider": "fbr",
      "recorder": "5294d020024d4aa99c3fd02da2cee799",
      ...
    }
  }
}

The response includes the updated channel data, but does not include information about the launched ECS Task as it is no longer returned.

Frame-Based Recording for 3D Animation Widgets

The ExAmino Platform Recorder Endpoint supports frame-based recording for 3D animation widgets. This approach ensures that the frames of the 3D animation are properly displayed in the recorded video without any discrepancies in storing rendered frames or losing any rendered frames.

To utilize frame-based recording for 3D animation widgets, the 3D framework has been modified to render the animations frame by frame. The containers are signaled after each rendered frame, indicating that the frame is ready for appending to the video.

When recording 3D-Core-based applications, it is necessary to include the ?fbr=true query parameter in the URL to enable frame-precise recording. When this parameter is present, the 3D Core library automatically switches to the appropriate rendering mode, and no additional action is required from the user. This will ensure the best possible image quality for 3D animations.

For example:

"url": "https://docs.performgroup.io/3d-core?fbr=true"

Please note that the recording process will no longer be real-time. The container’s performance will affect the time it takes to complete the video but not the video quality. The rendering process can be made asynchronous to achieve smooth recording of 3D animations, even without GPU support in the containers.