API de preajustes del mando a distancia

Si está creando una capa personalizada, existe la posibilidad de incluir preajustes de control personalizados con su capa. Esto es útil si la capa tiene botones que controlan el comportamiento de la capa cuando está activa.

Estructura de datos

La siguiente estructura de datos es un ejemplo de salida que debe estar presente en su composición bajo la clave de salida de la estructura `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 preajuste tiene un "título" y una serie de "botones", pero un solo botón también está bien.

*

Las claves `layerId` y `variantId` deben rellenarse dinámicamente con los datos de cadena de las claves de entrada de composición `tvIn_LayerIdentifier` y `tvIn_RuntimeIdentifier`.

Uso de la preselección del mando a distancia API en Quartz Composer

Las capas incorporadas de mimoLive utilizan un LUA para generar dinámicamente esta estructura de datos porque Quartz Composer no soporta la generación de estructuras de datos por sí mismo. El LUA contiene una función compleja addButton() que se puede utilizar para crear la estructura de un solo botón. Usualmente puedes usar esta función y no necesitas modificarla. Por lo tanto, es bastante fácil construir nuevas configuraciones predeterminadas de control remoto para su propia capa.

Por ejemplo LUA para generar los controles remotos de la capa Cronómetro. Tenga en cuenta que puede adoptar este código con sólo cambiar las líneas 15 a 29 del código.

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 Posicionamiento

Cuando se utilizan varios botones, su disposición debe controlarse manualmente. Esto significa que los botones se colocan en la cuadrícula mediante los atributos "x" e "y", que, al igual que los atributos "anchura" y "altura", se indican en múltiplos de celdas de la cuadrícula. Las posiciones son relativas a la celda superior izquierda de la cuadrícula a la que se ha arrastrado el grupo de botones.

Button Acciones

1TP14Las acciones pueden ser múltiples, una sola o ninguna. Existen varias combinaciones válidas de objetivos de acción y tipos de acción.
Tenga en cuenta que las acciones "textInput" y "numericInput" deben ir por separado, ya que no se garantiza una experiencia de usuario coherente en el mando a distancia.

Objetivos de la acción

Los objetivos de acción son elementos dentro del documento mimoLive. Se abordan de forma jerárquica:

El "ID del documento" se dibuja siempre en tiempo de ejecución, por lo que no tiene que estar presente en el preajuste.

• Si no se indican ni "layerId" ni "variantId", la acción se activará en el propio documento.
• Si se indica "layerId", la acción se activará en la capa especificada.
• Si "layerId" y "variantId", la acción se activará en la variante especificada. Sólo en este caso, se puede especificar "toggleSwitchKey" o "signalKey" adicionales (véase Tipos de acción más abajo).

Tipos de acción

Tipo de acción	Explicación	Atributos adicionales	Objetivos válidos
toggleLive	Alternar el estado en directo	ninguno	Documento (Iniciar/Parar espectáculo), Capa, Variante
setLive	Establecer el estado "live" a "live"	ninguno	Documento (Start Show), Capa, Variante
setOff	Poner el estado en directo en "off"	ninguno	Documento (Stop Show), Capa, Variante
señal	Activar una señal	signalKey, signalName (recomendado)	Variante
toggleSwitch	Conmutar un valor de entrada booleano	toggleSwitchKey, toggleSwitchName (recomendado)	Variante
textInput	Abre un campo de entrada de texto que, al enviarse, actualiza el valor de inputKey.	inputKey, inputName (recomendado)	Capa, Variante, Fuente
numericInput	Deslizador que controla un valor numérico en inputKey.	inputKey, inputDescription (objeto con valores mínimo y máximo), inputName (recomendado)	Capa, Variante, Fuente

*

Los tipos de acción "textInput" y "numericInput" están disponibles desde mimoLive 5.2.

Button Estado vivo

El objeto "liveState" permite configurar el estado de la luz de recuento del botón, que puede estar encendido (marca roja), en transición (marca amarilla) o apagado (sin marca).

Fuentes estatales vivas

De forma similar a los objetivos de acción de los botones, el estado vivo puede obtenerse de múltiples fuentes:

• El "ID del documento" se dibuja siempre en tiempo de ejecución, por lo que no tiene que estar presente en el preajuste.
• Si no se indican ni "layerId" ni "variantId", se utilizará el estado en directo del documento (se ha iniciado la presentación o no).
• Si se indica "layerId", se utiliza el estado activo de la capa.
• Si se indican "layerId" y "variantId", se utiliza el estado activo de la variante.
  - Sólo en este caso, se puede especificar "propertyPath" adicional para indicar que se debe utilizar una propiedad booleana en los valores de entrada o salida de la variante.
  - Otra posibilidad (¡mutuamente excluyente con propertyPath!) es especificar una propiedad "dynamicSourceId" que redirija la búsqueda de estado en directo a una fuente (obtenida por ID), que respete los cambios dinámicos de la fuente seleccionada (por ejemplo, en el conmutador de vídeo). El valor de "dynamicSourceId" se busca en los valores de entrada de la variante.

Indique la ruta completa a la propiedad, empezando por la variante como raíz, por ejemplo "inputValues.some_Boolean_Property" o "outputValues.other_Property".

• Si se indica "sourceId", se utiliza el estado activo de la fuente.

Button Texto

Los botones de acción pueden mostrar líneas de texto primarias y secundarias, ambas pueden ser de naturaleza estática o dinámica.

Texto principal

Este texto será el indicador principal de lo que el botón hará por el usuario. Si el botón preestablecido contiene una propiedad de texto, es un texto estático que se mostrará tal cual.

Alternativamente, se puede dar un dynamicText que permite la inclusión de propiedades de capa o variante mimoLive utilizando una sencilla sintaxis de plantilla. En la cadena de plantilla, se pueden combinar caracteres regulares con rutas de propiedades encerradas entre llaves:

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

Las rutas de las propiedades se evalúan en relación con el objeto que se resuelve utilizando "layerId", "variantId", "sourceId" y "filterId". La resolución del objetivo sigue estas reglas:

• El "ID del documento" se dibuja siempre en tiempo de ejecución, por lo que no tiene que estar presente en el preajuste.
• Si no se indican ni "layerId" ni "variantId", las rutas de las propiedades se evalúan en relación con el documento
• Si se indica "layerId" (y opcionalmente "variantId"), las rutas de las propiedades se evalúan en relación con una capa/variante.
• Se puede acceder a la capa padre de una variante iniciando una ruta con "layer", como "aslayer.name".

*

El primer segmento de ruta de los valores de entrada y salida debe ir en camelCased ("inputValues.tvIn...") y no en kebab-cased ("input-values.tvIn...") como en los documentos de la API.

• El texto estático siempre tendrá prioridad sobre el texto dinámico, porque esto permite a los usuarios sobrescribir el texto dinámico con algún texto personalizado que pueda ser más útil en su situación.

Texto secundario

Para dar al usuario más información sobre un botón, como el nombre de su capa padre, se le puede dar un texto secundario utilizando las propiedades "subtext" o "dynamicSubText".

La sintaxis de las plantillas y la resolución de objetos siguen exactamente las mismas reglas que el texto principal.

Button Tamaño de texto e icono

El texto y los iconos de los botones pueden variar de tamaño en función del contexto. Con la opción "fontScale" puede especificar una escala relativa a un tamaño por defecto calculado para el tamaño de pantalla actual. "1" será el tamaño por defecto. Menos de 1 (por ejemplo, 0,8) reducirá el tamaño de la fuente y más de 1 (por ejemplo, 1,5) lo aumentará.

Button Avance

Los botones de acción pueden mostrar una imagen de vista previa de la fuente que controlan o de cualquier otra fuente disponible en el documento.

Dependiendo de si la fuente es estática (sólo imágenes que fueron arrastradas a mimoLive), un PNG de la fuente que sí admite un canal alfa. Para cualquier otra fuente, se carga una JPEG La representación de la fuente se actualiza regularmente. La frecuencia de actualización prevista para las fuentes dinámicas es de 5 fotogramas por segundo, pero esta frecuencia se reduce cuando la velocidad de conexión a la red resulta insuficiente para la carga repetida de fotogramas de previsualización.

Actualmente no se admite mostrar la salida del programa del documento en un botón de acción. Las imágenes por defecto de las capas, aunque no son visibles en la lista de fuentes, están disponibles para su previsualización.

Para especificar una vista previa de la fuente, se utiliza un mecanismo de resolución de objetos:

• El "ID del documento" se dibuja siempre en tiempo de ejecución, por lo que no tiene que estar presente en el preajuste.
• Si se indica "sourceId", se utilizará la fuente con ese ID para la previsualización.
• Si se indican "layerId", "variantId" y "dynamicSourceId", el ID de la fuente se buscará en la variante de la capa especificada bajo la clave de "dynamicSourceId". Esto se puede utilizar para hacer referencia a fuentes como la fuente A-G del conmutador de vídeo, incluso cuando se cambian en el documento.

Button Color

Utilizando el atributo "color", los botones pueden colorearse con cualquier código de color que sea representable en HTML (por ejemplo, "#f80", "#ff0088", "naranja" o "rgb(255, 66, 88)").

Button Icono

1TP14Los mandos a distancia pueden mostrar un icono para indicar su funcionalidad. Para ver una lista de todos los iconos disponibles, abra http://localhost:8989/icons/demo.html mientras se esté ejecutando mimoLive y los mandos a distancia estén activados.
Utilice el nombre sencillo del icono. por ejemplo, "hacia atrás" o "flecha abajo".