API preset kendali jarak jauh

Jika Anda membuat layer khusus, ada kemungkinan untuk menyertakan preset kontrol khusus pada layer Anda. Hal ini akan sangat berguna jika layer Anda memiliki tombol-tombol tekan yang mengontrol perilaku layer Anda saat ditayangkan.

Struktur Data

Struktur data berikut ini adalah contoh output yang perlu ada dalam komposisi Anda di bawah kunci output struktur `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"
          }
        }
      ]
    }
  ]
}

Preset memiliki "judul" dan serangkaian "tombol", tetapi satu tombol tunggal juga tidak masalah.

Menggunakan Preset Remote Control API dalam Komposer Kuarsa

Pembangunan lapisan mimoLive menggunakan LUA untuk menghasilkan struktur data ini secara dinamis karena Quartz Composer tidak mendukung pembuatan struktur data sendiri. Struktur data LUA berisi fungsi kompleks addButton() yang dapat digunakan untuk membuat struktur untuk satu tombol. Biasanya Anda dapat menggunakan fungsi ini dan tidak perlu memodifikasinya. Oleh karena itu, cukup mudah untuk membuat pengaturan default kendali jarak jauh yang baru untuk layer Anda sendiri.

Sebagai contoh, ini adalah LUA untuk menghasilkan kendali jarak jauh untuk layer Stop Watch. Harap perhatikan bahwa Anda dapat menggunakan kode ini dengan hanya mengubah baris 15 sampai 29 dari kode tersebut.

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

Pemosisian Button

Apabila menggunakan banyak tombol, tata letak tombol harus dikontrol secara manual. Itu berarti, bahwa tombol diposisikan pada kisi-kisi dengan menggunakan atribut "x" dan "y", yang, seperti halnya atribut "lebar" dan "tinggi", diberikan dalam kelipatan sel kisi-kisi. Posisi relatif ke sel kisi-kisi kiri atas tempat kelompok tombol diseret.

Tindakan Button

Buttons dapat memiliki beberapa tindakan, satu tindakan tunggal, atau tidak sama sekali. Ada berbagai kombinasi yang valid dari target tindakan dan jenis tindakan.
Perhatikan bahwa tindakan "textInput" dan "numericInput" harus dilakukan sendiri-sendiri, karena pengalaman pengguna yang konsisten pada remote control tidak dijamin.

Target Aksi

Target aksi adalah elemen-elemen di dalam dokumen mimoLive. Mereka ditangani dengan cara yang hirarkis:

"ID dokumen" selalu diambil pada saat runtime, jadi tidak harus ada dalam preset.

• Jika "layerId" atau "variantId" tidak diberikan, tindakan akan dipicu pada dokumen itu sendiri.
• Jika "layerId" diberikan, tindakan akan dipicu pada layer yang ditentukan.
• Jika "layerId" dan "variantId" diberikan, tindakan akan dipicu pada varian yang ditentukan. Hanya dalam kasus ini, "toggleSwitchKey" atau "signalKey" tambahan dapat ditentukan (lihat Jenis Tindakan di bawah).

Jenis Tindakan

Status Langsung Button

Objek "liveState" dapat digunakan untuk mengonfigurasi status lampu penghitungan tombol, yang dapat menyala (tanda merah), transisi (tanda kuning), atau mati (tanpa tanda).

Sumber Status Langsung

Serupa dengan target aksi tombol, status live dapat diperoleh dari berbagai sumber:

• "ID dokumen" selalu diambil pada saat runtime, jadi tidak harus ada dalam preset.
• Jika "layerId" atau "variantId" tidak diberikan, status live dokumen akan digunakan (tayangan telah dimulai atau belum).
• Jika "layerId" diberikan, status live layer akan digunakan.
• Jika "layerId" dan "variantId" diberikan, status live varian akan digunakan.
  - Hanya dalam kasus ini, "propertyPath" tambahan dapat ditentukan untuk mengindikasikan bahwa properti boolean pada nilai input atau output varian harus digunakan.
  - Kemungkinan lain (saling terpisah dengan propertyPath!) adalah menentukan properti "dynamicSourceId" yang mengalihkan pencarian live state ke sumber (diambil berdasarkan ID), yang menghargai perubahan dinamis dari sumber yang dipilih (misalnya dalam pengalih video). Nilai "dynamicSourceId" dicari dalam nilai input varian.

*Berikan jalur lengkap ke properti, dimulai dari varian sebagai root, misalnya "inputValues.some_Boolean_Property" atau "outputValues.other_Property".

• Jika "sourceId" diberikan, status hidup sumber akan digunakan.

Teks Button

Tombol aksi dapat menampilkan baris teks primer dan sekunder, keduanya bisa bersifat statis atau dinamis.

Teks Primer

Teks ini akan menjadi indikator utama apa yang akan dilakukan tombol bagi pengguna. Jika preset tombol berisi properti teks, ini adalah teks statis yang akan ditampilkan apa adanya.

Sebagai alternatif, dynamicText dapat diberikan yang memungkinkan penyertaan layer mimoLive atau properti varian menggunakan sintaks templating sederhana. Dalam string templat, karakter biasa dapat dikombinasikan dengan jalur properti yang diapit oleh tanda kurung kurawal:

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

Jalur properti dievaluasi relatif terhadap objek yang diselesaikan menggunakan "layerId", "varianId", "sourceId", dan "filterId". Resolusi target mengikuti aturan-aturan ini:

• "ID dokumen" selalu diambil pada saat runtime, jadi tidak harus ada dalam preset.
• Jika "layerId" atau "variantId" tidak diberikan, jalur properti dievaluasi relatif terhadap dokumen
• Jika "layerId" (dan secara opsional "variantId") diberikan, jalur properti dievaluasi secara relatif terhadap layer/variant.
• Layer induk varian dapat diakses dengan memulai jalur dengan "layer", seperti "aslayer.name".

• Teks statis akan selalu diutamakan daripada teks dinamis, karena hal ini memungkinkan pengguna untuk menimpa teks dinamis dengan beberapa teks khusus yang mungkin lebih berguna dalam situasi mereka.

Teks Sekunder

Untuk memberikan informasi lebih lanjut kepada pengguna tentang sebuah tombol, seperti nama layer induknya, teks sekunder dapat diberikan dengan menggunakan properti "subtext" atau "dynamicSubText".

Sintaks templating dan resolusi objek mengikuti aturan yang sama persis dengan teks utama.

Ukuran Teks dan Ikon Button

Teks pada ikon pada tombol dapat bervariasi ukurannya berdasarkan konteks. Dengan opsi "fontScale" Anda dapat menentukan skala relatif terhadap ukuran default yang dihitung untuk ukuran layar saat ini. "1" akan menjadi ukuran default. Kurang dari 1 (misalnya 0,8) akan memperkecil ukuran font dan lebih besar dari 1,5 akan memperbesarnya.

Pratinjau Button

Tombol aksi dapat menampilkan gambar pratinjau dari sumber yang dikontrolnya, atau sumber lain yang tersedia di dalam dokumen.

Tergantung pada apakah sumbernya statis (hanya gambar yang diseret ke mimoLive), sumber statis PNG Representasi sumber dimuat sekali yang memang mendukung saluran alfa. Untuk sumber lainnya, sebuah JPEG representasi sumber diperbarui secara teratur. Kecepatan refresh target untuk sumber dinamis adalah 5 frame per detik, tetapi kecepatan ini dikurangi apabila kecepatan koneksi jaringan ternyata tidak mencukupi untuk pemuatan frame pratinjau yang berulang-ulang.

Saat ini tidak didukung untuk menampilkan output program dokumen pada tombol aksi. Gambar default layer, meskipun tidak terlihat dalam daftar sumber, tersedia untuk pratinjau.

Untuk menentukan pratinjau sumber, digunakan mekanisme resolusi objek:

• "ID dokumen" selalu diambil pada saat runtime, jadi tidak harus ada dalam preset.
• Jika "sourceId" diberikan, sumber dengan ID tersebut digunakan untuk pratinjau.
• Jika semua "layerId", "variantId", dan "dynamicSourceId" diberikan, ID sumber akan dicari pada varian layer yang ditentukan di bawah kunci di "dynamicSourceId". Ini dapat digunakan untuk mereferensikan sumber seperti sumber pengalih video A-G, bahkan ketika sumber tersebut diubah dalam dokumen.

Warna Button

Dengan menggunakan atribut "color", tombol dapat diwarnai dengan kode warna apa pun yang dapat direpresentasikan dalam HTML (misalnya "#f80", "#ff0088", "oranye", atau "rgb(255, 66, 88)").

Ikon Button

Buttons dapat menampilkan ikon untuk menunjukkan fungsinya. Untuk melihat daftar semua ikon yang tersedia, buka http://localhost:8989/icons/demo.html ketika mimoLive sedang berjalan dan kontrol jarak jauh diaktifkan.
Gunakan nama sederhana dari ikon tersebut, misalnya "mundur" atau "panah ke bawah".