Integrator Checklist

Requirements for C2C Integrators

Billy Peake
11 min read

C2C integration requirements

This article contains a “checklist” of integration best practices and requirements for becoming part of the C2C ecosystem. This is intended to be generic for all types of integrators as not all items are applicable to your C2C devices or applications. The C2C Partnerships team will work with you on defining the requirements as a part of the C2C Certification Program.

Basic integration requirements

The following is required of all integrations:

  • Displays connected project name to user when connected: Enables the user to quickly double-check what project they are connected to without scouring Frame.io’s UI.

  • Simple Upload Status

    • Number of files remaining
    • Total file size Remaining
    • Progress of current file upload: Gives confidence to user that files are being uploaded.
    • Status of completed, queued, or failed uploads.
  • Displays network connection status
  • Automatically refreshes access token after 8 hour expiration with no interaction / alert to the user. No user interaction failures or errors should occur because of an expired token, unless there is an error refreshing the token.
  • Can back out or cancel authorization flow. A user may decide they are not ready connect after initiating authorization flow. The application or device must have an affordance for cancelling authorization at each step of the process.
  • Uses the socket status for realtime communication
  • Sends firmware version header in each HTTPS endpoint call

OAuth Application Integration Requirements

OAuth application integrations must meet the following additional requirements:

  • Displays current login information. The following information must be displayed to verify the currently logged in user:

    • Username
    • Email
    • Optional: Profile Image
  • Implements a Frame.io connection manager: explained below
  • Displays to the user that they do not have access to any C2C enabled accounts if true, and should direct the user to our support document for more information.

Application integration: connection manager requirements

We want to make sure that configuring the C2C connection is as seamless as possible for the user. To help accomplish this, we require that application integrators’ UIs have a dedicated area to manage their C2C connection and check its status. This section is not required to be its own page, but is required to contain the connection state, and is the natural place that a user would go to initiate the authorization flow.

The following states should be accounted for:

  • Not Authorized: If a user is not logged to Frame.io, there must be a Call to Action to prompt them to initiate the authorization flow.

  • Not Connected: Once the user has authenticated, they need to select a project.

    • Account Listing/Selection. Users can be part of multiple accounts, so they need to be able to narrow which account they are looking for their project in.
    • Project Listing/Selection: Once a user has selected an account, a list of projects for that account needs to be displayed.
    • OPTIONAL: The list of projects can get quite large, so a simple search / filter functionality goes a long way to make finding the right project easier.

  • Connected

    • Display the name of the project they are connected to.,
    • Ability for the user to disconnect from the current project (which also removes the device from the project’s C2C Connections tab)
    • Ability for the user to choose a new account and project.

Security Requirements

Here at Frame.io we take security very seriously, and that extends to our integrators.

  • Makes all requests over HTTPS. HTTP requests will be rejected by our server.
  • Integrations must make a direct connection to Frame.io from the physical device or application, and may not pass through an intermediary service provider (IE Cloud to Cloud).
  • The client_secret and client_id must not be accessible via users.
  • Stored access_token and refresh_token credentials must not be accessible via users.
  • OPTIONAL: Stored secrets and tokens should be encrypted at rest.

Uploader requirements

The most complicated part of any integration will be reliably uploading Frame.io with all created media over a variety of bad states.

