Gravity Forms Video Offload Premium Add-on Setup Guide

Video Offload sends the videos that visitors give you through Gravity Forms to a video platform and keeps the playback link in the entry. Videos stay out of your WordPress uploads folder, your server does not have to stream them, and the person who reads the entry sees a player instead of a link to a heavy file. You choose the platform for each form: Bunny Stream, Cloudflare Stream or Mux.

Large video files are the hard part of any form that asks for them. They fill the disk, they are slow to download, they play badly on a phone and they are a pain to back up. A video platform solves all of that, but somebody has to move the file there. This add-on does it for you, in the background, after the form was submitted, so the visitor never waits and a slow platform can never break a form.

What You Get

• A feed for each form and platform. It works with File Upload fields and with the Video Recording and Screen Recording fields of GravityExtra. Files that are not videos are skipped.
• Three platforms behind one screen: Bunny Stream, Cloudflare Stream and Mux. Add a second feed to send the same video to two platforms.
• A background queue that uses Action Scheduler when it is there and WP-Cron otherwise. The form submit does not talk to any platform.
• Small files go in one request. Large files go in pieces with the resumable upload of each platform, and a run that is interrupted continues where it stopped.
• Automatic retries with a growing wait of 30 seconds, one minute, two minutes and so on up to an hour, and a clear failure with the reason when the attempts are used up.
• A status for every video: queued, uploading, processing, ready or failed, with notes in the entry.
• Webhook support with signature checks for all three platforms. A webhook only tells the add-on to look again; the answer always comes from the platform API.
• The playback link stored with the entry, optionally copied into a field, and the player embedded in the entry view.
• Merge tags for notifications and confirmations: the link, the player and the status.
• Private playback with signed links on all three platforms.
• An option to delete the local file once the platform has confirmed the video, with safety rules.
• Keys encrypted before they are saved, conditional logic on the feed and a clean uninstall.

Requirements

You need Gravity Forms 2.9 or newer, WordPress 6.5 or newer, PHP 7.4 or newer with the OpenSSL extension, an active license key and an account with at least one platform. The background queue needs WP-Cron or Action Scheduler to run. On a busy site the default WP-Cron is fine; on a quiet site a real cron job that calls wp-cron.php every minute makes the videos move sooner. If no platform is set up yet, the add-on shows a notice on the Gravity Forms pages.

Quick Start

1. Install and activate the add-on, then activate your license key under Forms, Settings, Video Offload.
2. On the same screen enter the keys of your platform. Save.
3. Open your form, go to Settings, Video Offload and add a feed. Pick the platform and the fields that hold videos.
4. Submit a test entry with a short video. Open the entry: the Video Offload box shows the status and, a little later, the player.

Step 1: Enter the Keys of Your Platform

All keys are entered once under Forms, Settings, Video Offload. Each key field shows as dots after saving. The saved value is encrypted with a key that comes from your site salts, so it never appears in the page, in the option that stores the settings or in an export in plain text. To keep a saved key, leave its field as it is. To replace it, type the new one.

Bunny Stream

Open your video library in the Bunny dashboard. Copy the Library ID and the API key of the library. The CDN host name is optional: when you enter it, the stored link is the HLS playlist on your own pull zone, otherwise it is the embed link of the Bunny player. For private playback add the token authentication key from the Security page of the library. To use webhooks, add the read-only API key of the library and enter the webhook address shown on the screen in the library settings.

Cloudflare Stream

Enter your Account ID and an API token that has the Stream edit permission. The button Register this webhook with Cloudflare sets the webhook address of your account and saves the signing secret, encrypted. A Cloudflare account has room for one Stream webhook, so register it only if you do not use the slot for something else.

Mux

Create an access token in the Mux dashboard with read and write access to Mux Video and enter the token ID and the token secret. For private playback create a signing key, then enter its ID and its private key. For webhooks add a webhook in Mux that points to the address shown on the screen and paste its signing secret.

Step 2: Add a Feed to a Form

Open the form, then Settings, Video Offload, and add a feed.

• Video platform: where the videos go. A platform whose keys are missing is marked.
• Fields with videos: tick the File Upload, Video Recording and Screen Recording fields of the form. All of them are ticked at first.
• Video title on the platform: optional, merge tags work. Empty means the file name.
• Private playback: turn it on for signed links, see below.
• How Mux gets the file: only for Mux. Direct upload sends the file from your site. The second choice lets Mux download it from a signed temporary link on your site, which is useful for very large files but needs a site that Mux can reach.
• Copy the link into this field: optional. Pick a text, paragraph, hidden or website field and the playback link is added to it when the video is ready, one line per video.
• Delete the local file: see below.
• Conditional logic: send only when a rule is met, for example only when a checkbox says that the video may be shared.

How a Video Travels

