Vooraf ingestelde afstandsbediening API

Als je een aangepaste laag maakt, is er zelfs de mogelijkheid om aangepaste besturingspresets bij je laag te voegen. Dit is handig als je laag drukknoppen heeft die het gedrag van je laag regelen als deze live is.

Gegevensstructuur

De volgende datastructuur is een voorbeelduitvoer die aanwezig moet zijn in je compositie onder de `tvOut_ControlRepresentations` structuuruitvoersleutel:

{
  "tvOut_ControlRepresentations": [
    {
      "title": "Compact Cut's",
      "buttons": [
        {
          "actions": [
            {
              "layerId": "03627C25-CC8A-474F-A738-C4DEB3353FA4",
              "variantId": "F6F52194-06DE-462E-983A-8D505C533A69",
              "type": "signal",
              "signalKey": "tvGroup_Control__Cut_1_TypeSignal",
              "signalName": "Cut 1"
            }
          ],
          "liveState": {
            "layerId": "03627C25-CC8A-474F-A738-C4DEB3353FA4",
            "variantId": "F6F52194-06DE-462E-983A-8D505C533A69",
            "dynamicSourceId": "tvIn_VideoSourceAImage"
          },
          "sourcePreview": {
            "layerId": "03627C25-CC8A-474F-A738-C4DEB3353FA4",
            "variantId": "F6F52194-06DE-462E-983A-8D505C533A69",
            "dynamicSourceId": "tvIn_VideoSourceAImage"
          },
          "color": "#BBBBBB",
          "width": 1,
          "height": 1,
          "x": 0,
          "y": 0,
          "icon": "facetime-video",
          "dynamicText": {
            "template": "{{inputputValues.tvIn_VideoSourceAName}}",
            "layerId": "03627C25-CC8A-474F-A738-C4DEB3353FA4",
            "variantId": "F6F52194-06DE-462E-983A-8D505C533A69"
          }
        }
      ]
    }
  ]
}

Een preset heeft een "titel" en een array van "knoppen", maar een enkele knop is ook goed.

*

De sleutels `layerId` en `variantId` moeten dynamisch worden ingevuld met de stringgegevens van de compositie-invoersleutels `tvIn_LayerIdentifier` en `tvIn_RuntimeIdentifier`.

De voorkeurszender van de afstandsbediening gebruiken API in Kwartscomposer

De ingebouwde lagen van mimoLive gebruiken een LUA script om deze datastructuur dynamisch te genereren, omdat Quartz Composer het genereren van datastructuren niet zelf ondersteunt. De LUA Het script bevat een complexe functie addButton() die kan worden gebruikt om de structuur voor een enkele knop te maken. Meestal kun je deze functie gewoon gebruiken en hoef je hem niet aan te passen. Daarom is het vrij eenvoudig om nieuwe standaardinstellingen voor afstandsbedieningen te maken voor je eigen laag.

Dit is bijvoorbeeld de LUA script om de afstandsbedieningen voor de Stop Watch-laag te genereren. Merk op dat je deze code kunt overnemen door alleen de regels 15 tot en met 29 van de code te wijzigen.

inLayerIdentifier = QC_STRING
inVariantIdentifier = QC_STRING
outControlRepresentations = QC_STRUCT
main = function()
  controlRepresentations = {}
  -- first representation
  controlRepresenation = {}
  -- {
    controlRepresenation["Title"] = "Stop Watch"
    buttons = {}
    -- {
      -- addButton(buttonsTable, buttonTitle, subTitle, positionX, positionY, width, height, color, icon, actionTarget, liveStateSource, previewSource)
      -- first row
      addButton(buttons, "{{outputValues.tvOut_TimeString}}", "", 0, 0, 2, 1, "#333333", "", "", "", "")
      addButton(buttons, "Live", "{\{name\}}", 2, 0, 1, 1, "#333333", "", "toggleLive", "layerVariant", "")
      -- second row
      addButton(buttons, "Start", "", 0, 1, 1, 1, "#33cc33", "play", "tvGroup_Control__Start_TypeSignal", "", "")
      addButton(buttons, "Stop", "", 1, 1, 1, 1, "#cc3333", "pause", "tvGroup_Control__Stop_TypeSignal", "", "")
      addButton(buttons, "Reset", "", 2, 1, 1, 1, "#cccc33", "stop", "tvGroup_Control__Reset_TypeSignal", "", "")
    -- }
    controlRepresenation["buttons"] = buttons
  -- }
  table.insert(controlRepresentations , controlRepresenation)
  outControlRepresentations = controlRepresentations
