Long-Form Video

Premium Feature

Functionality for this feature is currently available for customers on our Premium plans. If you’re interested in this feature, please contact our sales team for more information.

The Long-Form Video feature converts your videos into a HTTP live streaming (HLS) format that can be viewed using a web player, on any browser, on any device.

This documentation section describes all the parameters available for Long-Form Video and includes code samples you can play with. For more instructional information about implementing video such as setting up a web player, please see the Tutorials section.

Long-Form Video Differences

Long-Form Video is available through the .video domain extension. For example, https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?fm=hls.
Long-Form Video does not support custom domains.
Playing streamable video may require a compatible web player. Imgix provides a web player through ix-elements.
Newly uploaded videos will be processed by Imgix before they are available through the URL API. Processing time is relative to the video length but typically completes in seconds to minutes. A video that is not yet ready will return a 423 Processing status code. You can check the status of your video in the Asset Manager or by polling the video URL.

Video Processing

Videos uploaded to your Source’s Origin must be queued for processing through our service before playback. Processing will transcode the video into multiple formats and resolutions for optimal streaming performance.

There are several ways to kick off the transcoding process. These are:

Load to encode: Most common way to queue videos. Ensures that only the videos you request are transcoded.
Uploading with Asset Manager: Useful for users with access to the Asset Manager. Any videos uploaded through the Asset Manager will be transcoded automatically.
To queue any video for processing, you must make a request for any video using the .video domain extension. This will return a 423 Processing status code to indicate that the video is being transcoded.
Crawling your Origin: Periodically crawls your Origin for new videos. Useful for users with a large number of videos that are frequently updated. Please get in touch with our support team to enable this feature.’

You can begin applying Long-Form Video parameters once transcoding has finished.

The processing time will vary depending on the video’s length. Processing progress can be tracked in the Asset Manager, where videos are marked in one of the following status states:

Processing: The video is currently being processed by our service
Processed: The video has been successfully converted and can now be served through the imgix.video domain
Error: There was an issue processing the video_createMdxContent

A video will undergo encoding only once. After that, it will remain encoded indefinitely unless a change to the video file is detected at your Origin. To submit a video for reprocessing, use the refresh endpoint.

A video will return an error state if the video is incompatible or if there are issues with accessing the video. To ensure consistent video transcoding, it is recommended not to rename or remove the video once uploaded to your Origin.

How HTTP Live Streaming (HLS) Works

HTTP Live Streaming (HLS) is a streaming protocol allowing you to stream video content online. HLS breaks the video into small chunks and serves them over HTTP. This allows for adaptive bitrate streaming, which means that the video quality can be adjusted based on the viewer’s internet connection.

When you request a video using the .video domain extension using HLS, a chunk of video will be returned to determine the best bitrate for the viewer’s internet connection. The video’s bitrate will then adjust dynamically based on the viewer’s internet connection. This allows for a smooth streaming experience, even on slower connections.

Video Captions

Captions are auto-generated for Long-Form Video.

Enabling captions varies between all video players, but typically, there is an option to turn them on at the bottom-right of the video. If captions are available, most video players, including Imgix, will pick them up automatically.

The list of supported languages is as follows:

Bulgarian
Catalan
Croatian
Czech
Danish
Dutch
English
Finnish
French
German
Greek
Italian
Norwegian
Polish
Portuguese
Romanian
Russian
Slovak
Spanish
Swedish
Turkish
Ukrainian

Video Captions can be enabled from the Dashboard on Sources that have the Video functionality enabled.

Video Watermarking

Watermarking is a feature that allows you to add a logo or image to your video. It must be configured in your Source settings where Video functionality is enabled. There are various settings for controlling the watermark’s position, size, and opacity.

You can configure the watermark setting in your Source Dashboard settings.

In this example below, the Source configuration specifies watermarking the Imgix logo at the bottom right of the video.

To refresh the watermark settings on videos, you can use the refresh functionality or contact support to reprocess your videos.

All or Nothing Watermarking

Watermarking is an all-or-nothing feature. If you enable watermarking on a Source, all videos in that Source will be watermarked. You cannot choose to watermark only some videos in a Source.

If you need to watermark only some videos, you can create a new Source pointing to the exact Origin and enable watermarking on that Source. This will allow you to have two different Sources with different watermark settings.

Removing a Video

Unlike the Rendering API, videos will continue to be scanned for availability at your Origin. If a video is removed from your Origin, the following will happen:

The video URL will no longer support playback
The asset’s status will change to deleted in the Asset Manager

Acceptable Video File Formats

We accept any video file format as input. To ensure successful processing of videos, an appropriate video content type should be defined both in the metadata of the video and in the header response when the video is requested from your Origin.

The maximum duration for any single asset is 12 hours. For more information about standardizing video inputs, see our guide on optimizing video performance.

Limits

Video Caching

Imgix does not directly control cache configurations for video content, and cache-control headers do not affect video delivery. Cache behavior may vary depending on the video format, such as HLS .ts chunks or MP4 renditions, and may evolve to ensure the best possible experience.

Using Videos in a Web Player

HLS videos are not supported in all browsers. When you open a Long-form video with HLS on an unsupported browser, you may download a chunk of the stream instead of opening it.

To play and stream HLS videos, you need to use a web player that supports HLS video playback. This will allow you to use the same video URL across all browsers and devices.

Here is a code example that uses the ix-elements library to stream Imgix videos:

<!-- Note: type 'module' here is important -->
<script
  defer
  type="module"
  src="https://static.imgix.net/ix-player/@latest/dist/ix-player.mjs"
></script>
<ix-player
  gif-preview
  type="hls"
  src="https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?ixembed=docs&fm=hls"
>
</ix-player>

Click here to modify this in a CodeSandbox.

For more information about video players, see the Creating a User-Friendly Video Player tutorial.

Video Width Format