Getting Started with Video

Configuring your Source for serving video

Note: 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 to get more information on this feature.

In order to use the Video API, you first need to create a Source and aks your account manager to enable the feature. If you already have a Source connected to an Origin with video assets that you want to serve, you can also use that existing Source with the Video API.

For your initial Source configuration, you should define the subdomain you want to serve videos from, and the path from which your videos should be served from.

Configuration options

These are the relevant Source configruation fields for using the Video API:

• imgix Video Subdomain: This is the domain that will be used to stream videos. This is a non-editable field, and it inherits the same subdomain as the imgix Image Subdomain value. Unlike the Rendering API, the Video API uses the .video subdomain. For an in-depth breakdown of how assets are served using the rendering api or the Video API, see our documentation on Serving Assets
• Path Prefix: Specifies the parent path to be used when serving assets. You should choose a path that includes all the assets you want to serve.

If your Source is going to be used to only serve video, then you can simplify your configuration by using a path that only includes video files and folders.

• Asset Processing Rules: Similar to the Path Prefix, this adds an additional layer of routing for the Asset Manager. It’s core use case is to define which paths the Asset Manager will (or won’t) crawl. Since the files you serve with the Video API must first appear in Asset Manager served, you can use these rules to refine which videos (and images) that will show in Asset Manager. Note that this does not affect which assets you can serve with the Rendering API, but it does affect which videos can be served with the Video API.

Once you have set-up your account, contact the Sales team to enable the Video API for that Source. After it is enabled and configured, you can begin adding videos to your Origin. If you have videos already in your Origin, we will crawl and add them to the Asset Manager.

Uploading a video

We recommend uploading videos using the Management API’s upload endpoint or by using the Asset Manager user interface. Both of these methods immediately populates videos in Asset Manager, decreasing the time it takes for those videos to be available through the Video API.

From the time a video is first populated in the Asset Manager, we have seen historically that it takes 5 seconds to 5 minutes for less than 15 minutes videos and 10 seconds to 40 minutes for 60 minutes video to be available via Video API but duration can be longer for longer length videos

Alternatively, you can upload videos directly to your Origin without using imgix uploaders. Videos detected at your Origin will be available as soon as they are detected, which happens at intervals during the day.

Updating a video

We recommend uploading a video with a new file name in order to update a video. If you need to otherwise update a video while preserving the filename, you can replace the video at your Origin and then use the refresh endpoint to refresh the video.

Once a video is refreshed, it will go through the transcoding process again.

Deleting a video

To remove a video, you must delete the image at your Origin and then remove it from the Asset Manager. To do this:

• Delete the Video from your Origin
• Wait until we detect the video as deleted (we check throughout the day)
  • Alternatively, you can call the refresh endpoint to update the asset status immediately
• The video URL (both the .net and the .video) will automatically return a 404 error

Transcoding Videos

Before a video can be served with the Video API, it must be transcoded. This process is automatic, and happens either when:

• A .video URL is requested for the first time.
• A video is uploaded through the Asset Manager or the Asset Management API
• We crawl and fetch the video from your Origin (occurs regularly throughout the day)

When a video has been requested that has not yet been processed, the request to the video URL will return either a 404 if the video does not exist, or a 423 status code while it is processing.

While a video is being processed, it will continue to return a 423 until the video is done transcoding. Once transcoding is finished, the video can be transformed and served with the Video API. This behavior is called Load to Encode.

Serving Video

The Video API currently supports 2 different formats: mp4 and hls. HLS is the default format when using the Video API, and other formats can be selected by appending the fm parameter at the end of the video URL (ex: ?fm=mp4).

Direct playback is not as well supported for HLS unlike other video formats (MP4, AVI, etc). This is because HLS is a streamable video format, and the video’s bitrate is sent in varied chunks depending on the user’s connection speed.

To play HLS videos on a browser, HLS will require either native browser support or a third-party library (like ix-player for playback).

Here are some examples using the Video API:

• https://assets.imgix.video/videos/northern-lights.mp4 - Serves an HLS file (requires a video player to be viewed)
• https://assets.imgix.video/videos/northern-lights.mp4?fm=mp4 - Serves an MP4 file

MP4 vs HLS

Whether you use HLS or MP4 depends on how you want your videos to be played.

If you want:

• Better seeking
• Advanced video buffering for smooth playback
• To vary the video bitrate based on the user’s internet connection

… you should use HLS.

However, if:

• Your video is under 30s in duration
• You want to lock the video quality
• You don’t want to use a third party library to add universal video playback

… then you should use MP4. For videos with less than 30s playtime, we recommend MP4. Because HLS videos end up being <5 segments (typically 30 seconds or less), you aren’t really getting the benefit of the stream adapting to your bandwidth for videos of that length. At that point, it may be better for the user experience to keep the same quality vs varying it for such a small duration.

Adding a video player

Once you have video enabled, you can now begin serving video on any web page.

If you want to quickly serve the video without having to worry about video players, you can use the fm=mp4 parameter:

https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?fm=mp4

Though, if your video’s duration is longer than 30s, it can take a very long time to load the video fully depending on the user’s bandwidth and network connection.

For videos with a >30s duration, use the HLS format. HLS is returned by default when no fm parameter is specified:

https://assets.imgix.video/videos/girl-reading-book-in-library.mp4

If you visit the video URL above in a browser that does not natively support HLS, you will be prompted to download a manifest file. Since HLS is a streamable format, the file is streamed in chunks and the manifest file is used to outline the various chunks available for playback. To playback those video chunks as a video stream, you need to either use a browser that natively supports HLS or utilize a third-party library or video player (such as <ix-player>) that supports HLS playback.

Here is an example of how to quickly embed an HLS video player using the ix-player custom element video player on an HTML page:

<!-- 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.

Compared to an MP4 file which loads the full res video from beginning to last, the HLS video player does 3 things. It:

• Adjusts the bitrate of the video depending on the user’s connection
• Allows the user to navigate through non-downloaded sections of video (like skipping to the middle)

For more information on creating and implementing videos, please check out our article for creating a user friendly video player.