We require integrations gracefully handle the following scenarios:

  • The asset can be automatically uploaded in two ways: either immediately upon recording state (real-time uploading, preferred) or upon file closing.
  • Clearly and easily displays upload status to the user, including a queued upload list, and completed or failed uploads.
  • Writes files local physical storage, accessible to the user.

  • Maintains an upload Queue that ensures delivery of assets to Frame.io if:

    • Another file(s) is currently uploading
    • There is currently no network connectivity: uploads should resume when network is re-established
    • The app/device is power cycled before/during an upload

  • Will automatically retry failed uploads if:

    • Network connectivity lost or unstable
    • Power cycle initiated

    • A non-fatal error is encountered:

      • Request timeout
      • Network Error
      • Token Expired
  • Will resume uploading of asset from last know uploaded chunk. This should not restart the upload from zero or create a new asset.

  • Respects PAUSED state, in which any assets recorded while device is PAUSED will NOT upload in this state.

    • Tracking and respecting the offset value is also extremely important.
    • Once device state is RESUMED, all uploads from that resumed point on will upload.
  • Handles non-fatal AWS errors: click here for more information.
  • Handles poisoned media (media that will always fail to upload). Retry logic should be able to detect and filter out bad media that will always result in an error. Such media should not block other media from being uploaded.

  • Users should be able to choose whether to upload all files automatically or to disable automatic uploads and select files manually at a later time.

    • Users should be able to manually select individual assets to add to the upload queue, either one at a time or through multi-selection.
    • (OPTIONAL) Users to have the option to prioritize specific file types, such as proxy files over hero files.
    • (OPTIONAL) The user should have the ability to prioritize an asset and move it to the top of the queue for immediate uploading.
    • (OPTIONAL) Parallel uploads should be allowed (upload at least 2 files simultaneously if possible).
  • User should be able to cancel a single asset upload or all asset uploads from the upload queue

Networking requirements

  • Capable of uploading files at no less than 50Mbps, external network conditions notwithstanding. Users will expect upload speeds to match network speeds, with 50Mbps being a hard floor for what users will find acceptable.
  • Capable of WiFi connectivity and support no less than WPA2 security. Ethernet connectivity is optional, but encouraged.
  • Capable of both DHCP and Static IP configurations.
  • Capable of clearly and easily displaying network status (connection type, speed, health) to the user.

  • Capable of switching between networks without needing to re-pair to the same project on frame.io

    • Save known WiFi networks for easy switching

Testing requirements

Good testing leads to great software! Because C2C is designed to be used in the most suboptimal conditions imaginable, we put some requirements on our integrations for testing.

  • Tested using network configurations consisting of at least the following scenarios. Each scenario should be tested for WiFi, Ethernet, and USB if the Device supports hardline connections. Each scenario should also be tested for various traffic conditions and connection health.

    • Commercial router connected to a hardline WAN (ie, typical home or small office).
    • Commercial router connected to bonded cellular (ie, multi-SIM) modem.
    • Commercial router connected to commercial cellular modem.
    • Commercial router connected to commercial hotspot-style modem (ie, USB or WiFi only).

    • Meshed router connections in office or event space

      • Tested for emerging 802.11r FT(Fast Basic Service Set Transition) protocol
    • Directly connected to bonded cellular (ie, multi-SIM) modem.
    • Directly connected to commercial cellular modem.
    • Directly connected to commercial hotspot-style modem (ie, USB or WiFi only). Both USB and WiFi connectivity should be tested if the Device supports a USB modem.
    • Directly connected to a cellphone in hotspot mode.
  • Tested with unexpected / random power outages.
  • Tested with unexpected / random network disconnections.
  • Tested with unexpected / random ISP connection issues.
  • Tested with poisoned media (corrupted file or other error that will always result in an upload error).
  • Tested with creating assets offline, while authenticated to a project, and then reconnecting to the internet.

Workflow Requirements

Camera to Cloud is not just a feature; it is an ecosystem that enables workflow. Depending on the type of device or application you have, there are some requirements to ensure that it operates in a way that enables a functional workflow to our users. These include:

  • For downstream SDI/HDMI recording devices:

    • Can you automatically trigger recording on the device by recording on the camera?

      • Are there different options for various cinema cameras
    • Can you set timecode offset parameters if need be?

    • Can you manually (crash) record the device?

      • Does it provide a unique name to the recording or does it use what is in the SDI/HDMI ANC data?
    • Does the filename recorded by the downstream SDI/HDMI device match the OCF?

    • Is timecode present in the SDI/HDMI stream?

      • if yes, does that timecode accurately match to the OCF timecode?

  • If a device creates proxy files, the proxy must match the same filename, timecode stream, and metadata fields as the hero file/OCF.

    • Proxy files are optimized for uploading via LTE networks and have a bitrate range of 1-12Mbps.
    • Proxies should encode video in commonly compatible codecs (AVC/HEVC/ProRes/etc)
    • Proxies should encode audio in commonly compatible codecs (WAV/AAC/MP3/etc.)
  • Video or audio assets must have timecode streams.

  • Be able to select multiple types of assets to upload

    • IE Proxy, OCF, LUT, WAV
    • IE RAW, JPG, HEIF, TIFF

  • If a user changes the name of a project, the device or app should update the user interface to reflect the change.

    • Any new uploads should not be affected by the project name change. Use project_id in the API calls instead of the project name as a string.

