======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 ?&&<...> to the end of the URL.
* duration= sets a duration limit for the http transfer. Once seconds has elasped the stream will be closed by the HDHomeRun.
* transcode= 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 1280x720 30fps.
* internet540: transcode to low bitrate AVC progressive not exceeding 960x540 30fps.
* internet480: transcode to low bitrate AVC progressive not exceeding 848x480 30fps for 16:9 content, not exceeding 640x480 30fps for 4:3 content.
* internet360: transcode to low bitrate AVC progressive not exceeding 640x360 30fps for 16:9 content, not exceeding 480x360 30fps for 4:3 content.
* internet240: transcode to low bitrate AVC progressive not exceeding 432x240 30fps for 16:9 content, not exceeding 320x240 30fps for 4:3 content.
====Examples====
For the URL "http://192.168.0.100:5004/auto/v5.1" \\
* http://192.168.0.100:5004/auto/v5.1?duration=120
* http://192.168.0.100:5004/auto/v5.1?transcode=mobile
* http://192.168.0.100:5004/auto/v5.1?transcode=mobile&duration=120
====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.
{{tag>development}}