Twivel is shutting down
It's been a incredible journey but I've decided to wind down Twivel. I'll be sharing more soon.
How to make an Apple TV app | Twivel

How to make an Apple TV app - the complete guide.

Here at Twivel we love the Apple TV. It provides a rich interface for finding and viewing great video. We think it provides video producers an incredibly exciting opportunity to get straight in front of their viewers without the need for any broadcaster or platform getting in the way.

In this guide we take you through the detail of how to create an Apple TV app and point you to some of the best resrouces on the web.

The basics

Apple TV and tvOS, the operating system which powers it, is a very powerful platform. You can build anything that you could build on iOS. In this guide we are going to take you through the different ways you can create Apple TV apps. In this guide we will focus on apps whose main purpose is to enable users to navigate through a selection of videos and then play them. Now is a truly great time to be creating apps for Apple TV. There are only ~6000 tvOS apps vs nearly 2m iOS apps. Let's get started!.


There are a few terms we are going to have to understand before we get started.

tvoS is the name of the operating system which powers the Apple TV.

TVML is an XML based templating language which enables Apple TV to have a common look and feel.

TVJS is a set of javascript methods which bridge the communications between a server which hosts videos and the native app. This javascript runs on an external server.

When creating apps you will use a combination of all three of tvOS, TVML, TVJS, depending on the strategy you choose.

Choose the best architecture for your app

Apple TV apps have a maximum size of 250mb which is not much space for video files! This is because it is intended that you pull in videos from an external location rather than including them in the app.

Depending on the type of app you want to build you can use a different architecture:

  • tvOS only. If you have a simple utility app or game this may be all you need. You can develop your app in the same way you would for iOS. The downside is that users will quickly get bored of this kind of app as there is no fresh content.
  • tvOS + external content feed. If you want to create an app with a unique user interface and show videos, images or sound to your users, then this is a good setup. Whilst this let's you create a more unique experience this approach has several downsides: creating pure tvOS apps can be time consuming and unique user interfaces are often difficult for users to navigate if they are more familiar with standard interfaces.
  • TVJS + TVML + external content feed. If you are happy to use Apple's TVML templates you can create an Apple TV app using only javascript and minimal tvOS code. You can load resources like videos and images from an external feed. This is the kind of app we will concentrate on in this guide.
diagram of how to make an Apple TV app

The app

We will break this section down into three parts to cover the separate components.

1. The app. In this case the tvOS app itself will be very simple and make a call to the server running the TVJS. You can see an example of what this should look like in Apple's example code.

You will need to use Xcode to edit this code. Here you can also add icons and modify other properties.

2. The TVJS. The TVJS sits on the server. When the app is opened, it is downloaded and executed by the app. TVJS can control all the logic within the app, for example, the navigation behaviour, when a user selects an image you can play a video or move to a new screen. You can also handle things like analytics and search.

3. The TVML. With TVML there are broadly two options. It can sit within the javascript code or it can come from the content feed itself. A common pattern is to consume a JSON feed and use JS based TVML templates to render it.

There are many different TVML templates you can choose from and some of them take different appearances depending on configuration.

Now that we have got our container app, our TVJS to control the logic and the TVML to control the layout, we are missing one important thing: the content.

The content feed

The content feed will contain not just the videos but thumbnail images, titles, descriptions and other metadata. The feed could come from an existing source e.g. an RSS feed or it could come from a dedicated CMS e.g. Drupal or Prismic.

If the feed is only being used for Apple TV you could output the feed in TVML. Alternatively if the feed is being used for other platforms a JSON or XML encoding would be more appropriate.

Assets such as images and videos will need to be hosted on a server and ideally with a CDN in place to allow for rapid downloading.

Video encoding for Apple TV

Although you can use a regular MP4 video file, if the video is longer than 5 minutes it is recommended that you follow the official HLS encoding spec.

HLS encoded files consist of a playlist which points to multiple video streams encoded at different bitrates. Those streams are broken down in small (2 - 10 second) segments. This means that downloads can begin playing very quickly. The most suitable bitrate will automatically be selected based on the available bandwidth. We can assume that Apple TVs will always be connected to broadband and therefore you only really need to encode at a high bitrate e.g. 3000kb/s.

User Experience Considerations

The user experience of a TV app is very different from that of a mobile app or website. The major difference is that the user is often 2 - 3 meters away from the screen. This requires that images, text and other display elements need to be much larger.

Making design and UX decisions from in front of the computer can often lead to elements being too small. We recommend that you regularly preview your app on a TV to experience the app as a user would.

Before starting on planning the UX of your app we highly recommend you familiarise yourself with Apple's UX guidelines for TV.

Universal Purchase

Universal Purchase lets you pair your Apple TV app with your iOS app. You need to release both apps under the same app record. Once enabled, when a user downloads the app on iOS it will automatically download on their Apple TV. It is still too early to tell, but we think this will really help with app discovery distribution. The Apple TV App Store is still quite a difficult place to search and discover interesting apps.


We made Twivel because the people creating the content we want to see on TV should not have to go through this long process to have their own app for Apple TV.

With Twivel all your need to do is to upload images, enter text, configure your homepage and you are good to go. No need to worry about hosting, servers or CDNs, we take care of all of that for you. All you need to do is bring your awesome video content and you're good to go.

Recommended resources

There are tons of resources out there to help you create Apple TV apps, here are some we found really useful:

Create Apple TV & iOS apps with no development .

Twivel is a simple & poweful platform, trusted by major media brands, for creating and managing video apps for Apple TV, iPad and iPhone. Contact us for your free trial.