API pour les préréglages de la télécommande

Si vous créez un calque personnalisé, il est même possible d'inclure des préréglages de contrôle personnalisés avec votre calque. Cela peut s'avérer utile si votre calque comporte des boutons-poussoirs qui contrôlent le comportement de votre calque lorsqu'il est en ligne.

Structure des données

La structure de données suivante est un exemple de sortie qui doit être présente dans votre composition sous la clé de sortie de la structure `tvOut_ControlRepresentations` :

{
  "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"
          }
        }
      ]
    }
  ]
}

Un préréglage a un "titre" et un tableau de "boutons", mais un seul bouton est également acceptable.

Utilisation de la télécommande Préréglage API dans Quartz Composer

Les couches intégrées de mimoLive utilisent une couche de LUA pour générer dynamiquement cette structure de données, car Quartz Composer ne prend pas en charge la génération de structures de données par lui-même. Le script LUA contient une fonction complexe, addButton(), qui peut être utilisée pour créer la structure d'un seul bouton. En général, il suffit d'utiliser cette fonction et il n'est pas nécessaire de la modifier. Il est donc assez facile de créer de nouveaux paramètres par défaut de télécommande pour votre propre couche.

Il s'agit par exemple de la LUA pour générer les télécommandes du calque Stop Watch. Notez que vous pouvez adopter ce code en modifiant simplement les lignes 15 à 29 du code.

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 Positionnement

Lors de l'utilisation de plusieurs boutons, la disposition des boutons doit être contrôlée manuellement. Cela signifie que les boutons sont positionnés sur la grille à l'aide des attributs "x" et "y" qui, tout comme les attributs "width" et "height", sont donnés en multiples de cellules de la grille. Les positions sont relatives à la cellule supérieure gauche de la grille sur laquelle le groupe de boutons a été glissé.

Button Actions

Les Buttons peuvent avoir plusieurs actions, une seule action ou aucune. Il existe plusieurs combinaisons valables de cibles et de types d'action.
Notez que les actions "textInput" et "numericInput" doivent être indépendantes, car une expérience utilisateur cohérente dans la télécommande n'est pas garantie.

Objectifs d'action

Les cibles d'action sont des éléments du document mimoLive. Ils sont traités de manière hiérarchique :

Le "document ID" est toujours dessiné au moment de l'exécution, il ne doit donc pas être présent dans le préréglage.

• Si ni "layerId" ni "variantId" ne sont indiqués, l'action sera déclenchée sur le document lui-même.
• Si "layerId" est indiqué, l'action sera déclenchée sur la couche spécifiée.
• Si "layerId" et "variantId" sont données, l'action sera déclenchée sur la variante spécifiée. Dans ce cas uniquement, les options "toggleSwitchKey" ou "signalKey" peuvent être spécifiées (voir les types d'action ci-dessous).

Types d'actions

Button État vivant

L'objet "liveState" permet de configurer l'état de la lampe tally du bouton, qui peut être allumée (marquage rouge), en transition (marquage jaune) ou éteinte (pas de marquage).

Sources de l'État en direct

Comme pour les cibles d'action des boutons, l'état réel peut être obtenu à partir de plusieurs sources :

• Le "document ID" est toujours dessiné au moment de l'exécution, il ne doit donc pas être présent dans le préréglage.
• Si ni "layerId" ni "variantId" ne sont fournis, c'est l'état du document en direct qui est utilisé (le spectacle a commencé ou non).
• Si "layerId" est indiqué, c'est l'état de la couche qui est utilisé.
• Si "layerId" et "variantId" sont donnés, l'état de la variante est utilisé.
  - Dans ce cas uniquement, le paramètre supplémentaire "propertyPath" peut être spécifié pour indiquer qu'une propriété booléenne sur les valeurs d'entrée ou de sortie de la variante doit être utilisée.
  - Une autre possibilité (mutuellement exclusive avec propertyPath !) est de spécifier une propriété "dynamicSourceId" qui redirige la recherche d'état en direct vers une source (recherchée par ID), qui respecte les changements dynamiques de la source sélectionnée (par exemple, dans le sélecteur vidéo). La valeur de "dynamicSourceId" est recherchée dans les valeurs d'entrée de la variante.

*Indiquer le chemin complet vers la propriété, en commençant par la variante en tant que racine, par exemple "inputValues.some_Boolean_Property" ou "outputValues.other_Property".

• Si "sourceId" est indiqué, l'état de la source est utilisé.

