Search Videos with Hulu Embed API for PHP Developers - PHP Hulu Video package blog

Contents

Introduction

Hulu Video Embedding

Customizing the Embedded Video

Data Mining

Hulu Public Sitemaps

Using Sitemaps for Local Search

Manually Installing Hulu Sitemaps

Conclusion

Introduction

Hulu is a streaming video provider of motion picture films and trailers, television programming, video game trailers and clips. They offer a free service with limited access and a subscriber service called Hulu Plus for full access to their media content.

The PHP Hulu Video class was developed to bring together the limited public resources that they provide into a pseudo-API to make embedding their content into external websites a little easier. We will discuss the different types of resources and techniques that can be used in the class to enrich your users experience.

The first thing we need to do is include and instantiate the class.

error_reporting(E_ALL ^ E_NOTICE);
include('hulu.class.php');
$hulu = new hulu;

Hulu Video Embedding

The public method Hulu has made available for serving their content on an external Web site is by embedding the video feed into an inline frame using their own player. While all of their content can be embedded, the premium subscriber content will only stream a short preview.

All of Hulu's content is identified by a unique numeric identifier. For example, in the URL http://www.hulu.com/watch/142476, the video identifier is 142476.

Hulu also provides an embed identifier. For the above show, the embed URL is http://www.hulu.com/embed.html?eid=LvlJ_IAZOQLb6tQgx2vy1w and the identifier is LvlJ_IAZOQLb6tQgx2vy1w.

To further complicate things, Hulu also has a resource identifier used for images. For the above show, the URL for a large thumbnail image is http://ib.huluim.com/video/50045978?size=512x288&caller=h1o&img=i and the resource identifier is 50045978.

Don't worry, all the class needs to manage this is the video identifier. We can include it when instantiating the class:

$hulu = new hulu(142476);

We can set it manually after the class has been instantiated...

$hulu->videoID = 142476;

...or we can set it when we retrieve the video data using the setData method

$hulu->setData(142476);

The setData method is the primary class method for retrieving video data, the public embed data is always set, and can be used in the following ways:

$hulu->setData(); // The video id has already been provided
$hulu->setData( 142476 ); // Providing the video id
$hulu->setData( 142476, true) // Include data from data mining techniques
$hulu->setData( 142476, null, true) // Include data from public sitemaps

The last two attributes can be set to either true or false and default to false if not provided. We will discuss the data mining techniques and the public sitemaps a little later in this article.

The public embed data provided is very limited. The primary information it contains is the video title, embed markup, and thumbnail source.

If all you want to provide is the video, here is a full implementation for the example movie using the class.

error_reporting(E_ALL ^ E_NOTICE);
$videoID = 142476;
include( 'hulu.class.php' );
$hulu = new hulu;
$hulu->setData( $videoID );
echo $hulu->embedData[ 'html' ];

Providing a different videoID will display the video related to that identifier. Once the setData method has been processed, the embedData property will contain all the embed data provided by Hulu.

The associative key html contains the full markup for the embed player. If you want to see all the associative keys and values available, you can use the following code to display the embedData contents.

var_dump( $hulu->embedData );

Customizing the Embedded Video

Hulu allows you to customize the video players size, the starting and ending points of the video to be played and the image displayed when the video is first loaded.

To do this in the class, we use the buildEmbed method.

$hulu->buildEmbed( 512, 288, 1638, 1745, 1691, $hulu->embedData[ 'embed_URL' ]);

This will create a player 512x288, start the video at the 1638 seconds point, end the video at the 1745 seconds point and display the still image from the 1691 seconds point.

The only information you are required to provide to the buildEmbed method is the width and the height.

If the starting and ending points are null then the whole video will play. If the thumbnail image is null then the default thumbnail is displayed. If the embed URL is empty, then the one previous loaded into the embedData property is used.

If you do not want to calculate these starting and ending points, I recommend getting them directly from Hulu.

While watching any video on the Hulu site, there will be a share link located just under the video playback. Clicking the share link will expand a container where you can recommend the video to friends through e-mail and just under that form is an <>embed link.

If you click the <>embed link you will be taken to an editor that will allow you to position the starting and ending points and set the image thumbnail. The resulting embed markup will contain the information you need in the key and value pairs st (start), et (end) and it (thumbnail).

et=1745&st=1638&it=i1691

Here is a full implementation to provide a customized embed

error_reporting(E_ALL ^ E_NOTICE);
$videoID = 142476;
include( 'hulu.class.php' );
$hulu = new hulu;
$hulu->setData( $videoID );
$embedHTML = $hulu->buildEmbed( 512, 288, 1638, 1745, 1691);
echo $embedHTML;

Data Mining