Quality Assurance

At frame.io, we take pride in our workflow and we strive to provide each user with the best possible experience when it comes to our partner integrations. Below are just some of the steps we take to ensure a seamless user experience. If you follow the C2C API Guide, you should have no problems passing each of these tests. Feel free to use this as a guide during your own QA testing before you submit for Certification review

  • Does the app/integration launch properly(e.g. can you use C2C without crashing the app/device)?

  • Are you able to connect to a C2C enabled Frame.io project?

    • If hardware, does the device generate a 6 digit code and display it properly?
  • Are you able to log out/disconnect from Frame.io in the app/device?
  • Does it shows current project/username/email in app/device?

  • Are you able to forget the app/device from the C2C Connections tab?

    • Does the app/device update itself to show as no longer connected to the previous project nor display the previous user’s info?

  • Are you able to shoot and upload an asset from app/ device?

    • Are you able to upload all recordable formats available? (IE JPG, RAW, MOV, CDL, Proxy, OCF)

  • Are you able to pause asset upload from C2C enabled frame.io project? (This should not allow assets to upload):

    • Resume device, check that new assets after that point are able to successfully upload.
  • Is the status of uploaded assets displayed as "pass" or "fail" and does the user know the asset has been uploaded or not?
  • Are you able to change the name of a project once device is authenticated and upload an asset?
  • Once authenticated, are you able to shoot multiple takes offline and then reconnect to internet?

  • Is a device/app able to resume uploads after a network/power interruption?

    • Have device connected to WAN/LAN and begin large file upload. While uploading:

      • Remove Internet connection from network. Upon restoration device should resume the upload of the original asset from the last known file chunk uploaded (not start over from zero or create a new asset in Frame.io)
      • Perform proper system shutdown/turn off device. Once device powers back on, device should automatically restore network connection and asset should resume uploading from the last known file chunk uploaded.
      • Perform improper system shutdown (pull power/force quit app). Once device/app powers back on, device should automatically restore network connection and asset should resume uploading from the last known file chunk uploaded.
  • Does the device show the number of files/percentage remaining to upload?
  • Does the device display the network connection status to the user? (WiFi, ETH, Tethering, good/fair/poor signal strength)
  • Does a device stay connected to the same project 8h after first authenticating it?
  • Can you cancel the Auth flow?
  • Does the device make a direct connection to Frame.io? (IE no 3rd part web portal/Cloud to Cloud)
  • Make sure the client_secret and client_id are not accessible to users.
  • Make sure the stored access_token and refresh_token credentials are not accessible to users.
  • Is the integration able to saturate available network upload speeds based on the available network technology present?

Future improvements

The Frame.io Camera to Cloud API and eco-system is a living product. The features we have today will certainly not be the same features we have in the future. We will always maintain backwards compatibility so that your integration continues to operate without any changes.

We know that our roadmap will not always line up with yours, so our ask is that we keep an open dialogue in regards to future developments to ensure that we can keep our API up to date with the way it is being used!

That’s all, folks!

Throw a mortarboard in the air, because you’ve just graduated from the UC2CIG (University of C2C Integration Guides)! We hope you found this series informative!

Please let us know if you feel anything is missing or confusing in these guides, or with any other C2C-related questions and troubleshooting. We are here to help!