Button Texte

Les boutons d'action peuvent afficher des lignes de texte principales et secondaires, qui peuvent être statiques ou dynamiques.

Texte primaire

Ce texte sera le principal indicateur de ce que le bouton fera pour l'utilisateur. Si le préréglage du bouton contient une propriété textuelle, il s'agit d'un texte statique qui sera affiché tel quel.

Il est également possible d'utiliser un texte dynamique qui permet d'inclure des propriétés de couches ou de variantes mimoLive à l'aide d'une syntaxe de modélisation simple. Dans la chaîne de caractères du modèle, des caractères ordinaires peuvent être combinés avec des chemins d'accès aux propriétés entre accolades :

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

Les chemins d'accès aux propriétés sont évalués par rapport à l'objet qui est résolu à l'aide de "layerId", "variantId", "sourceId" et "filterId". La résolution des cibles suit ces règles :

• Le "document ID" est toujours dessiné au moment de l'exécution, il ne doit donc pas être présent dans le préréglage.
• Si ni "layerId" ni "variantId" ne sont indiqués, les chemins d'accès aux propriétés sont évalués par rapport au document.
• Si "layerId" (et optionnellement "variantId") est donné, les chemins d'accès aux propriétés sont évalués par rapport à une couche/variante.
• Il est possible d'accéder au calque parent d'une variante en commençant le chemin par "calque", par exemple "calque.nom".

• Le texte statique aura toujours la priorité sur le texte dynamique, car il permet aux utilisateurs de remplacer le texte dynamique par un texte personnalisé qui pourrait être plus utile dans leur situation.

Texte secondaire

Pour donner à l'utilisateur plus d'informations sur un bouton, comme le nom de son calque parent, un texte secondaire peut être donné en utilisant les propriétés "subtext" ou "dynamicSubText".

La syntaxe du modèle et la résolution des objets suivent exactement les mêmes règles que le texte principal.

Button Taille du texte et de l'icône

La taille du texte et des icônes sur les boutons peut varier en fonction du contexte. L'option "fontScale" permet de spécifier une échelle relative par rapport à une taille par défaut calculée pour la taille actuelle de l'écran. La taille par défaut est "1". Une valeur inférieure à 1 (par exemple 0,8) réduira la taille de la police et une valeur supérieure à 1 (par exemple 1,5) l'augmentera.

Button Aperçu

Les boutons d'action peuvent afficher une image de prévisualisation de la source qu'ils contrôlent ou de toute autre source disponible dans le document.

Selon que la source est statique (uniquement les images qui ont été glissées dans mimoLive), une image statique peut être utilisée. PNG de la source est chargée une fois, qui supporte un canal alpha. Pour toute autre source, un JPEG La représentation de la source est mise à jour régulièrement. Le taux de rafraîchissement cible pour les sources dynamiques est de 5 images par seconde, mais ce taux est réduit lorsque la vitesse de connexion au réseau s'avère insuffisante pour le chargement répété des images de prévisualisation.

Il n'est actuellement pas possible d'afficher la sortie du programme du document sur un bouton d'action. Les images par défaut du calque, bien que non visibles dans la liste des sources, sont disponibles pour la prévisualisation.

Pour spécifier un aperçu de la source, un mécanisme de résolution d'objets est utilisé :

• Le "document ID" est toujours dessiné au moment de l'exécution, il ne doit donc pas être présent dans le préréglage.
• Si "sourceId" est donné, la source avec cet ID est utilisée pour la prévisualisation.
• Si tous les éléments "layerId", "variantId" et "dynamicSourceId" sont fournis, l'identifiant de la source sera recherché dans la variante du calque spécifié sous la clé "dynamicSourceId". Cela permet de référencer des sources telles que les sources A à G du commutateur vidéo, même lorsqu'elles sont modifiées dans le document.

Button Couleur

En utilisant l'attribut "color", les boutons peuvent être colorés avec n'importe quel code de couleur représentable en HTML (par exemple, "#f80", "#ff0088", "orange" ou "rgb(255, 66, 88)").

Button Icône

Les Buttons peuvent afficher une icône pour indiquer leur fonctionnalité. Pour voir la liste de toutes les icônes disponibles, ouvrez le site http://localhost:8989/icons/demo.html lorsque mimoLive est en cours d'exécution et que les télécommandes sont activées.
Utilisez le nom simple de l'icône, par exemple "retour en arrière" ou "flèche vers le bas".