SDK docs menuMethods

Methods

Every method of EvmuxAppsApi with examples: settings, apps, social, scenes, studio modules, media, participants, sound and the account plan.

All examples assume an instance named evmuxApi:

import EvmuxAppsApi from 'evmux-app-framework/src/EvmuxAppsApi/EvmuxAppsApi'

const evmuxApi = new EvmuxAppsApi()

Asynchronous methods resolve to an object with the result in response.

Settings

Global methods, called on the instance itself. They read and write the settings object of the app instance.

Method Parameters Returns
getSettings() { response: settingsObject }
updateSettings(settings) The settings object to save.
const settingsResponse = await evmuxApi.getSettings()
const settings = settingsResponse.response

settings.title = 'My New Title'
await evmuxApi.updateSettings(settings)

Apps

Methods for the app itself: its fast action buttons, its messages and its settings sidebar.

Method Parameters Returns
apps.setFastActionButtons(buttons, options) An array of buttons, and optional settings for the group.
raiseAppMessagingEvent(data) A JSON object.
apps.sendMessageToApp(userAppInstanceId, data) The instance id of the app to send to, and a JSON object.
apps.isSudioMode() { response: boolean }
apps.openSideBarSettings()
const icon = `<svg ... />`

// register a fast action button
evmuxApi.apps.setFastActionButtons([
  { buttonId: 'spin', buttonText: 'Spin The Wheel!', params: {}, icon: icon },
])

// send a message to all instances of your app
// all your other instances can listen for that event
evmuxApi.raiseAppMessagingEvent({ exampleKey: 'exampleVal' })

const isStudioModeResponse = await evmuxApi.apps.isSudioMode()

A button has a buttonId, a buttonText, an icon as an SVG string, and params, which is any data you want back when it is clicked. The optional second argument describes the group of buttons:

Option Default Description
groupName "" A name for the group of buttons.
groupIcon null An icon for the group.
showToSpeakersAndGuests false Show the buttons to speakers and guests too, not only to editors.
evmuxApi.apps.setFastActionButtons(
  [
    { buttonId: 'spin', buttonText: 'Spin', params: {}, icon: icon },
    { buttonId: 'reset', buttonText: 'Reset', params: {}, icon: icon },
  ],
  { groupName: 'Wheel', groupIcon: icon, showToSpeakersAndGuests: false },
)

When the user clicks one of your buttons, your app receives the fastActionButton event. A message sent with raiseAppMessagingEvent arrives as the appMessaging event, and one sent with sendMessageToApp arrives in the other app as externalAppMessaging.

raiseAppMessagingEvent is called on the instance itself, not on apps. The Studio Mode check is spelled isSudioMode in the SDK.

Social

Methods for the comments and statistics of the connected channels.

To be called when new comments arrive, register for the comments event.

Method Notes Returns
social.getStatistics() The data may differ from one network to another. { response: [channelStatistics, ...] }
social.getComments() { response: [comment, ...] }
social.addComment(comment) Works only while the show is live.
const comments = await evmuxApi.social.getComments()

const statistics = await evmuxApi.social.getStatistics()

// works only during a live broadcast
const res = await evmuxApi.social.addComment({
  title: 'Dana Cohen',
  text: 'Won round 1 with 9/10!',
  pic: 'https://LINK_TO_USER_AVATAR.jpg', // optional
  logo: 'https://myapp.example.com/app-logo.png', // optional, shown as the network logo (fb, yt, zoom and so on)
  flags: { star: false }, // optional
})

A statistics response

{
  "response": [
    {
      "viewers": 1,
      "type": "youtubeChannel",
      "statistics": {
        "channel": {
          "viewCount": "2",
          "subscriberCount": "4",
          "hiddenSubscriberCount": false,
          "videoCount": "2",
          "subscribers": "4"
        },
        "live": {
          "viewCount": "0",
          "likeCount": "0",
          "dislikeCount": "0",
          "favoriteCount": "0",
          "commentCount": "0"
        }
      },
      "last_subscribers": []
    }
  ]
}

A comments response

