Using Launch Parameters

Launch parameters are chunks of information that can be sent to your channel by devices using the Roku External Control Protocol (ECP). ECP is a RESTful API that allows other network connected devices to control a Roku. ECP is documented in the Roku SDK.

When a device using ECP launches a channel, it can also send a collection of parameters to that channel. This ability presents endless possibilities to channel developers. In this article, we’ll explore some of the simplest applications of this mechanism.

Hello World!
Launch parameters are passed to your Main() function as a parameter whose value is a roAssociativeArray. The simplest thing we can do with a launch parameter is display its value directly to the user, so let’s write a very simple channel that does exactly that. First, we need to check for the existence of a launch parameter named message. If that parameter exists, we’ll display it to the user.

sub Main(launchParameters)
  ' setup a poster screen and assign it a message port
  port = CreateObject("roMessagePort")
  screen = CreateObject("roPosterScreen")
  screen.SetMessagePort(port)
  screen.Show()
  
  ' set the default message
  message = "No message received"
  ' check to see if a message was passed in
  if launchParameters.message <> invalid
    message = launchParameters.message
  end if
  
  ' display the message
  screen.ShowMessage(message)
  
  while true
    ' wait for an event from our poster screen
    msg = Wait(0, port)
    
    if type(msg) = "roPosterScreenEvent"
      if msg.isScreenClosed()
        exit while
      end if
    end if
  end while
  
  screen.Close()
end sub

If you side-load this channel and launch it from the Roku home screen using the standard remote control, you will see “No message received” displayed on the poster screen. In order to make use of our launch parameter, we need to launch the channel using ECP. You can do this from your PC using curl and replacing the x’s below with the local IP address of your Roku. Note that the command must be sent as an HTTP POST request and the launch parameters must be sent as URL parameters. It’s also important that the parameter values be properly encoded, otherwise the ECP call will fail and the channel will not launch.

curl -d "" "http://xxx.xxx.xxx.xxx:8060/launch/dev?message=Hello%20World%21"

If this command succeeds, your side-loaded channel will launch and “Hello World!” will be displayed on your poster screen. Try it with some other values for the message parameter.

Play a Video
Displaying a message is a simple way of demonstrating how launch parameters work, but it isn’t especially useful. Suppose we wanted to pass the URL of a piece of content into a channel and have the channel play that content. The first thing we would need is a simple channel that could accept a launch parameter whose value was a URL and use that URL to build a content-meta-data structure that could then be fed into a roVideoScreen. That might look something like this.

sub Main(launchParameters)
  ' don't do anything unless we got a url
  if launchParameters.url <> invalid
    ' setup a poster screen and assign it a message port
    port = CreateObject("roMessagePort")
    screen = CreateObject("roVideoScreen")
    screen.SetMessagePort(port)

    ' build a content-meta-data using the passed in URL   
    screen.SetContent({
      stream: { url: launchParameters.url }
    })

    ' play the video
    screen.Show()
    
    while true
      ' wait for an event from our video screen
      msg = Wait(0, port)
      
      if type(msg) = "roVideoScreenEvent"
        if msg.isScreenClosed()
          exit while
        end if
      end if
    end while
    
    screen.Close()
  end if
end sub

Once you side-load this channel, you can launch it using ECP the same way we did our first channel, but this time you would need to send it a parameter called url whose value is the URL to a compatible mp4 video. You could do that with a command similar to this. Again, notice that the launch parameter must be properly URL encoded for the command to succeed.

curl -d "" "http://xxx.xxx.xxx.xxx:8060/launch/dev?url=http%3A%2F%2Fvideo.ted.com%2Ftalks%2Fpodcast%2FDavidBrooks_2011.mp4"

If the command succeeds, your side-loaded channel will launch and begin playing the video referenced by the URL.

Using this simple channel as a starting point, you could add support for additional video and audio content by adding a second launch parameter to specify the type of content that the URL refers to. Or, instead of a single video, you could pass in the URL of an MRSS feed and display all the content contained in that feed.

And if you’re working with a content provider’s API, you can use launch parameters to pass in search terms or content identifiers, or other data that can be used in conjunction with that particular API to get the user to compelling content quickly.