Working With The Twitter Videos API

Twitter now allows people to upload videos directly to the micro-blogging platform. It's an attempt to bypass 3rd party sites like YouTube (owned by Google) and Instagram (owned by Facebook).

In an uncharacteristic display of openness, Twitter's API allows developers to get direct access to video.

This is a quick blog post to explain how you get access, and what you can do with the information.

I presuppose that you're already familiar with the Twitter API and know how to make basic calls.

Entities

Upon requesting a status (either individually or as part of a timeline) your program will receive metadata about the post, stored in the entities node of the JSON.

One of these entities will be the imaginatively named "extended_entities".

If we request this specific Tweet:

katie

@katiemoffat

A dull video of my cat to test twitter videos pic.x.com/cGazAn7H3E

---

The "extended_entities" looks like this :

 JSON"extended_entities": {

    "media": [

      {

        "id": 567972074346807300,

        "id_str": "567972074346807296",

        "indices": [

          46,

          68

        ],

        "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/567972074346807296/pu/img/uz53Ap4wEah7cV50.jpg",

        "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/567972074346807296/pu/img/uz53Ap4wEah7cV50.jpg",

        "url": "http://t.co/cGazAn7H3E",

        "display_url": "pic.twitter.com/cGazAn7H3E",

        "expanded_url": "http://twitter.com/katiemoffat/status/567972190639022080/video/1",

        "type": "video",

        "sizes": {

          "small": {

            "w": 340,

            "h": 340,

            "resize": "fit"

          },

          "thumb": {

            "w": 150,

            "h": 150,

            "resize": "crop"

          },

          "medium": {

            "w": 600,

            "h": 600,

            "resize": "fit"

          },

          "large": {

            "w": 720,

            "h": 720,

            "resize": "fit"

          }

        },

        "video_info": {

          "aspect_ratio": [

            1,

            1

          ],

          "duration_millis": 6605,

          "variants": [

            {

              "bitrate": 832000,

              "content_type": "video/mp4",

              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/480x480/eU1s1ig_skHgeRjB.mp4"

            },

            {

              "content_type": "application/x-mpegURL",

              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/pl/tr7sF7aHBPOCuL8H.m3u8"

            },

            {

              "bitrate": 832000,

              "content_type": "video/webm",

              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/480x480/eU1s1ig_skHgeRjB.webm"

            },

            {

              "bitrate": 1280000,

              "content_type": "video/mp4",

              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/720x720/njkDGgpJBpsTjQD3.mp4"

            },

            {

              "bitrate": 320000,

              "content_type": "video/mp4",

              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/240x240/Gye4gcWtlJq8zXhF.mp4"

            }

          ]

        }

      }

    ]

  },

As well as a static thumbnail, we are also given a list of direct links to the video files. extended_entities->media->video_info->variants

Here's where things get a little confusing...

• Three of the videos are MP4 files - each with a different bitrate.
• There is one WEBM video.
• Finally, there's an HTTP Live Streaming link suitable for iOS.

The videos are in an unordered list, so you'll need to parse each one carefully to pick the right format.

One Video To Rule Them All

It's tricky to know which file to display to a user. The lowest bitrate MP4 will probably play on most devices. The WEBM is good for modern browsers apart from IE. The streaming link is unlikely to work with desktop machines and older phones.

There's no filesize information, so you can't present that to a user and allow them to make a choice.

There's no direct access to the resolution of the video. If you look at the URL : https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/240x240/Gye4gcWtlJq8zXhF.mp4 You should be able to extract the resolution from the string. In the above case, it's 240*240.

Unless you are absolutely sure of your user's device capabilities, stick to the MP4 version. Hopefully the lowest resolution will always be the last element of the array.

Ideally, I would have liked to have seen Twitter provide a canonical URL - point the user at that and let Twitter decide on the best format and directly serve it. At the very least, it would be helpful to provide filesize and resolution in the metadata.

In HTML5, it's easy to add multiple sources to allow the browser to determine which one to play :

 HTML<video controls>

  <source src="foo.m3u8" type="application/x-mpegURL">

  <source src="foo.webm" type="video/webm">

  <source src="foo.mp4"  type="video/mp4">

  Your browser does not support the <code>video</code> element.

</video>

That should display like this :

I'm not aware of a (simple) way to advertise differing bitrates and resolutions. You can use hacks like media queries to determine screensize, or try using a video playback solution like Video.js;

If you want a fuller explanation, I advise reading Dive Into HTML5's Video section.

Searching For Videos

There's nothing in the search API which allows you to specify that you only want results with videos. A hacky way to get them is to search for the string "/video/1". You might get a few false positives, but it's all that's available for now.

Where Next?

Hopefully we'll see more 3rd party apps supporting the display of video - I'll be updating Dabr shortly.

At the moment, the Twitter API only allows Animated GIFs to be uploaded by third party clients - video is restricted to official apps. I hope that will change in the near future.

I can't wait to see what interesting art and data comes from this.