How to: Log Footage in Real Time

Real-time footage logging

Charlie Anderson
5 min read

Introduction

Real-time logging allows devices to register comments, asset status, and other data while a piece of media is being recorded on set, before it is registered with Frame.io, for any C2C assets being generated by any device in the same project.

Imagine a director watching their feed in Video Village, being able to hit a button whenever the actor gives a good performance, or a Smart Slate that can mark the clap point on all assets.

What will I need?

If you haven't read the Implementing C2C: Setting Up guide, give it a quick glance before moving on!

You will need the access_token you received during the hardware device or C2C Application authentication and authorization guide.

Timecode requirements

To line up real-time logging events with assets, we expect both the asset being captured and the device being used to log to be jam-syned or gen-locked. Both the recording device and the logging device will then be responsible for sending timecode to our backend, where we will do a timecode sync operation to line up the logging event with the correct frame.

Setting up your input configurations

Real-time logging operates on a new concept in the data model: Inputs. An input represents a physical button on your device that can be configured to send data to Frame.io. The first thing you will need to decide is the number of buttons you will allow to do this sort of operation, then assign an index, starting at 0, to each button. This index will be used to identify which button has been pressed when the event is sent to our servers. Inputs belong directly to channels, and so each button press message will need to target a specific channel endpoint. For more on channels, see the [channel management guide].

Configuration of what each button does is handled by the user through Frame.io's UI, allowing integrations to be a simple as possible. You won't be required for any special UI affordances on your end, besides being able to assign a button to be a "Frame.io action", if your button / triggers / etc are configurable.

We will work with you to determine following configuration for each of your device's inputs:

  • Index: An 0-indexed integer that will be used to identify the input.
  • Display name: The name of the input to be displayed to the user in Frame.io's configuration screen.
  • Supported actions: Right now the only action type is "single press", but in the future we may allow additional action types such as "long press" or "double press" to allows each input to support multiple actions, each having a different meaning.
  • Button color: If your button has a color associated with it, we can display that to help users orient themselves when configuring the device's input settigs.

  • Default event type: The type of event this input generates by default:

    • Comment: This input generates a comment
    • Status: The input updates the asset status
  • Default comment text: The default text that should be used on comments generated by this input

  • Default status: The default status to update assets with when this input is being used for status. Can be:

    • in_progress
    • needs_review
    • approved

By supplying this information ahead of time, we keep the demands on your actual device as low as possible.

Sending a real-time logging event

Real-time logging events can be sent with the following call

Shell
{
curl -X POST https://api.frame.io/v2/devices/channels/{channel_id}/inputs/{input_index}/trigger \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__'
        {
            "action_type": "single_press",
            "offset": 0,
            "start": {
                "smpte_timecode": "01:00:00:00",
                "rate": {
                    "playback": [24_000, 1001],
                    "ntsc": "non_drop"
                }
            },
            "duration": {
                "smpte_timecode": "00:00:00:01",
                "rate": {
                    "playback": [24_000, 1001],
                    "ntsc": "non_drop"
                }
            }
       }
__JSON__
} | python -m json.tool

On a success, you will receive a 204 with a blank payload.

URL Parameters

  • channel_id: The UUID of the channel this input is registered to. This ID will have been received by the channel create call or from the identity endpoint.
  • input_index: The index of the input making the call

JSON Body

  • action_type: The type of action to perform. Currently the only supported action is single_press.
  • offset: The offset from the start of the asset to log the event at.

  • start: Start time, as represented by the SMPTE timecode + framerate of when the input was triggered.

    • smpte_timecode: Timecode represented as a SMPTE string.
    • rate: Framerate of the timecode stream.
    • playback: Playback speed of the framerate, represented as a [numerator, denominator] pair in an array. Optionally, this field also accepts fractions in string format, "numerator/denominator". NTSC framerates like 23.98 should be sent as they're fully qualified rational value: [`24000, 1001]`.
    • ntsc: The NTSC standard of the timecode. Can be "non_drop" or null. If null, playback must represent a whole-number value, such as [24, 1]. If "non_drop", playback must represent a valid NTSC framerate, such as [24000, 1001].
  • duration: Duration of the event, as represented by a SMPTE timecode + framerate of when the input was triggered. Conform to the same object definition as start. For single_press, events, must be exactly 1 frame ("01:00:00:00").

Reliability requirements

Realtime upload triggers must apply the same reliability guidelines as uploads, and respect the device paused status.

Next up

If you haven't already, we encourage you to reach out to our team, then continue to the next guide. We look forward to hearing from you!