end
function addButton(buttonsTable, buttonTitle, buttonSubTitle, positionX, positionY, width, height, color, icon, actionTarget, liveStateSource, previewSource)
  local button = {}
  -- {
  if #buttonTitle > 0 then
    if string.find(buttonTitle, "{{") then
      -- dynamic titel
      local dynamicText = {}
      -- {
        dynamicText["layerId"] = inLayerIdentifier
        dynamicText["variantId"] = inVariantIdentifier
        dynamicText["template"] = buttonTitle
      -- }
      button["dynamicText"] = dynamicText
    else
      -- static title
      button["text"] = buttonTitle
    end -- if dynamic
  end -- if buttonTitle
  if #buttonSubTitle > 0 then
    if string.find(buttonSubTitle, "{{") then
      -- dynamic titel
      local dynamicSubText = {}
      -- {
        dynamicSubText["layerId"] = inLayerIdentifier
        dynamicSubText["variantId"] = inVariantIdentifier
        dynamicSubText["template"] = buttonSubTitle
      -- }
      button["dynamicSubText"] = dynamicSubText
    else
      -- static title
      button["subtext"] = buttonSubTitle
    end -- if dynamic
  end -- if buttonSubTitle
  button["x"] = positionX
  button["y"] = positionY
  button["width"] = width
  button["height"] = height
  if #color > 0 then
    button["color"] = color
  end -- if
  if #actionTarget > 0 then
    local actions = {}
    -- {
      local action = {}
      -- {
        action["layerId"] = inLayerIdentifier
        action["variantId"] = inVariantIdentifier
        if string.ends(actionTarget, "_TypeSignal") then
          action["type"] = "signal"
          action["signalKey"] = actionTarget
          action["signalName"] = buttonTitle
        elseif actionTarget == "toggleLive" then
          action["type"] = "toggleLive"
        else
          action["type"] = "toggleSwitch"
          action["toggleSwitchKey"] = actionTarget
          action["toggleSwitchName"] = buttonTitle
        end -- if
      -- }
      table.insert(actions , action)
    -- }
    button["actions"] = actions
  end -- if actionTarget
  if #liveStateSource > 0 then
    local liveState = {}
    -- {
      liveState["layerId"] = inLayerIdentifier
      liveState["variantId"] = inVariantIdentifier
      if string.starts(liveStateSource,"tvIn_VideoSource") then
        -- get the live state from a dynamic video source
        liveState["dynamicSourceId"] = liveStateSource
      elseif liveStateSource == "layerVariant" then
        -- nor more information needed
      else
        liveState["propertyPath"] = liveStateSource            end -- if
    -- }
    button["liveState"] = liveState
  end -- if liveState Source
  if #previewSource > 0 then
    local sourcePreview = {}
    -- {
      sourcePreview["layerId"] = inLayerIdentifier
      sourcePreview["variantId"] = inVariantIdentifier
      sourcePreview["dynamicSourceId"] = previewSource
    -- }
    button["sourcePreview"] = sourcePreview
  end -- if
  if #icon > 0 then
    -- See bottom of documentation page for list of avaiable icon names
    button["icon"] = icon
  end -- if
  -- }
  table.insert(buttonsTable, button)
end -- func
function string.starts(String,Start)
   return string.sub(String,1,string.len(Start))==Start
end
function string.ends(String,End)
   return End=='' or string.sub(String,-string.len(End))==End
end

Button Positionering

Als je meerdere knoppen gebruikt, moet je de lay-out van de knoppen handmatig regelen. Dat betekent dat knoppen op het raster worden gepositioneerd met behulp van "x"- en "y"-attributen, die net als de attributen "breedte" en "hoogte" worden opgegeven in veelvouden van rastercellen. Posities zijn relatief ten opzichte van de rastercel linksboven waar de knoppengroep naartoe werd gesleept.

Button Acties