{
  "response": [
    {
      "id": "1fsdf",
      "title": "Sample comment",
      "text": "Comments will appear here once the broadcast starts.",
      "pic": "imgUrl",
      "style": "comment",
      "enabled": true,
      "created_time": "2024-12-10T06:54:11.907Z",
      "sn": "fb",
      "flags": { "sample": true, "star": false, "shown": false }
    }
  ]
}

Scene

Methods for the scenes of the studio and their layers.

Method Notes Returns
scene.createNewLayer(layerType, params)
scene.switchScene({ id })
scene.getLayerDisplayableName(layerId, sceneId) { response: "My Layer Name" }
scene.list() { response: [scene, ...] }
scene.updateLayer({ sceneId, layer }) Pass a layer object taken from a scene.
scene.removeSizeCatcher() Lets the user interact with the widget’s window.
// layerTypes is exported next to EvmuxAppsApi
await evmuxApi.scene.createNewLayer(layerTypes.userApp, {})

await evmuxApi.scene.switchScene({ id: sceneId })

const layerNameResponse = await evmuxApi.scene.getLayerDisplayableName('83821da1-feea-4d80-9e92-5b640424b4a4', 672)

const allScenesResponse = await evmuxApi.scene.list()

await evmuxApi.scene.updateLayer({ sceneId: sceneId, layer: layerObjFromScene })

A scene list response

{
  "response": [
    {
      "id": 672,
      "order": 0,
      "name": "My Scene",
      "stingerData": {},
      "backgroundColor": {},
      "overWriteBackgroundColor": false,
      "layers": [],
      "thumbnail": { "landscape": "...", "portrait": "..." },
      "isCurrentScene": false
    }
  ]
}

Studio modules

Methods that open the studio’s own pickers, editors and notifications, so your app does not have to build them.

Method Notes Returns
modules.displayScenePicker(selectedScene) { response: sceneObject }
modules.displayRichTextEditor({ textValue, title }) { response: html }
modules.displayDateTimePicker(type, currentValue, timezone, minDate, maxDate) Every parameter is optional. See below. { response: { value } }
modules.displayToast({ text, type, uniqCode })
modules.displayGalleryPicker(title, selectedIds, allowMultiselect, lockFilters, filters) { response: [file, ...] }
modules.displayLayerSelector(layers, layerTypeFilter, allowHiddenLayers, allowMultiSelect) Lets the user pick layers.
modules.displaySpeakerSelector(speakers, participantTypes, allowMultiSelect, onlineOnly) Lets the user pick participants. { response: { speakers } }
modules.displayInputs(title, inputs) Asks the user to fill in one or more inputs.

Do not store the URLs of the files the gallery picker returns, they expire. Store the ids, and ask for the files with the media methods each time.

// the id of an already selected scene to show as selected, or null for a simple picker
const selectedSceneInPicker = null
const sceneObjectResponse = await evmuxApi.modules.displayScenePicker(selectedSceneInPicker)
// { response: sceneObject }

const richTextResponse = await evmuxApi.modules.displayRichTextEditor({
  textValue: '<p><strong>Text Already In Editor</strong></p>',
  title: 'Type Your Text',
})
// { response: '<p>a text <strong>user</strong> <u>entered</u></p>' }

const selectedDateTimeResponse = await evmuxApi.modules.displayDateTimePicker()
// { response: { value: 1735119420000 } }

evmuxApi.modules.displayToast({
  text: 'This is example toast notification in the studio',
  type: 'info',
  uniqCode: 'exampleCode',
})

const selectedFiles = await evmuxApi.modules.displayGalleryPicker(
  'Please choose file',
  [],
  true,
  true,
  ['Image', 'Video', 'Doc', 'Audio'],
)
// { response: [selectedFile1, selectedFile2, ...] }

The date and time picker

Parameter Default Description
type 'datetime' 'datetime', 'date' or 'time'.
currentValue Now The value the picker opens with, as a timestamp in milliseconds.
timezone The browser’s time zone An IANA time zone name, such as 'Europe/London'.
minDate Now The earliest value the user can pick, as a timestamp in milliseconds.
maxDate One year from now The latest value the user can pick, as a timestamp in milliseconds.
const inOneHour = Date.now() + 60 * 60 * 1000

