Skip to content
Tom Miranda edited this page Jan 2, 2017 · 40 revisions

SageTV For Echo

Installation (Alpha Users)

Please note: If I have granted you access to the skill you are actually registered as a developer of the skill. As such you can edit various settings or even delete the skill. Please don't! Feel free to poke around (looking at the "interaction model" may be interesting) but don't change anything!

Step By Step Instructions:

  • Create a developer account in the Amazon Developer Portal located here. (Make sure you use the same email address as you used to register your Echo or Dot.) Then, follow the instructions here. I will do steps 1 - 4. You must do steps 5 - 9.
  • Unzip the manifest I email you and copy it to the Sage install directory. (That's where the SageTV executable is located.)
  • Install the "Sage for Echo" plugin. (Must be done on something other than a SageClient.)
  • If I emailed you a file called echoFunctions unzip it and place it in the sagex/services directory. (Overwrite the existing echoFunctions.js file.)
  • Create a jetty user with the name "echo" and password "alexa-XXXX-XXXX-XXXX-XXXX" where the X's are your locator ID. Do this by editing the file located in the jetty/etc directory on your Sage server. The line should look like this: echo: alexa-XXXX-XXXX-XXXX-XXXX,user. Note that passwords are case sensitive and all characters other than "alexa" MUST be upper case. If you do not know the locator ID it can be found in the System Information menu.
  • Configure port forwarding on your router making sure the port being used by Jetty is forwarded to your Sage server.
  • The default configuration assumes Jetty uses port 8080. To use a port other than 8080, say "use port xxxx". You will be prompted to enter a port number if the skill can't connect on port 8080.
  • Reboot your server.

The first time you invoke the skill you will be prompted to enter the Locator ID of your SageTV server. If you do not know the Locator ID it can be found in the Setup -> System Information menu. When prompted speak each hexidecimal digit one at a time. You should wait until the Echo repeats the digit before speaking the next. If the Echo does not get a digit correct say "no" and then say the digit again. If you want to start over again say "Reset the locator".

To hear the current locator say "What is the current locator?".

Once the last digit is spoken the skill will attempt to contact the server.

Quick Start

Once you have successfully entered the locator ID I recommend you start by asking Alexa to open SageTV by saying "Alexa, open SageTV". The skill will tell you your system status and then ask you what to do next. To access your recordings say "Go to TV". Your "virtual view" will be recordings grouped by title. (If you say "Go to videos" your virtual view will be all videos grouped by title.)

Note that this will not cause anything visible to happen on your TV.

To go to the next or previous group say "next" or "previous". For details see the section "Commands That Act Upon Groups".

To go to the recordings in the group say "select". (To go back to the groups say "back".) For details about what you can do to recordings see the section "Commands that Act Upon Airings".

If you are in a large list or group you can say "skip to the letter <letter>", or "skip to the group <group name>".

To play a recording say "play the first episode of <show name>" or just "play the latest episode of <show name>". This functionality is still in the "alpha" stage.

The show will play on the first instance of SageTV the skill can find. To use a particular TV use the UI Mod plugin to name your TVs (under Setup -> Detailed Setup -> Customize) and pick a name for the TV. Then say "use the TV in the <room name>".


Commands that Act Upon Airings

In SageTV every recording and video is an "Airing". In this wiki I will use the terms interchangeably. When Airings are in focus you can do most of the same things that you are used to doing to recordings. For example, you can:

  • Add it as a Favorite by saying "Add it as a Favorite".
  • Remove it as a Favorite by saying "Remove it as a Favorite".
  • Delete it by saying "Delete it".
  • Mark it Watched, or clear the Watched status by saying "Set it Watched", or "Clear Watched".
  • Set it as "Don't Like", or clear the "Don't Like" status by saying "Set Don't Like", or "Clear Don't Like".
  • etc.

You can also ask some basic information about the Airing such as:

  • "When did it record?"
  • "What was the original airing date?" or "When did it originally air?"
  • "What's the title?"

To hear many of the details about the Airing say "tell me the details".

To watch the Airing say "Watch it in the <name>", or to watch it on he default UI just say "Watch it". Note that the default UI behavior is explained in the section "Commands That Act Upon a Sage UI".

Sorting and Filtering

You can sort and filter the airings by saying things such as:

  • "Sort by title"
  • "Sort by date"
  • "Filter out watched"
  • "Filter in favorites"

Note that for filtering the default is "in", so "Filter in archived" and "Filter archived" will do the same thing.


To group the Airings say "Group by title". Currently this is the only grouping that is supported.

Commands That Act Upon Groups


  • To go to the next or previous group, say "next" or "previous".
  • To skip to a group that begins with a certain letter, say "skip to <letter>".
  • To go to the Airings in the group, say "select".

Sorting and Filtering

Commands That Act Upon a Sage UI

In this wiki I will generally use the term "UI" or "context" to mean any SageTV extender or SageClient. This section contains all of the commands that act upon Sage UIs.

Naming The UIs

In order to name the UIs (TVs) you will need to install the Echo UI Mod Plugin through the Plugin Manager. Once that is done go to Setup -> Detailed Setup -> Customize. Towards the end of the list you will see "Name for Echo".

Getting The Names

To hear the names of the configured UIs say "what are the names of the extenders?"

Selecting the Default UI

By default when you watch something it will be displayed on the first TV the skill finds OR the TV you have specified as the default. To make a particular TV the default you can say any of the following:

  • "Make the TV in the <name> the default"
  • "Use the TV in the <name>"
  • "context <name>"

If you specify a UI when you ask the command (for example, "play it in the living room") the skill will try to access that specific UI. If the UI is not available the command will not be executed. If you do not specify a UI in the command (for example, "watch it") the skill will:

  • Use the UI that you have selected as the default. If it's not available then the skill will
  • Use the first active named UI it finds. If it's not available then the skill will
  • Use the first active UI it finds.

Sending Raw Commands

You can send "raw" commands directly to the UI just as if you had pressed a button on the remote control. To do this first make sure you have selected a default UI then just say "command <name>". For example:

  • "Command pause" will pause a playback if a video is playing.
  • "Command guide" will jump to the programming guide.
  • "Command options" will bring up the options menu.
  • "Command volume up" will increase the volume.

Commands That Create Views

A view is simply a set of recordings or videos that have been automatically grouped and sorted. Currently the skill supports the following views:

  • "TV" or "Go to TV" will get all recordings, group them by name, sort the groups by title, then sort the episodes by original air date.
  • "Videos" or "Go to Videos" will get all videos, group them by name, sort the groups by title, then sort the episodes by original air date.
  • "Movies" or "Go to Movies" will get all recorded movies and sort them by title.

To customize these views start by saying "Get all recordings" or "Get all videos". Customize the view as you like by grouping, sorting and filtering, and then say "Save view". The next time you say "TV" or "Videos" the customized view will be restored.

Commands That Return Status

  • "What's the locator ID?"
  • "Is anything recording?"
  • "What's currently recording?"
  • "What's new?"
  • "Are there any conflicts?"
  • "Are there any alerts?"
  • "Is my server up?"
  • "What's the heap usage?"
  • "How much disk space is available?"
  • "What's the status of my system?"

Miscellaneous Commands


To enable debugging say "debug on". To turn it off say "debug off". When debugging is enabled various information will be written to the logfile, which is not accessible to the user but is accessible to me and will help me fix problems. You may notice commands take a little longer to execute when debugging is on.


To reboot your Sage server say "reboot". You will be asked to confirm the command before the server is rebooted.


This will tell you the software version.


If you want the Echo to continue waiting without ending your session, say "Wait".

Wrap Lists

This will control if lists (and groups) "wrap around". If set to "off" then if you are the bottom of the list and say "next", you will not be able to go any further. If set to "on" you will be brought back to the top of the list.

To change this setting say "List wrap <on or off>", or "Set list wrapping <on or off>".


Searching is fairly limited at this time. Due to the constraints of the Echo searching by title, or actor, or any random keyword is not possible. It is only possible to search on fields that you already know the possible values. For this reason right now you can only search by genre.

To search by genre say "Search <genre>". That will return a list of all Airings that match the genre. You can then filter, group, and sort the result to your liking. Note that this will return all of the Airings in the SAge database (past, present and future).

To get recorded shows with a particular genre say "Get <genre> recordings." To get recorded movies with a particular genre say "Get <genre> movies."

Clone this wiki locally
You can’t perform that action at this time.