Idle thoughts on mapping Receiver Capabilities to Query API RQL

[garethsb]

For example:

Receiver Caps

Query API - RQL

{ ... "transport": "urn:x-nmos:transport:rtp", "format": "urn:x-nmos:format:video", "caps": { "media_types": [ "video/raw" ], "version": "1603796863:314159275", "constraint_sets": [ { "urn:x-nmos:cap:meta:label": "1080i", "urn:x-nmos:cap:format:color_sampling": { "enum": [ "YCbCr-4:2:2" ] }, "urn:x-nmos:cap:format:frame_height": { "enum": [ 1080 ] }, "urn:x-nmos:cap:format:frame_width": { "enum": [ 1920 ] }, "urn:x-nmos:cap:format:grain_rate": { "enum": [ { "numerator": 25 }, { "numerator": 30000, "denominator": 1001 } ] }, "urn:x-nmos:cap:format:interlace_mode": { "enum": [ "interlaced_tff", "interlaced_bff", "interlaced_psf" ] } }, { "urn:x-nmos:cap:meta:label": "1080p", "urn:x-nmos:cap:format:color_sampling": { "enum": [ "YCbCr-4:2:2" ] }, "urn:x-nmos:cap:format:frame_height": { "enum": [ 1080 ] }, "urn:x-nmos:cap:format:frame_width": { "enum": [ 1920 ] }, "urn:x-nmos:cap:format:grain_rate": { "enum": [ { "numerator": 25 }, { "numerator": 30000, "denominator": 1001 }, { "numerator": 50 }, { "numerator": 60000, "denominator": 1001 } ] }, "urn:x-nmos:cap:format:interlace_mode": { "enum": [ "progressive" ] } } ] } }

/x-nmos/query/v1.3/flows/?query.rql=and( eq(format,urn%3ax-nmos%3aformat%3avideo), in(media_type,(video%2fraw)), or( and( eq(components,sampling:YCbCr-4%3a2%3a2), eq(frame_height,1080), eq(frame_width,1920), in(grain_rate,( rational:25%2f1, rational:30000%2f1001 )), in(interlace_mode,( interlaced_tff, interlaced_bff, interlaced_psf )) ), and( eq(components,sampling:YCbCr-4%3a2%3a2), eq(frame_height,1080), eq(frame_width,1920), in(grain_rate,( rational:25%2f1, rational:30000%2f1001, rational:50%2f1, rational:60000%2f1001 )), eq(interlace_mode,progressive) ) ) )

I've taken the liberty of mapping some enum constraints with a single value to eq, while leaving some using in. They're equivalent, the former is a slight optimization, that's all.

[garethsb]

Receiver Caps	Query API - RQL
... "urn:x-nmos:cap:format:sample_depth": { "minimum": 8, "maximum": 24 }, ...	... ge(bit_depth,8), le(bit_depth,24), ...

[garethsb]

With the RQL operator rel, we can make queries on Senders like:

/x-nmos/query/v1.3/senders/?query.rql=and(
  in(transport,(
    urn%3ax-nmos%3atransport%3artp.mcast,
    urn%3ax-nmos%3atransport%3artp.ucast
  )),
  rel(flow_id,
    and(
      eq(format,urn%3ax-nmos%3aformat%3avideo),
      ...more filters on the associated Flow, as above...
    )
  )
)

[garethsb]

A more complete example query on audio Senders (and their linked Flows and Sources):

Receiver Caps	Query API - RQL
{ "transport": "urn:x-nmos:transport:rtp.mcast", "format": "urn:x-nmos:format:audio", "caps": { "media_types": [ "audio/L24" ], "version": "1603796863:314159275", "constraint_sets": [ { "urn:x-nmos:cap:format:sample_depth": { "minimum": 8, "maximum": 24 }, "urn:x-nmos:cap:format:channel_count": { "enum": [2,4,8] } } ] }, ... }	/x-nmos/query/v1.3/senders/?query.rql=and( eq(transport,urn%3ax-nmos%3atransport%3artp.mcast), rel(flow_id, and( eq(format,urn%3ax-nmos%3aformat%3aaudio), eq(media_type,audio%2fL24), ge(bit_depth,8), le(bit_depth,24), rel(source_id, in(count(channels),(2,4,8)) ) ) ) )

Similarly here, I've taken the liberty of mapping the parameter constraints of a single constraint set into the top-level and rather than including the or for constraint_sets and an and for each constraint set. Again, it's just a trivial optimization.

[garethsb]

Dealing with target parameters that have default values requires a little work, but using null to detect omitted properties and rel it's possible even for 'grain_rate'.

Receiver Caps	Query API - RQL
... "urn:x-nmos:cap:format:transfer_characteristic": { "enum": [ "SDR", "ST2115LOGS3" ] }, ...	... in(transfer_characteristic,(SDR,null,ST2115LOGS3), ...
... "urn:x-nmos:cap:format:grain_rate": { "enum": [ { "numerator": 25, "denominator": 1 } ] }, ...	... or( eq(grain_rate,rational:25%2f1), and( eq(grain_rate,null), rel(source_id, eq(grain_rate,rational:25%2f1) ) ) ) ...

[peterbrightwell]

Thanks @garethsb perhaps this info would be suitable for a future BCP on use of RQL in NMOS?

See also AMWA-TV/is-04#158 (search for 'RQL' as it's a huge conversation)

[garethsb]

Yes, precisely. 👍