HTTP API Documentation

Want to write your own code to work with a HDHomeRun or work with the HDHomeRun DVR? We are happy to help with concepts, APIs, best practices.
TPeterson
Posts: 130
Joined: Thu May 31, 2007 8:29 pm
Device ID: 10123716, 10157425, 1039FE2B, 103AEA6C, 1075D4B1, 1076C3A7, 1080F19F
Location: San Carlos, CA
x 2
Contact:

Re: HTTP API Documentation

Post by TPeterson »

As an oldtimer, I didn't recognize HDHomerun_config by its new name. That utility, of course, does provide (after a rather lengthy delay) a tuner-specific lineup. However, my hope is to avoid requiring that CW_EPG users with HTTP-capable HDHR units install the "Windows software" package and also to avoid those long scanning delays that are now unnecessary since the HDHR units perform background scans. This would be trivially easy if a variant of the lineup.xml call would supply a filtered list.

Ned, lineup.xml (when the "tuning" parameter is specified) already does show which channels are "atsc3" protocol. The rub is that my app will need to know which models and which tuners support same.

rpcameron
Posts: 1108
Joined: Fri Mar 25, 2016 9:55 am
x 4

Re: HTTP API Documentation

Post by rpcameron »

TPeterson wrote: Sat Feb 03, 2024 4:24 pm As an oldtimer, I didn't recognize HDHomerun_config by its new name. That utility, of course, does provide (after a rather lengthy delay) a tuner-specific lineup.
There is no new name. hdhomerun_config is simply the plain command line interface to libhdhomerun. libhdhomerun has always been built as the library the powered the application; when you build hdhomerun_config, it first builds libhdhomerun.

nickk
Silicondust
Posts: 20195
Joined: Tue Jan 13, 2004 9:39 am
x 384

Re: HTTP API Documentation

Post by nickk »

Tuners are dynamically allocated. Keep in mind that you don't know what tuners are available when you go to tune because another app on another device may be using one or more tuners.

lineup.json provides the list of channels the device supports including the URL for each channel. You pull lineup.json from every HDHomeRun device and combine them by virtual channel number so you end up with a list of URLs for each channel.

When you want to record you try the first URL for that virtual channel number. The HDHomeRun device will either start delivering the channel or report that all tuners are busy, in which case you move on to try the next URL.

You shouldn't care which tuner inside the HDHomeRun was dynamically allocated. The one exception is checking signal information - the HTTP response from the video request includes the tuner number so you cross reference with /status.json.

Which tuners support ATSC 3.0 doesn't matter. If all ATSC 3.0 tuners within a HDHomeRun device are busy the HDHomeRun will report all tuners in use. If the next tune request is an ATSC 1.0 channel you start trying URLs and the same HDHomeRun may have a tuner available and start delivering.

For software that expects to control each tuner individually you report to the software X number of virtual tuners where X is the total number of tuners across all HDHomeRun devices found on the network. That way it will be able to record X shows at once.

Keep in mind that you can't predict ahead of time which physical tuners will be available as there may be other software using some or all of the tuners.

libhdhomerun - typically the only thing you use libhdhomerun for these days is the discover API in hdhomerun_discover.h. Everything else is done using HTTP.

BTW - with our BDA drivers on Windows you see the Device ID + tuner index as the name but is is really a virtual tuner... when the actual request to tune a channel hits the BDA driver can use any tuner on any device.

nickk
Silicondust
Posts: 20195
Joined: Tue Jan 13, 2004 9:39 am
x 384

Re: HTTP API Documentation

Post by nickk »

Documentation for the discover2 API which is now the recommended API for discovering HDHomeRun devices:
https://www.silicondust.com/hdhomerun/h ... er_api.pdf

rpcameron
Posts: 1108
Joined: Fri Mar 25, 2016 9:55 am
x 4

Re: HTTP API Documentation

Post by rpcameron »

nickk wrote: Sat Feb 03, 2024 7:19 pm libhdhomerun - typically the only thing you use libhdhomerun for these days is the discover API in hdhomerun_discover.h. Everything else is done using HTTP.
I disagree with this characterization. If you use HDHR tuners with more than one application, or you need non–ClearQAM, or want to use ATSC 3.0, then yes, the HTTP API is your only real avenue.

But, if you are using a single application for your TV/DVR needs, and don't have any non–ClearQAM cable feeds, the UDP–based library is still an excellent option. (Also, if you have an older HDHR tuner that does not support the HTTP API—all 3rd generation and older devices except the Prime—then that is your only option; the Windows software + SiliconDust server for a pseudo–lineup won't work for everyone.) Plus, if you use the UDP API through libhdhomerun, you can use the full mux, enabling a single tuner to access more than one virtual channel.

nickk
Silicondust
Posts: 20195
Joined: Tue Jan 13, 2004 9:39 am
x 384

Re: HTTP API Documentation

Post by nickk »

rpcameron wrote: Sat Feb 03, 2024 9:17 pm But, if you are using a single application for your TV/DVR needs, and don't have any non–ClearQAM cable feeds, the UDP–based library is still an excellent option. (Also, if you have an older HDHR tuner that does not support the HTTP API—all 3rd generation and older devices except the Prime—then that is your only option; the Windows software + SiliconDust server for a pseudo–lineup won't work for everyone.) Plus, if you use the UDP API through libhdhomerun, you can use the full mux, enabling a single tuner to access more than one virtual channel.
You can tune by physical-channel + program-number or request full mux using HTTP.

ebo
Posts: 674
Joined: Thu Jan 07, 2010 6:58 pm
Device ID: 1016F746, 101C8CF9, 1041F134, 10532394
x 3

Re: HTTP API Documentation

Post by ebo »

nickk wrote: Sat Feb 03, 2024 7:19 pm Tuners are dynamically allocated. Keep in mind that you don't know what tuners are available when you go to tune because another app on another device may be using one or more tuners.
.
.
.
Keep in mind that you can't predict ahead of time which physical tuners will be available as there may be other software using some or all of the tuners.
That's what HDHomeRun Status Monitor is good for. It shows what tuners are in use (and what channels they're on) regardless of whether they're used by other programs or devices on the network.

TPeterson
Posts: 130
Joined: Thu May 31, 2007 8:29 pm
Device ID: 10123716, 10157425, 1039FE2B, 103AEA6C, 1075D4B1, 1076C3A7, 1080F19F
Location: San Carlos, CA
x 2
Contact:

Re: HTTP API Documentation

Post by TPeterson »

nickk wrote: Sat Feb 03, 2024 7:19 pm Tuners are dynamically allocated. Keep in mind that you don't know what tuners are available when you go to tune because another app on another device may be using one or more tuners....
libhdhomerun - typically the only thing you use libhdhomerun for these days is the discover API in hdhomerun_discover.h. Everything else is done using HTTP....
Nick, thanks for the detailed description of your tuner-selection rationale. We recently enhanced CW_EPG to recognize that it may not be the only HDHR-using app on the LAN and have it fall back to another tuner whenever a target is locked. It does follow a routine in that case that is similar to the one you describe, but I was hoping to make this more efficient by making sure that ATSC 1.0 tuners would not be attempted for ATSC 3.0 signals and realized that having a tuner-specific lineup.xml would be a quick solution to that if it existed. (I also realized that Silicondust has more urgent fish frying lately)

CW_EPG also stopped requiring hdhomerun_config.exe a while ago, as long as there are no pre-HTTP HDHR units in the mix.

Post Reply