const response = await evmuxApi.modules.displayDateTimePicker('datetime', inOneHour, 'Europe/London')

The layer and participant selectors

// let the user pick one or more visible layers
const layersResponse = await evmuxApi.modules.displayLayerSelector([], [], false, true)

// let the user pick one participant who is online
const speakersResponse = await evmuxApi.modules.displaySpeakerSelector([], [], false, true)
// { response: { speakers: [participant, ...] } }

The first argument of each selector is the list that is already selected. layerTypeFilter and participantTypes narrow what the user can choose from, and an empty array means no filter.

A participant looks like this:

{ "idx": "mock-speaker-1", "name": "John Doe", "pic": null, "client_type": "speaker", "isConnected": true }

Inputs

displayInputs opens a small form in the studio. Give each input a myId of your own, so you can tell the inputs apart in the answer:

const inputsResponse = await evmuxApi.modules.displayInputs('Player name', [
  { type: 'string', min: 0, max: 256, value: 'Input Text Here', myId: 'playerName' },
])

Media

Methods for the media assets of the studio.

Method Notes Returns
media.listAssets(ids) Pass an empty array to get every asset. { response: [file1, file2, ...] }
const allStudioAssets = await evmuxApi.media.listAssets([])

const someAssets = await evmuxApi.media.listAssets([1234, 765, 11])

Studio

Methods for the studio itself and the people in it.

Method Notes Returns
studio.getStudioParams() { response: studioParams }
studio.getParticipants(participantTypes, onlineOnly) Both parameters are optional. { response: participants }
const studioParamsResponse = await evmuxApi.studio.getStudioParams()

// everyone, online or not
const everyoneResponse = await evmuxApi.studio.getParticipants()

// only the participants who are connected right now
const onlineResponse = await evmuxApi.studio.getParticipants([], true)

To be called when the parameters change or when people come and go, register for the studioParamsUpdated, participantJoined and participantLeft events.

A studio parameters response

{
  "response": {
    "antiScaleValue": 4.481327800829876,
    "antiScaleValue2": 1,
    "studioMode": false,
    "styleVersion": "light",
    "portraitStreaming": false
  }
}

The response can also describe the current user and the current scene:

{
  "currentUser": { "clientId": "mock-user-id", "clientType": 1, "userType": "editor" },
  "currentScene": { "idx": "simple", "name": "Dynamic Scene" }
}

A participants response

{
  "response": {
    "editors": [
      { "idx": "mock-editor-1", "name": "Editor One", "pic": null, "client_type": "editor", "isConnected": true }
    ],
    "speakers": [
      { "idx": "mock-speaker-1", "name": "Speaker One", "pic": null, "client_type": "speaker", "isConnected": true }
    ],
    "guests": []
  }
}

Sound

Methods for the sound of your widget and of the scene.

Method Notes Returns
getVolumeMultiplier() Called on the instance itself. The multiplier is 1 unless the studio changed it. { response: { value } }
studio.getSoundRtc(type, layerId, preferredCodecs) Asks the studio for a WebRTC sound channel. type is 'scene' by default. Pass a layerId for the sound of one layer.
studio.signal(data) Sends a WebRTC signaling message to the studio.

If your widget plays sound, multiply its volume by the volume multiplier, and follow the volumeMultiplier event to keep it up to date:

const { response } = await evmuxApi.getVolumeMultiplier()
audioElement.volume = baseVolume * response.value

Signaling messages from the studio arrive as the signalingEvent event.

Account

Methods for the plan of the account that runs the studio. They are on evmuxApi.misc.

Method Notes Returns
misc.accountPlanCapabilities() What the account’s plan allows. { response: { value } }
misc.upgradePopup(title, text) Shows the studio’s upgrade popup with your title and text.
misc.createStream() { response: { value } }
const { response } = await evmuxApi.misc.accountPlanCapabilities()
const capabilities = response.value

await evmuxApi.misc.upgradePopup('More players', 'Upgrade your plan to play with more than 10 players.')

Stuck, or found a mistake in these docs? Tell us.