HTTP API Documentation

[matthew.muscat]

Hi there,

I am currently looking at implementing a web-based client for HD HomeRun devices and seeking details of the HTTP APIs available from HDHomerun devices..

Taking a look online, I've already located some official docs, however this appears to only mention channel lists + streaming options

- https://info.hdhomerun.com/info/http_api (only appears to mentioned channel lists + streaming endpoints)
- http://www.silicondust.com/hdhomerun/hd ... opment.pdf (is this documentation current? — published in 2014)

Is there a more comprehensive list of the available HTTP endpoints and their expected request/response structures?

I'm seeking details on the following behaviors...

1. Device Discovery
2. Channel Scanning
3. Device / Tuner Status
4. Channel Streaming
5. Session / tuner handling

At the moment I've been looking at how third-party client / emulator implementations consume the API to determine the available endpoints and their expected behaviors, but this approach seems cumbersome and is likely not covering all use cases such as device types, their capabilities and their regional environment.

- Emby LiveTV Client
- Kodi Addon for HD Homerun Client
- Emulator of the HD Homerun API for TV Headend

Is there a resource i can refer to for the official device apis that are currently supported?

[signcarver]

Your first link is the official one. Things not covered in that aren't published/documented. Though you can discover through http, that is based on essentially going to api.hdhomerun.com/discover looking where that redirects to and then also change ipv4- to ipv6- as most wll connect to SD through ipv6. It has been previously stated that such discovery may cease next year but not sure if they changed those plans. The proper way for discovery is broadcast discovery which sends a special udp packet to the broadcast address port 65001 (i.e. 255.255.255.255:65001) you can look at libhdhomerun to see how to craft the packet or just capture the payload part of it via Wireshark rather than building it and use that. I typically have a webserver do this with php or execute a script to do such.

There are different types of channel scans... most building an app would again probably use libhdhomerun/hdhomerun_config but that doesn't typically have the device maintain lineup just displays the scan results which does little good for http api. My suggestion is to open the device's lineup page and check the code/request when you click the detect channels button (you may wish some developer tools i.e. f12 in many browsers) . Status would be status.json

Http streaming would use the playurl from the lineup.json.. not sure what you mean by session/tuner handling when it comes to http api and/or if using the dvr to stream (as there are a couple of other things for using dvr to stream live). Http method of tuning auto locks, actual tuner used can be specified but it is usually best to use auto (as given in url) but you can use tunerX where X is tuner number (0- 1 less than number of tuners)

[matthew.muscat]

There are different types of channel scans... most building an app would again probably use libhdhomerun/hdhomerun_config but that doesn't typically have the device maintain lineup just displays the scan results which does little good for http api.

Ideally, i would want to support all capabilities of the hdhomerun devices from the client, as this would be a web-based client, the HTTP api would be what we are consuming here — my understanding is that libhdhomerun seems to implement a custom protocol, rather than consuming the HTTP apis

I see some clients reference a /lineup.post endpoint, however there's no mention of this in any official documentation

Reverse engineering the potentially available apis with a local device is one approach possible at the moment, but you miss out on the nuances between different models, regions and source types (DVB-T / Cable) that may influence the API payload response structures — i was hoping there was at least some further information on this beyond the document dated in 2014

Right now, i'm only able to infer this information for other client implementations and non-official notes people have taken...
- Documentation of some endpoints
- Home Assistant Integration

Is there hesitation to have these apis publicly documented? or is this just a case where no one had really asked for it?

[TPeterson]

The pages lineup.xml and lineup.json were OK as long as all tuners in the device were the same. But now, with some tuners in the device not able to lock on all of the channels shown, it would be very nice to have a modified call to show the lineup for only one of the tuners. Is there such a call already?

[nickk]

The pages lineup.xml and lineup.json were OK as long as all tuners in the device were the same. But now, with some tuners in the device not able to lock on all of the channels shown, it would be very nice to have a modified call to show the lineup for only one of the tuners. Is there such a call already?

All HDHomeRun tuner models that support lineup.xml/json are single input (all tuners receive the same signal).

[signcarver]

Typically, unless something like an atsc3 vs atsc1 issue, which would be known by channel number (atsc3 on hdhomerun adds 100) , that would most often mean your power supply is beginning to show its age as such wouldn't be normal without some hardware failure and power supply should be first thing to suspect.the device only has the one lineup and to do it quickly uses all tuners to produce such.

Typically for what you ask, one would use the libraries which are more meant on a per tuner basis.

[TPeterson]

All HDHomeRun tuner models that support lineup.xml/json are single input (all tuners receive the same signal).

True, but the 4k units show atsc3 channels in those lists that tuners 2 and 3 cannot lock. That's the reason for my wish to have tuner-specific lists.

[TPeterson]

Typically for what you ask, one would use the libraries which are more meant on a per tuner basis.

"The libraries" == ??

[signcarver]

For thar issie, as I mentioned, those would be channels above 100. (Edit: I should mention not counting the 5000 channels which to my knowledge shouldn't be an atsc3 channel)

libhdhomerun not http api.

[TPeterson]

"libhdhomerun" url?

[TPeterson]

Of course one can parse the list, which also includes the modulation type of each channel, and use external knowledge of the model and its tuner complement to decide which channels to assign each. But why force each user to that effort when the fw could issue a correct tuner-specific list instead?

[nickk]

Normal operation is send a request where the URL includes the channel number. The HDHomeRun chooses the tuner.

[TPeterson]

Nick, this is the Developer Support forum.... My use case is not selecting a single channel but constructing resources for CW_EPG to use when recording from HDHomerun units.

[rpcameron]

"libhdhomerun"

url?

https://github.com/Silicondust/libhdhomerun

[removed by moderator]

[NedS]

What if lineup.xml and lineup.json showed which channels were ATSC 3.0 (it's technically possible for ATSC 1.0 to be in the 100+ range, but I can't imagine anyone would actually choose a virtual number that high)? From that information you could figure out what channels to exclude for the ATSC 1.0 tuners.