How to Build a Fire TV App, It’s Easier Than You Think
If you can build a website, you can build a real Fire TV app
Disclaimer: I have no official relationship with Amazon but I am a developer with experience working on streaming TV apps for another major content provider. Views are my own.
Not many people are building TV streaming apps. There typically aren’t a lot of open-source projects for platforms like Apple TV (tvOS), or Android TV. So, you would be right to consider that these platforms are difficult to break into.
And, as someone who’s spent time in the industry, it’s apparent that the tools available for these devices target industry insiders, not everyday developers.
But what if I told you that one of the largest up-and-coming Connected TV ecosystems was accessible to anyone who can hack together a simple webpage, with HTML5, JavaScript, jQuery, or other simple web technologies?
What if I told you most Fire TV apps are simple web pages, running in a modified Chromium runtime (you’re familiar with Google Chrome, right?)?
Amazon even gives you the tools to automatically package any web page or static web app to run on Fire TV.
Even better, Fire OS itself is just a simplified version of Android, there’s no fee to publish an app in the Amazon Appstore, and the very same apps you publish for Fire TV can be published to other Fire OS devices, like the Fire Tablet.
Well, it’s all true.
Welcome to the wild west of CTV app development.
Nearly 40 Million Users and Growing
When I say that the Fire OS platform is growing fast, I mean fast.
And, as Amazon seems intent on almost giving away Fire OS hardware at this point, their marketshare is only going to grow.
Fire OS started the year at 30 million active users, surpassing Roku to take the #1 spot in the streaming hardware market. Later reports, prior to Prime Day, pegged the device at 34 million users.
And, during the Prime Day event, the Fire TV Stick was featured heavily, becoming the best selling deal of the two-day Prime event.
So, it should come as no surprise that research groups, such as eMarketer, forecast that Fire TV will reach nearly 70 million viewers by 2021.
If you’re looking for a new project to sink your teeth into, why not try your hand at building a Smart TV streaming app?
What We’re Going to Build
App 1: Live TV streaming app
Difficulty level: ridiculously easy.
For the first app, we’ll be taking advantage of a recently-launched broadcast TV streaming service that’s part of the Stanford Puffer project.
It already features most of the functionality we need to build a working Fire TV app and demonstrates how easily existing web technologies can be used to create rich Connected TV applications.
App 2: YouTube streaming app example
Difficulty level: moderate.
For the second app, we’ll be taking a look at a Fire TV example codebase, demonstrating more features of a polished Connected TV application.
Getting the Right Tools
As a minimum, you’ll need a Fire TV Stick to get started with this tutorial.
Maybe you picked one up for $14.99 with two months of HBO included during Prime Day? If not, no sweat. Currently, the best deal I could find is a 4k streaming TV Stick for $44.99 (Amazon, US) — which is still a great deal. (Don’t worry, that’s not an affiliate link.)
1. Amazon Web App Tester
Next, you’ll want to download the Amazon Web App Tester from your Fire TV device.
You can do so by searching for “Web App Tester” with your voice remote.
2. Pro tip: connect a USB keyboard for development
Remember, Fire OS is just Android. Most USB devices are going to work just fine (all you need to do is plug them in).
I have a Fire TV (Element) so connecting a USB hub is easy. But, if you’re using a Fire TV Stick, you may need to purchase a USB OTG cable.
This probably costs about $3 on eBay or slightly more on Amazon.
It connects between your Fire TV Stick and power cable, exposing a single USB port that you can use to connect a thumb drive, USB keyboard, or USB hub.
Getting to Know Your Input Device(s)
Now that we have the Web App Tester set up, let’s use it to learn a bit more about our input devices.
Head over to https://keycode.info/ on your Fire TV device, inside the Web App Tester, by creating a new “app”, entering the URL: https://keycode.info/, and pressing Add to Device.
Once you’ve done so, you will see a list of apps you can run, then click Test on the right side of the screen to launch the app.
This should appear on your TV:
Press Keys on Your Remote
You should be met with a very pleasant surprise: your basic navigation controls are the exact same key codes you would use with any web app and keyboard.
The Fire TV remote maps to your normal arrow keys, Enter for OK, and Escape for back.
Additionally, focus-state management is handled automatically for HTML5 apps, and the Chromium browser obeys web history/typical back-button behavior.
An unhandled press of the back button is equivalent to history.back().
You don’t have to overthink this. Just build a decent web app without a ton of weird absolute/fixed positioning hacks and let Fire OS do the heavy lifting (for now).
I would recommend focusing on the following keys, and ignoring others:
Back Button: 27
OK Button: 13
Arrow Left: 37
Arrow Up: 38
Arrow Right: 39
Arrow Down: 40
Rewind: 227
Play/Pause: 179
Fast Forward: 228Avoid attempting to overload the Voice remote button, Settings/Menu button, Home button, volume controls, and speciality buttons (such as the Netflix and HBO buttons on some physical remotes).
Not only are these keys missing from many devices, overloading these keys may be confusing for users. And, while it may be possible to prevent the default action of these keys now, this may break in future updates and I’ve already seen this behavior change between releases.
Hacking Together Our First App
For our first app, we’re going to hack together a version of an existing web app, Puffer, as a proof of concept to learn more about how a Fire TV app works.
With this, we can watch a few free broadcast TV channels on our Fire TV.
The app re-broadcasts six Bay Area channels (CBS, NBC, PBS, Univision, Fox, and ABC).
You’ll need to sign up for an account (easy, no email or verification required), and “agree to be in the USA”, possibly for legal purposes. You may not actually have to be in the USA, though…
First step: log in to Puffer
First, you’ll need to log in to Puffer, get to the player page, and see it working in your local Chrome browser.
Fork My Repo on GitHub (Optional)
Instead of following the guide below, you can also just fork my repo.
Just be sure to update the session details in the bottom of index.html if you skip the following steps in the DIY guide.
DIY Guide/How It Works
Download the web page and run a local development server
You’ll have to do a tiny bit of re-writing of the existing page to get started.
The easiest way to get started is to view source for this page:
view-source:https://puffer.stanford.edu/player/Create a new folder, puffer, and copy and paste the contents of this page to a new file, index.html.
Fix relative URLs, JavaScript
Next, search and replace all of the relative URLs that start with /static/puffer/ with absolute URLs, such as: https://puffer.stanford.edu/static/puffer/dist/js/jquery-3.3.1.slim.min.js
Next, you can (optionally) remove all the Analytics tracking code.
Now, you’ll want to download two JavaScript files to your puffer directory.
https://puffer.stanford.edu/static/puffer/js/player.js
https://puffer.stanford.edu/static/puffer/js/puffer.jsYou’ll notice that the line near the end of index.html references player.js. Modify it to point to your local file:
<script src="player.js"></script>Fix WebSockets
Next, you’ll need to fix the WebSockets so they point to the Puffer server (not your own).
This is on line 662 of puffer.js (you can search for location.hostname)
Replace location.hostname with:
'puffer.stanford.edu'To make:
const ws_host_port = 'puffer.stanford.edu' + ':' + port;Running the App Locally
I’ve added a package.json file so you can easily run the app locally on your machine, if you already have a Node environment.
You can run this with the following command:
npm install && npm startWhich will open up a new server on http://localhost:1111/ running your web app.
If you have your network set up to do so, you can even enter this directly in your Fire TV device for testing, using the Web App Tester.
Update Session Details With Your Own
If you forked my repository, you’ll need to grab your session details from the bottom of this page after logging in:
view-source:https://puffer.stanford.edu/player/And, replace my “fake” details with your own:
See the video:
This code, near the bottom of index.html, contains some session details required to connect to the stream and may become invalid after one to two hours.
Keep this in mind: If you start receiving errors, you’ll need to re-open the page on your main computer and update this code.
Deploying Your App
The easiest way to deploy your app for testing is probably GitHub & GitHub Pages (free).
After creating a new repository, you can upload your example files via drag-and-drop (no Git skills required!).
Your gh-pages branch will be public on the web.
The fastest way is to just fork my repo and update your session details at the bottom of index.html.
Make sure you’re editing the right branch with your current session details!
Once you’re finished, you can use your gh-pages URL with the Amazon Web App Tester to see your app live.
Your final URL will be something like this:
https://kidgodzilla.github.io/puffer-firetv-example/
With the username being your own, not mine.
It should look like this:
On your remote, you can use the UP / DOWN keys to change channels and LEFT / RIGHT to adjust volume.
For me, the video is muted every time I change channels and I need to press RIGHT to unmute after changing channels.
Advanced: Add More Features/Update Styles
Automatically unmute video
If you like, you can add this script tag just before your </body> tag, to automatically unmute video:
Update/fix styles
I’ve written a small snippet of CSS that you can use to “fix” the CSS styles for the app to simplify things on the Fire TV.
Place this inside your <head></head> tags (at the end, before </head>):
Continue Exploring
If you would like to continue exploring the Fire TV app development using HTML5 technologies, I would suggest taking a look at the examples in the official Amazon repo on GitHub:
Live examples/demos
Have Fun! I hope this helps you to get started on your Connected TV app-building journey.