When the entry is saved the feed makes one job for every video file and schedules the first step. That takes a few milliseconds and sends nothing, so the confirmation appears at once. The steps then run in the background. If the form has payment feeds you can send the video only after the payment is completed, with the usual option of Gravity Forms feeds.

A step that fails because of a temporary problem, such as a timeout or an error 500 or 429, is tried again after 30 seconds, then after one minute, two minutes and so on, up to an hour. After five attempts the video is marked as failed. A refusal that cannot get better by waiting, such as a wrong key (401 or 403) or a missing file, fails at once. A file that was already created on the platform is reused when a step is repeated, so a retry never makes a second copy.

A large file is sent in pieces of 8 MiB. Each background run sends pieces until its time budget is used, saves where it stopped and schedules the next run, so a file of several gigabytes does not need a long PHP time limit. Files up to 32 MiB go in a single request.

The Entry View

Open any entry that has videos. The Video Offload box shows each file with its platform and its status. When the video is ready the player of the platform is embedded right there. A failed video shows the reason and a Try again button that starts the video over from the beginning. Entry notes record when a video was queued, when it was ready or why it failed and when the local copy was deleted.

Merge Tags

Use these tags in notifications, confirmations and anywhere Gravity Forms accepts merge tags. Replace 5 with the ID of the field:

{video_offload:5:url}
{video_offload:5:embed}
{video_offload:5:status}

• url is the playback link. For several videos in one field the links are on separate lines.
• embed is the player. In an HTML message it is an iframe; in plain text it is the embed link.
• status is queued, uploading, processing, ready or failed, and none when the field has no video.

Notifications are normally sent when the form is submitted, which is before the platform has finished. At that moment the status is queued and the link is empty. Use the tags in a notification that you send later, for example from a workflow or with the gfvoff_video_ready action, which fires once for every video that becomes ready and receives the entry ID and the job. The tags also work in the entry view and in any notification you resend.

Private Playback

Turn on Private playback in the feed and the video can only be played with a signed link.

• Bunny Stream: the embed link gets a token made from your token authentication key. Turn on token authentication for the library as well.
• Cloudflare Stream: the add-on sets require signed URLs on the video and asks Cloudflare for a short-lived token each time a link is shown.
• Mux: the asset gets a signed playback ID and the add-on signs a token with your signing key, valid for a day.

Signed links expire, so the add-on does not store them. It makes a fresh one every time the entry view or a merge tag needs a link. The lifetime is one day and can be changed with the gfvoff_signed_link_ttl filter.

Delete the Local File Safely

Switch on Delete the local file after the platform confirms the video to free the disk. The add-on deletes the file only when every rule holds: the platform has reported the video as ready, no other feed on the same file is still waiting, and the file lies inside the Gravity Forms upload folder. It never deletes a file for a failed video, a video that is still processing or a path that points anywhere else. A note records the deletion. The link to the file in the entry stops working after that, so do not use this option if you want to keep downloading the original.

Webhooks

Polling is enough to finish every video, so webhooks are optional. They make the status change sooner. Each platform has its own address on your site, shown on the settings screen. A request is accepted only when its signature is correct and not older than five minutes: Cloudflare and Mux sign the time and the body with the webhook secret, Bunny signs the body with the read-only key of the library. A request with a bad signature gets the same empty 403 as any other bad call. Even a correct request never carries the result: it only asks the add-on to check the platform again.

Security Summary

• Keys are encrypted before they are saved and never printed, logged or put in an error message.
• Every request to a platform uses HTTPS with certificate checks.
• Webhook signatures are compared in constant time and old requests are refused.
• The temporary link for Mux is signed, expires after an hour, works only for that one video while it is being sent and is refused afterwards.
• Files are read only from the Gravity Forms upload folder.
• The Try again link needs a nonce and the capability to edit entries.
• Nothing is sent to anyone but the platform you chose and the license server.

Troubleshooting

The video stays queued

The queue needs WP-Cron or Action Scheduler. Check that WP-Cron is not disabled without a real cron job in its place and that the license key is active. A site without a license waits and sends nothing.

The video failed with a 401 or 403

A key is wrong or lacks a permission. Fix it on the settings screen and press Try again in the entry.

It says the file is no longer on this server

Something moved or removed the file before the add-on could send it, for example another plugin that offloads uploads. Choose a field that still keeps the file on this server while the video is sent.

The video stays in processing

Long videos take time to encode. After two days without a result the add-on marks the video as failed. A webhook shortens the wait.

Can I send the same video to two platforms?

Yes. Add a second feed on the same form. Each feed makes its own job, and a local file is deleted only after both are ready.

What happens if I uninstall the add-on?

Its options, its jobs and its keys are removed. The videos stay on the platforms and the forms and entries are not touched.

See the Video Offload add-on