Table of Contents

HDHomeRun HTTP Development Guide

Channel List

The list of available channels can be queried using the following URLs: 

   http://hdhomerun.local/lineup.json
   http://hdhomerun.local/lineup.xml
   http://hdhomerun.local/lineup.m3u


Note: “hdhomerun.local” can also be replaced by the deviceID.local or the IP address of the HDHomeRun.

The following information is returned for each program:

  • “GuideNumber” (virtual channel number). For ATSC the number will be “n.n” format. For all other systems the number will be “n” format.
  • “GuideName” in UTF-8 format. Client must support UTF-8 character encoding.
  • “Tags” in comma-separated-value format. The following tags are supported:
    • “favorite” indicates the user has marked this channel as a favorite channel.
    • “drm” indicates this channel requires the use of end-to-end copy protection.
  • “URL” for sourcing the video for this channel.

Streaming Video

The HTTP request will result in the following sequence:

  • A tuner will be allocated for this HTTP operation.
  • The channel will be authorized and tuned.
  • The PID filter will be set automatically.
  • The video stream will be streamed in MPEG-TS format over the HTTP connection.

The stream will continue until the TCP connection is closed by the client or the specified duration is reached, at which point the tuner will become available for other client requests.

Optional Parameters

Optional parameters may be specified by adding ?<paramater>&<paramater>&<…> to the end of the URL.

  • duration=<n> sets a duration limit for the http transfer. Once <n> seconds has elasped the stream will be closed by the HDHomeRun.
  • transcode=<profile> enables transocding of the video/audio following the specified profile. (EXTEND models only)

Transcode Profiles

(EXTEND models only)

  • heavy: transcode to AVC with the same resolution, frame-rate, and interlacing as the original stream. For example 1080i60 → AVC 1080i60, 720p60 → AVC 720p60.
  • mobile: trancode to AVC progressive not exceeding 1280×720 30fps.
  • internet540: transcode to low bitrate AVC progressive not exceeding 960×540 30fps.
  • internet480: transcode to low bitrate AVC progressive not exceeding 848×480 30fps for 16:9 content, not exceeding 640×480 30fps for 4:3 content.
  • internet360: transcode to low bitrate AVC progressive not exceeding 640×360 30fps for 16:9 content, not exceeding 480×360 30fps for 4:3 content.
  • internet240: transcode to low bitrate AVC progressive not exceeding 432×240 30fps for 16:9 content, not exceeding 320×240 30fps for 4:3 content.

Examples

For the URL “http://192.168.0.100:5004/auto/v5.1”

Channel frequency instead of vchannel

URLs can also use the channel frequency instead of the virtual channel. Use “ch” instead of “v”, and the RF channel number or frequency in Hz instead of the virtual channel number.

  • Example channel 5 is RF 14, which is 473MHz and would be written as 
    http://192.168.0.100:5004/auto/ch473000000
  • If the channel has sub-channels, you can use the program number to specify the channel with a dash. For example, channel 5.3 might be -3 (program numbers are not always sequential or starting with 1), it would be written as, 
    http://192.168.0.100:5004/auto/ch473000000-3

Specifying a tuner

The “/auto/” portion of the URL will select the first available tuner. Replacing this with a tuner identifier will force use of a specific tuner. For example:

  • tuner0 - the first tuner
  • tuner1 - the second tuner
  • tuner2 - the third tuner (if you have a 3 or 4 tuner model)
  • tuner3 - the fourth tuner (if you have a 4 tuner model)

The URL for using the second tuner might look like this: 

http://192.168.0.100:5004/tuner1/v5.1

Errors

If the virtual channel number is not known the tuner will return “404 Not Found”.

If the request cannot be completed at this time (for example all tuners are in use) the tuner will return “503 Service Unavailable”.

If the program cannot be not found in the stream within 5 seconds or the program cannot be authorized within 5 seconds the tuner will return “503 Service Unavailable”.

If the program requires content-protection not requested by the client the tuner will return “503 Service Unavailable” after 5 seconds. This error code may change in the future to return a more relevant error code.

There's an X-HDHomeRun-Error header that will be returned with more specific reasons. The parts in parentheses are not included in the error, just an explanation of what the error is.

801 Unknown Channel
802 Unknown Transcode Profile (EXTEND only)
803 System Busy (normally means the device is in the middle of a channel scan)
804 Tuner In Use (when a specific tuner is used instead of auto)
805 All Tuners In Use
806 Tune Failed (TA reported an error (PRIME only), or hardware error)
807 No Video Data (bad reception/station off air/particular service is not being transmitted at that time)
808 DVR Failure (DVR can't write to the recording location)
809 Playback Connection Limit (DVR has hit the limit of playback streams)
810 DVR Full
811 Content Protection Required (PRIME only, channel is copy protected)

Client requirements for live TV

The stream is delivered to the client in real time as it arrives from the broadcast source.

  • The client will have a slightly different concept of how long one second is due to slight differences in the client clock timebase vs the broadcaster clock timebase. The client must adjust its concept of real time to match the incoming video stream. For example, if the client is displaying frames slightly faster than the incoming stream rate it will slowly empty the input jitter buffer. Alternatively if the client is displaying frames slightly slower than the incoming stream rate it will slowly fill up and overflow the input jitter buffer. For live TV the client must adjust its concept of real time by increasing or decreasing the frame rate slightly to match the rate at which data is arriving.
  • The initial buffering of data by the client must be based on time, not size. The stream is sent in real time which means the amount of data received in one second will be lower on SD channels vs HD channels.
  • There may be a delay between the HTTP request and data being returned. The initial buffering of data by the client must be based on time, starting from the first data arriving.
  • The client input jitter buffer max-size must be larger than the worst case amount of data that can be sent in the initial buffering time. This allows for 1) detecting if the client is running slower than the stream rate (see above), and 2) if the client takes time to set up the video rendering components after detecting the stream content it must continue to buffer (not drop data) during this setup time.