Buttons kunnen meerdere acties hebben, één enkele actie, of helemaal geen. Er zijn verschillende geldige combinaties van actiedoelen en actietypen.
Let op dat "tekstInvoer" en "numeriekeInvoer" acties op zichzelf moeten staan, omdat een consistente gebruikerservaring in de afstandsbediening niet gegarandeerd is.

Actiedoelen

Actiedoelen zijn elementen in het mimoLive-document. Ze worden hiërarchisch geadresseerd:

De "document-ID" wordt altijd tijdens runtime getekend, dus deze hoeft niet aanwezig te zijn in de preset.

• Als noch "layerId" noch "variantId" zijn gegeven, wordt de actie geactiveerd op het document zelf.
• Als "layerId" is opgegeven, wordt de actie geactiveerd op de opgegeven laag.
• Als "layerId" en "variantId" zijn gegeven, wordt de actie geactiveerd op de gespecificeerde variant. Alleen in dit geval kunnen de extra "toggleSwitchKey" of "signalKey" worden opgegeven (zie Actietypes hieronder).

Soorten acties

Soort actie	Uitleg	Extra eigenschappen	Geldige doelen
toggleLive	Schakelen tussen live-status	geen	Document (Start/Stop show), Laag, Variant
actief	Live-status instellen op "live"	geen	Document (Startscherm), Laag, Variant
UIT	Stel live-status in op "uit".	geen	Document (Stop tonen), Laag, Variant
signaal	Een signaal triggeren	signalKey, signalName (aanbevolen)	Variant
toggleSwitch	Een booleaanse invoerwaarde schakelen	toggleSwitchKey, toggleSwitchName (aanbevolen)	Variant
tekstinvoer	Opent een tekstinvoerveld dat bij verzenden de waarde bij inputKey bijwerkt.	inputKey, inputName (aanbevolen)	Laag, Variant, Bron
numerieke invoer	Schuifregelaar die een numerieke waarde op inputKey controleert.	inputKey, inputDescription (object met zowel min- als max-waarden), inputName (aanbevolen)	Laag, Variant, Bron

*

"textInput" en "numericInput" actietypes zijn beschikbaar sinds mimoLive 5.2.

Button Levende staat

Het object "liveState" kan worden gebruikt om de status van het statuslampje van de knop te configureren, die aan (rode markering), overgang (gele markering) of uit (geen markering) kan zijn.

Live staatsbronnen

Net als bij knopactiedoelen kan de live-status worden verkregen uit meerdere bronnen:

• De "document-ID" wordt altijd tijdens runtime getekend, dus deze hoeft niet aanwezig te zijn in de preset.
• Als noch "layerId" noch "variantId" zijn gegeven, wordt de live-status van het document gebruikt (show is gestart of niet).
• Als "layerId" is opgegeven, wordt de live-status van de laag gebruikt.
• Als "layerId" en "variantId" zijn gegeven, wordt de live-status van de variant gebruikt.
  - Alleen in dit geval kan de extra "propertyPath" worden opgegeven om aan te geven dat een booleaanse eigenschap op de invoer- of uitvoerwaarden van de variant moet worden gebruikt.
  - Een andere mogelijkheid (wederzijds exclusief met propertyPath!) is het specificeren van een "dynamicSourceId" eigenschap die de live-status lookup omleidt naar een bron (opgehaald door ID), die dynamische veranderingen van de geselecteerde bron respecteert (bijv. in de videoswitcher). De waarde van "dynamicSourceId" wordt opgezocht in de invoerwaarden van de variant.

Geef het volledige pad naar de eigenschap, beginnend bij de variant als root, bijvoorbeeld "inputValues.some_Boolean_Property" of "outputValues.other_Property".

• Als "sourceId" is gegeven, wordt de live-status van de bron gebruikt.

Button Tekst

Actieknoppen kunnen primaire en secundaire tekstregels weergeven, beide kunnen statisch of dynamisch van aard zijn.

Primaire tekst

Deze tekst is de primaire indicator van wat de knop doet voor de gebruiker. Als de vooraf ingestelde knop een tekst-eigenschap bevat, is dit een statische tekst die wordt weergegeven zoals hij is.

Als alternatief kan een dynamicText worden gegeven die het mogelijk maakt om mimoLive laag- of varianteigenschappen op te nemen met behulp van een eenvoudige sjabloneringssyntaxis. In de sjabloonstring kunnen reguliere tekens worden gecombineerd met eigenschappenpaden tussen accolades:

"template": "{\{propertyPath\}}"

Eigenschapspaden worden geëvalueerd relatief ten opzichte van het object dat wordt opgelost met behulp van "layerId", "variantId", "sourceId" en "filterId". Doelomzetting volgt deze regels:

• De "document-ID" wordt altijd tijdens runtime getekend, dus deze hoeft niet aanwezig te zijn in de preset.
• Als "layerId" of "variantId" niet zijn gegeven, worden de paden van de eigenschappen relatief ten opzichte van het document geëvalueerd.
• Als "layerId" (en optioneel "variantId") is gegeven, worden de eigenschapspaden relatief ten opzichte van een laag/variant geëvalueerd.
• De bovenliggende laag van een variant is toegankelijk door een pad te beginnen met "layer", zoals "aslayer.name".

*

Het eerste padsegment van invoer- en uitvoerwaarden moet camelCased zijn ("inputValues.tvIn...") en niet kebab-cased ("input-values.tvIn...") zoals in de API-documenten.

• Statische tekst heeft altijd voorrang op dynamische tekst, omdat gebruikers dan de dynamische tekst kunnen overschrijven met een aangepaste tekst die misschien nuttiger is in hun situatie.

Secundaire tekst

Om de gebruiker meer informatie te geven over een knop, zoals de naam van de bovenliggende laag, kan een secundaire tekst worden gegeven met de eigenschappen "subtext" of "dynamicSubText".

De syntaxis van templating en objectresolutie volgen exact dezelfde regels als de primaire tekst.

Button Grootte van tekst en pictogrammen

De tekst en pictogrammen op knoppen kunnen in grootte variëren op basis van de context. Met de optie "fontScale" kun je een relatieve schaal opgeven ten opzichte van een standaardgrootte die is berekend voor de huidige schermgrootte. "1" is de standaardgrootte. Minder dan 1 (bijv. 0,8) verkleint de lettergrootte en meer dan 1 (bijv. 1,5) vergroot deze.

Button Voorbeeld

Actieknoppen kunnen een voorbeeldafbeelding weergeven van de bron die ze aansturen, of een andere bron die beschikbaar is in het document.

Afhankelijk van of de bron statisch is (alleen afbeeldingen die naar mimoLive werden gesleept), een statische PNG representatie van de bron wordt eenmaal geladen die een alfakanaal ondersteunt. Voor elke andere bron wordt een JPEG weergave van de bron wordt regelmatig bijgewerkt. De beoogde vernieuwingsfrequentie voor dynamische bronnen is 5 frames per seconde, maar deze snelheid wordt verlaagd als blijkt dat de snelheid van de netwerkverbinding onvoldoende is voor het herhaaldelijk laden van voorbeeldframes.

Het wordt momenteel niet ondersteund om de programma-uitvoer van het document weer te geven op een actieknop. Standaardafbeeldingen van lagen, hoewel niet zichtbaar in de lijst met bronnen, zijn beschikbaar als voorbeeld.

Om een bronvoorbeeld te specificeren, wordt een objectresolutiemechanisme gebruikt:

• De "document-ID" wordt altijd tijdens runtime getekend, dus deze hoeft niet aanwezig te zijn in de preset.
• Als "sourceId" is opgegeven, wordt de bron met die ID gebruikt voor de preview.
• Als alle "layerId", "variantId" en "dynamicSourceId" zijn opgegeven, wordt de ID van de bron opgezocht in de variant van de opgegeven laag onder de sleutel in "dynamicSourceId". Dit kan worden gebruikt om te verwijzen naar bronnen zoals bron A-G van de videoswitcher, zelfs als ze in het document worden gewijzigd.

Button Kleur

Door het "color" attribuut te gebruiken, kunnen knoppen worden gekleurd met elke kleurcode die kan worden weergegeven in HTML (bijvoorbeeld "#f80", "#ff0088", "oranje" of "rgb(255, 66, 88)").

Button Pictogram

Buttons kunnen een pictogram weergeven om hun functionaliteit aan te geven. Om een lijst met alle beschikbare pictogrammen te zien, opent u http://localhost:8989/icons/demo.html terwijl mimoLive draait en de afstandsbedieningen zijn ingeschakeld.
Gebruik de gewone naam van het pictogram, bijv.