API 20141201: update to "map" section for lineup

Post Reply
rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

API 20141201: update to "map" section for lineup

Post by rkulagow » Mon Aug 31, 2015 12:44 pm

Based on numerous issues that have been raised from developers, the "map" response for a lineup will switch to a more standardized format.

The map still maintains the "stationID" and "channel" parameters, so no changes there, however, based on submitted scans from subscribers it doesn't make sense to have DVB-C, -S and -T have one kind of map, with U.S. set-top-box satellite having a 3rd, FTA having a 4th, QAM being something else, etc. That leads to multiple code paths on the server side as well as on the client side.

With the proposed change, the following fields will be available in the map section.

Mandatory:
stationID
channel

Optional:
frequencyHz
polarization
deliverySystem (DVB-C, -S, -T, ATSC)
modulationSystem (QPSK, QAM64, QAM256, 8VSB)
symbolrate
fec
vpid
apid_a
apid_d
teletextID
conditionalAccess
serviceID
networkID
transportID
radioID
providerChannel
providerCallsign
logicalChannelNumber
channelMajor (typically for ATSC digital channels)
channelMinor
matchType ("pChannel", "pCallsign", "lcn")

Your code does not need to use any of the optional fields, but if your user's scan finds "BBC ONE Scot", then your code can now correlate that it's on stationID 21439, even though the Schedules Direct name is "BBC One (Scotland)"

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20141201: update to "map" section for lineup

Post by rkulagow » Tue Sep 01, 2015 12:51 pm

Here's what GBR-0001219-DEFAULT (Freeview in the UK) would look like with the new scheme; it's from a HDHomerun lineup.json, so in this case we only know the providerCallsign and the logicalChannelNumber

Code: Select all

[
    {
        "stationID": "21439",
        "channel": "001",
        "providerCallsign": "BBC ONE Scot",
        "logicalChannelNumber": "1",
        "matchType": "pCallsign"
    },
    {
        "stationID": "29049",
        "channel": "002",
        "providerCallsign": "BBC TWO Scot",
        "logicalChannelNumber": "2",
        "matchType": "pCallsign"
    },
    {
        "stationID": "21833",
        "channel": "003",
        "providerCallsign": "STV",
        "logicalChannelNumber": "3",
        "matchType": "pCallsign"
    },
    {
        "stationID": "17155",
        "channel": "004",
        "providerCallsign": "Channel 4",
        "logicalChannelNumber": "4",
        "matchType": "pCallsign"
    },
    {
        "stationID": "17157",
        "channel": "005",
        "providerCallsign": "Channel 5",
        "logicalChannelNumber": "5",
        "matchType": "pCallsign"
    }
]
(etc)
I'm still in the process of integrating the other scan types but won't do a whole lot on that until I know which direction developers prefer: back-port the feature into API-20141201, or push it to API-NEXT

glugglug
Posts: 16
Joined: Wed Oct 14, 2015 8:52 pm

Re: API 20141201: update to "map" section for lineup

Post by glugglug » Thu Oct 22, 2015 7:44 pm

I guess this is not done across all lineup types yet, as when testing whether I can parse every type I can find, I found that my local OTA lineup does not have the "mandatory" channel field populated, but does have the uhfvhf/atscMajor/atscMinor not on this list (and I don't think the analog uhfvhf versions of the channels still exist? Or is that the physical major channel with atscMajor-atscMinor being what it maps to as a virtual channel?)

A few other questions:


[*]Can we get a brief description of what to expect in each of these fields (should the strings be #-#, #.#, or just generic strings, etc).?
[*] Which lineup types use which subset of the fields?
[*]QAM should always be major#-minor#, just like ATSC. But it is using a string providerChannel field instead of the channelMajor/channelMinor which the earlier post says are typically for ATSC digital channels. I think it makes sense to reuse the channelMajor/channelMinor fields here unless the QAM and OTA tuning info is sometimes specified together in the same channel instance.
[*]Is there a canonical list of fields to use for tuning vs. guide channel numbers?
[*] Maybe the new canonical field list should be in addition to existing fields kept awhile for backward compatibility?

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20141201: update to "map" section for lineup

Post by rkulagow » Tue Nov 03, 2015 8:32 am

Ah, my old nemesis, backwards compatibility.

I will update the documentation. "channel" was initially strictly a field for set top boxes, because that's how things started out when this was a v0.0001 project.

An Analog transmitter (there are still analog transmitters in the United States and Canada) will have a uhfVhf, but not an ATSC major/minor.

As far as which lineups use which subsets, it's a mixture depending on what scan source we received to generate the map. A map which comes directly from our upstream won't have any of the NID/TID/SID information, frequencies, polarization, etc, because they don't provide it.

But, if we get a scan from someone with a HDHR using the built-in lineup.json URL, it's going to be sparse, and all we'll be able to provide is something like the providerCallsign as a matchType option. (But it will have the stationID, which is the key to everything)

If the scan comes from some other hardware, then there may be a lot more information which is then used to provide hints to a grabber when they run a hardware scan to make automapping possible. The more examples I can get of what various applications generate after a hardware scan, the better I can make the backend.

Since I no longer have access to QAM, much of the digital tuning had to be developed without me being able to directly experience things. If you check the threads here in the developer forum you'll see that I've been asking developers what they'd like / what makes things easiest.

If you have some examples of what a digital scan looks like in your application then I can see about adding it; if there are too many changes necessary in the current API that would break other things then I can possibly include it as a sub-container in the map; any applications that don't know about it will just ignore the field.

Post Reply