Video Encoding with the Zype API

You can build awesome video streaming workflows and fully control the user experience by leveraging Zype’s application programming interfaces (APIs). A great place to start is video encoding, the process of taking raw video files and preparing them for distribution by encoding them into formats like HTTP Live Streaming (HLS).  You can also save steps by having them readily available for indexing in a video content management system (CMS) for future distribution. 

To dig deeper, read our complete guide to video content management systems.

In this article, we’ll show you how to encode a video file using Zype's APIs. Once a video is encoded by Zype, you can directly access the encoded, streaming-ready formats. This article focuses on video on demand (VOD) use cases, where you have a mezzanine or raw video file you've already produced and want to prepare for streaming on your website or over-the-top (OTT) app, or syndicate to partners with Media Really Simple Syndication (MRSS).

How to Encode a Video with the Zype API

Step 1: Set Up Your Environment

To get started, you need a Zype account. If you don't yet have a Zype account, you can request one here.

Once you're set up with a Zype account, you can log in to your CMS dashboard.

In this demonstration, we'll utilize the Zype API to perform our encoding exercise. The Zype API documentation can be found here.

To communicate with the Zype API, you need to authenticate each request using an API key. For the purpose of this article, use your Admin API key to import your video and your Player API key to access the encoded streaming formats and distribute your content. You can retrieve your API keys on your Zype account's API Keys page.

To send commands to the Zype API, you can use an HTTP client to send HTTP requests in your chosen programming language. The Zype API documentation allows you to view examples for each API endpoint in various programming languages, such as cURL, Shell, Node, Ruby, PHP, Python, and more.

For this exercise, we'll use a common command line tool called cURL that's pre-installed and available on most Unix- and Linux-based command line platforms. 

Step 2: Apply Presets

Before using Zype's API to encode your video files, you'll need to select encoding presets. Presets define the various file formats that our original mezzanine file is encoded into. In Zype terms, these are called output formats. Zype will automatically set several encoding presets for you.

Step 3: Import Your Video

If your mezzanine file is available to download from a URL on the internet, you can utilize the Zype Import API to import it directly into your Zype account from that URL.

A quick tip: you have options for sending your original mezzanine video file to your Zype account for encoding whether directly through Zype's Dashboard or utilizing the Zype Upload API.

For this example, we'll utilize the Zype Import API to import a video called "Big Buck Bunny" from this URL: https://mirror.clarkson.edu/blender/demo/movies/BBB/bbb_sunflower_1080p_30fps_normal.mp4

Start by opening your favorite command line terminal and executing the following cURL command, replacing ADMIN_API_KEY with the Admin API key you retrieved from the API Keys page:

curl --request POST \
    --url 'https://api.zype.com/video_imports?api_key=ADMIN_API_KEY' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '
{
  "video_import": {
    "title": "Big Buck Bunny",
    "source_url": "https://mirror.clarkson.edu/blender/demo/movies/BBB/bbb_sunflower_1080p_30fps_normal.mp4",
    "to_zype_hosted": true,
    "auto_add": true,
    "auto_activate": true
  }
}
'

This command will create a Video Import in your Zype account. In the background, Zype will download your mezzanine video from the "source_url" you provided in the cURL command, encode the file into Zype's default output formats, and create a Zype video for distribution.

The above command will return a JavaScript Object Notation (JSON) response representing the Video Import that was created, which will look something like this:

{
  "response": {
    "_id": "VIDEO_IMPORT_ID",
    "source_url": "https://mirror.clarkson.edu/blender/demo/movies/BBB/bbb_sunflower_1080p_30fps_normal.mp4",
    "title": "Big Buck Bunny",
    ...
  }
}

The _id field in the response above represents the ID of the Video Import. Let's now retrieve that Video Import to get the ID of the encoded video for publishing. Run the following cURL command, replacing VIDEO_IMPORT_ID with the _id from the previous response, and ADMIN_API_KEY with your Admin API key:

curl --request GET \
     --url 'https://api.zype.com/video_imports/VIDEO_IMPORT_ID?api_key=ADMIN_API_KEY' \
     --header 'accept: application/json'

The response will look something like this:

{
  "response": {
    "_id": "VIDEO_IMPORT_ID",
    "source_url": "https://mirror.clarkson.edu/blender/demo/movies/BBB/bbb_sunflower_1080p_30fps_normal.mp4",
    "title": "Big Buck Bunny",
    "video_id": "VIDEO_ID",
    ...
  }
}

The video_id represents the ID of the encoded video in your Zype account. We'll use this video_id in the next step to retrieve and publish your encoded video.

Step 4: Access and Publish Your Encoded Video

Now that we've encoded our mezzanine file into the HLS streaming format, we can publish it. To do this, we'll need our Player API key, which you can retrieve from your API Keys page in the Zype admin dashboard, along with the VIDEO_ID we retrieved from the previous cURL response.

We'll use the Zype Player API to retrieve an embeddable JavaScript player. Let's first retrieve the HLS manifest of our encoded Zype video. Run the following cURL command, replacing PLAYER_API_KEY with your Zype Player API key, and VIDEO_ID with your video's ID:

curl --request GET \
     --url 'https://player.zype.com/embed/VIDEO_ID.js?api_key=PLAYER_API_KEY' \
     --header 'accept: application/json'

This will return the Player JavaScript code you can use to embed the Zype player on your web page. To do this, we can create a small HTML snippet to embed the video on a web page using the above API URL as the source. Add the following HTML to your web page, replacing [VIDEO_ID] with your video's ID, and PLAYER_API_KEY with your Player API key:

<div id="zype_[VIDEO_ID]"></div>

<script src="https://player.zype.com/embed/VIDEO_ID.js?api_key=PLAYER_API_KEY" type="text/javascript"></script>

This will embed the encoded Zype video on your web page using the Zype player. And that's all we need to do to encode a video file using the Zype API and publish it. 

To see our code in action, we've embedded the above HTML snippet below so you can see the result. Good luck, and happy coding!

If you want to learn more about how Zype can help you encode videos and streamline your workflows, request a demo and get in touch with our team.