To get a lot more information about a video, the class supports data mining the video page. We saw the example to include this data previously:

$hulu->setData( 142476, true); // Include data from data mining techniques

With the second attribute set to true, the class will fill the property videoData with the mining results. This will be everything you ever wanted to know about the video and more. You can use the following code to display the videoData contents.

var_dump( $hulu->videoData );

The class comes bundled with an example.php file which provides examples on how to use this information for a feature rich display. So to avoid turning this article into a book by repeating the techniques already used in the example file, I will just let you know that is the place to find the answers.

Please note that this class feature is not supported by Hulu and can become unstable at any time if Hulu changes their JSON coding on video pages. Should it stop working, you can use the embedData as a fallback or advanced users can manipulate the regular expression in the getDataChunk method to locate and retrieve the JSON data based on the current page changes.

If it does become stable, don't hesitate to use the support forum to let me know and if I am still alive I will find a solution.

Hulu Public Sitemaps

Hulu also provides an XML database of all of their currently available content, which they call sitemaps. This data is constantly updated as they add new content, drop content and make changes like the dates content will be available, etc... There is so much information that Hulu needs to split it up between many sitemaps, there where 52 when this article was written.

Since Hulu does not provide a public api, these sitemaps are also how you would provide search capabilities to your users. They will require you to constantly download them to keep your data up to date, however the class does have a method to help automate the task called fetchSiteMaps.

$hulu->fetchSiteMaps();

The class comes bundled with a fetch_data.php file which will perform pre-download checks to ensure your system is properly set up to receive the files, download the most recent files, and perform the required maintenance to index the files so that the class can use them. You can run this file manually whenever you want update the sitemaps.

Once the files are downloaded and processed, you can also get video data from them.

$hulu->setData(142476,null,true) // Include data from public sitemaps

When the third attribute is set to true, the class will locate the video information contained in the sitemaps and fill the property huluResult. You can use the following code to display the huluResult contents.

var_dump($hulu->videoData);

By default, the sitemap files are contained in a folder named video_data. You can change this by setting the property dataFolder to the correct folder name. This folder must be readable and writable from the script, so you will want to make sure the permissions are set to 666 or 777.

The sitemap files are compressed using gzip, so the class needs the zlib library compiled with PHP to un compress them. If you do not have the zlib library then please make sure you read the next section in this article for manually installing the sitemaps.

In the sitemaps folder there is one additional file named lastid.json. This file is used to store the last id in each sitemap file for indexing purposes so that the class can locate the correct file to retrieve the video information from without having to search through them all. This file is automatically updated by the class whenever it downloads the most recent sitemaps.

Using Sitemaps for Local Search

The class comes bundled with a search.php file which provides an example for a simple local site search. You must have downloaded the sitemaps into their video data folder for this feature to work.

The method for searching is searchHulu function...

$hulu->searchHulu( $search );

where the $search parameter is the keyword being searched for. This method will return an array containing the video information from the sitemap for all matches found.

Since this data is contained in XML files, there are some limitations that you should be aware of. There is currently over 500MB of data to search through, so the search can take a minute or two which feels like forever in today's high speed environment.

To avoid exponentially increasing this search time the class will treat the search text as one keyword, even if it includes more than one word. Searching for common keywords can produce a very large array, eventually when most servers have installed PHP versions that support generators the class can be updated to use less memory with this default search.

If you are really serious about providing a great search experience for your users, I would recommend moving the data into a relational database like MySQL. You would then be able to provide paged results returned very quickly and containing only the data you intend on using. This functionality is currently beyond the scope of the class and this article.

Manually Installing Hulu Sitemaps

This section is intended to provide instructions on manually downloading, uncompressing and running maintenance on the sitemaps in the event that your PHP installation does not support the automated method.

The current sitemaps are listed in this XML sitemap. You can click on the listed sitemap URLs to download them automatically if your browser shows the URLs as links.

Using your favorite archiving application that supports gz compression (mine is 7-zip), open each file and extract the XML file to the sitemaps data folder.

Once all the files are in the sitemaps data folder you will need to perform maintenance on them for indexing. Here is a complete implementation that will set them up for using with the class.

error_reporting(E_ALL ^ E_NOTICE);
include( 'hulu.class.php' );
$hulu = new hulu;
$hulu->createLastJSON();
echo 'Sitemap files have been indexed';

Conclusion

Without an official public API, serving Hulu content can be a challenge and the PHP Hulu Video class was created in the hope that it helps take some of that burden off of your shoulders.

There are limitations on what we, as developers, can accomplish without the direct support of Hulu. Some of these limitations that remain can be seen in this class that you can download here.

I wish you good fortune in your Hulu adventure. Should you have any comments or questions, feel free to post them here.