Web player groups

The Web player groups section covers the API endpoints used to organize multiple browser players into one grouped playback experience. This is the layer you use when viewers should switch between language feeds, file-based variants, or curated player selections without leaving the same overall viewing surface.

Compared with a single web player, a web player group adds selection policy, group-level authorization, optional pay-per-view rules, event metadata, and shared branding. The create and update calls do more than attach players: they also shape how one player is selected by default and how the grouped experience is presented to viewers.

If your team drives grouped playback from an operator workflow, the create, start, and stop examples below also include ready-to-adapt vMix Script tabs alongside the usual API snippets.

Examples by preset

The group create flow naturally breaks into a few preset families. In practice, the most useful presets are a language-selector group, a file-based variant list, a password-protected private event group, and a pay-per-view event page built around the same underlying players.

Workflow examples

These scenarios help frame why a web player group exists in a production design, not just what the payload looks like.

Use a group as the viewer-facing switcher for parallel language feeds

Create a web player group when several browser players point at parallel language or commentary feeds and viewers should be able to move between them from a single embedded experience.

Use a group as a curated file playlist selector

A file-based group works well when viewers should choose among pre-published assets or episodes while the surrounding player page, branding, and access policy stay consistent.

Use a group as the event access layer for branded private playback

When the viewer experience should combine selected players, viewer passwords, optional pay-per-view, support contact details, and event metadata, the web player group becomes the policy layer that holds those concerns together.

Create web player group
Collapse
POST
/api/vod-group/create

Creates a new web player group resource in Callaba Engine.

The current API definition exposes this method as POST /api/vod-group/create with an application/json request body. The payload combines group identity, player selection rules, optional viewer authorization, optional pay-per-view settings, and event or branding fields.

If your operators trigger grouped playback setup from production tooling, the preset examples below also include vMix Script tabs for the same request shapes.

Examples by preset

The grouped playback model is easier to copy from a few concrete presets than from one oversized catch-all payload.

Workflow-oriented use cases

Put multiple language or commentary feeds behind one viewer-facing selector

Use a group when several live players should remain separate operationally, but the viewer should switch between them from one embedded browser experience.

Attach access policy and event framing above an existing set of players

The group layer is the right place for password access, event timing, support email, and pay-per-view behavior when those concerns apply across several players together.

Language selector group

Use this when several parallel web players represent language or commentary variants and one should be selected by default.

Language selector group
curl --request POST \
  --url http://localhost/api/vod-group/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Main event language selector",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "PLAYER_ID_ENGLISH",
      "name": "English",
      "selected": true
    },
    {
      "id": "PLAYER_ID_SPANISH",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED",
    "credentials": []
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "support_email": "[email protected]",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true
}'
File playlist group

Use this when the grouped browser experience should switch between on-demand assets or prepared file-backed players.

File playlist group
curl --request POST \
  --url http://localhost/api/vod-group/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "On-demand episode selector",
  "type": "FILES_LIST",
  "players": [
    {
      "id": "PLAYER_ID_EPISODE_1",
      "name": "Episode 1",
      "selected": true
    },
    {
      "id": "PLAYER_ID_EPISODE_2",
      "name": "Episode 2",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED",
    "credentials": []
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true
}'
Password-protected event group

Use this when the grouped playback should stay private behind a shared guest password.

Password-protected event group
curl --request POST \
  --url http://localhost/api/vod-group/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Private webinar playback group",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "PLAYER_ID_PRIVATE_MAIN",
      "name": "Main stream",
      "selected": true
    }
  ],
  "authorization": {
    "authorization_type": "VOD_USE_PASSWORD",
    "credentials": [
      {
        "name": "Guest",
        "password": "guest-password"
      }
    ]
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "support_email": "[email protected]",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true
}'
Pay-per-view event group

Use this when a branded event page should wrap one or more players with PayPal-based access and event timing metadata.

Pay-per-view event group
curl --request POST \
  --url http://localhost/api/vod-group/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Paid event player group",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "PLAYER_ID_MAIN_STAGE",
      "name": "Main stage",
      "selected": true
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED",
    "credentials": []
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_PAYPAL",
    "amount": 19,
    "client_id": "PAYPAL_CLIENT_ID"
  },
  "support_email": "[email protected]",
  "event_date": "2026-04-01T18:00:00.000Z",
  "timeZone": "Europe/Istanbul",
  "eventDateStatus": "EVENTS_SET_DATE",
  "active": true
}'
Request body parameters
Identity
name
string

Dashboard label: Group name.

Human-readable name of the grouped playback experience.

type
string

Dashboard label: Type.

Real product values include LANGUAGE_LIST and FILES_LIST.

Players
players[]
array

List of linked player entries. Each item includes id, display name, and a selected flag used for the default choice.

Access
authorization
object

Optional viewer authorization block. Real product modes include VOD_PASSWORD_DISABLED, VOD_USE_PASSWORD, and email-plus-password flows.

Monetization
pay_per_view_settings
object

Optional pay-per-view block. The current dashboard exposes a PayPal-based mode in addition to the disabled default.

Presentation
cover_path / logo_path / useCustomLogo / useCustomBackground
mixed

Optional branding fields for the grouped playback page.

support_email
string

Optional support contact shown alongside the event-style player experience.

event_date / timeZone / eventDateStatus
mixed

Optional event timing metadata stored on the group.

Runtime
active
boolean

Dashboard label: Enable once created.

Controls whether the group should be active right after provisioning.

Create web player group
curl --request POST \
  --url http://localhost/api/vod-group/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Main event language selector",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "PLAYER_ID_ENGLISH",
      "name": "English",
      "selected": true
    },
    {
      "id": "PLAYER_ID_SPANISH",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED",
    "credentials": []
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "support_email": "[email protected]",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true
}'
Response
Identity
_id / id / name / type
mixed

Identifiers and the core group identity fields.

Players
players[]
array

Stored player entries in the group, including default-selection state.

Access
authorization / users
mixed

Authorization state plus any linked viewer users that belong to the group.

Monetization
pay_per_view_settings
object

Stored pay-per-view configuration for the group.

Presentation
cover_path / logo_path / support_email / event_date / timeZone / eventDateStatus
mixed

Branding and event metadata returned with the group object.

Runtime
active / created / modified
mixed

Current running-state flag and backend-managed timestamps.

Operation result
success
boolean

The model exposes success: true as a virtual field in successful responses.

Response: Create web player group
JSON
{
  "_id": "6a1144aa22bb33cc44dd55ee",
  "id": "6a1144aa22bb33cc44dd55ee",
  "name": "Main event language selector",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "6a1144aa22bb33cc44dd5601",
      "name": "English",
      "selected": true
    },
    {
      "id": "6a1144aa22bb33cc44dd5602",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED"
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "cover_path": "",
  "logo_path": "",
  "useCustomLogo": "VOD_DISABLE_LOGO",
  "useCustomBackground": "VOD_DISABLE_BACKGROUND",
  "support_email": "[email protected]",
  "event_date": "2026-04-01T18:00:00.000Z",
  "timeZone": "Europe/Istanbul",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true,
  "created": "2026-03-24T18:00:00.000Z",
  "modified": "2026-03-24T18:00:00.000Z",
  "success": true
}
Get web player groups count
Expand
POST
/api/vod-group/getCount

Returns the total number of web player groups visible to the authenticated user.

Use this method together with paginated getAll requests when you need listing totals in an admin UI or housekeeping tool.

Request body parameters
This method has no parameters
Get web player groups count
curl --request POST \
  --url http://localhost/api/vod-group/getCount \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Response
count
integer

Total number of web player groups currently visible to the authenticated user.

Response: Get web player groups count
JSON
{
  "count": 1
}
Get all web player groups
Expand
POST
/api/vod-group/getAll

Returns the list of web player groups visible to the authenticated user.

This is the normal listing method for dashboards and management tooling. The backend returns a bare array of group objects and supports the same pagination and sort pattern used elsewhere in the product.

Request body parameters
limit
integer

Optional page size for the list query.

skip
integer

Optional offset for paginated listing.

sort
object

Optional sort descriptor. The dashboard store defaults to { created: 1 }.

filter
object

Optional filter object forwarded to the backend query.

Get all web player groups
curl --request POST \
  --url http://localhost/api/vod-group/getAll \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sort": {
    "created": 1
  },
  "limit": 20,
  "skip": 0,
  "filter": {}
}'
Response
array of web player group objects
array

The backend returns a bare array of group objects, not a wrapped object.

Response: Get all web player groups
JSON
[
  {
    "_id": "6a1144aa22bb33cc44dd55ee",
    "id": "6a1144aa22bb33cc44dd55ee",
    "name": "Main event language selector",
    "type": "LANGUAGE_LIST",
    "players": [
      {
        "id": "6a1144aa22bb33cc44dd5601",
        "name": "English",
        "selected": true
      },
      {
        "id": "6a1144aa22bb33cc44dd5602",
        "name": "Spanish",
        "selected": false
      }
    ],
    "authorization": {
      "authorization_type": "VOD_PASSWORD_DISABLED"
    },
    "pay_per_view_settings": {
      "type": "PAY_PER_VIEW_DISABLED"
    },
    "cover_path": "",
    "logo_path": "",
    "useCustomLogo": "VOD_DISABLE_LOGO",
    "useCustomBackground": "VOD_DISABLE_BACKGROUND",
    "support_email": "[email protected]",
    "event_date": "2026-04-01T18:00:00.000Z",
    "timeZone": "Europe/Istanbul",
    "eventDateStatus": "EVENTS_DATE_DISABLED",
    "active": true,
    "created": "2026-03-24T18:00:00.000Z",
    "modified": "2026-03-24T18:00:00.000Z",
    "success": true
  }
]
Get web player group by id
Expand
POST
/api/vod-group/getById

Returns one web player group by id.

This is the best method when you need the full group definition, including populated player references and any linked viewer users created for password-protected playback.

Request body parameters
id
string

Identifier of the web player group you want to load.

Get web player group by id
curl --request POST \
  --url http://localhost/api/vod-group/getById \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "WEB_PLAYER_GROUP_ID"
}'
Response
web player group object
object

The backend returns the populated group object with linked players and any attached users.

Response: Get web player group by id
JSON
{
  "_id": "6a1144aa22bb33cc44dd55ee",
  "id": "6a1144aa22bb33cc44dd55ee",
  "name": "Main event language selector",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "6a1144aa22bb33cc44dd5601",
      "name": "English",
      "selected": true
    },
    {
      "id": "6a1144aa22bb33cc44dd5602",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED"
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "cover_path": "",
  "logo_path": "",
  "useCustomLogo": "VOD_DISABLE_LOGO",
  "useCustomBackground": "VOD_DISABLE_BACKGROUND",
  "support_email": "[email protected]",
  "event_date": "2026-04-01T18:00:00.000Z",
  "timeZone": "Europe/Istanbul",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true,
  "created": "2026-03-24T18:00:00.000Z",
  "modified": "2026-03-24T18:00:00.000Z",
  "success": true
}
Update web player group
Expand
POST
/api/vod-group/update

Updates an existing web player group.

The update contract mirrors create. Use it when you need to change the selected player, group type, branding, event settings, or authorization rules without rebuilding the group from scratch.

Request body parameters
id
string

Identifier of the web player group being updated.

group payload fields
mixed

The update contract mirrors create and reuses the same group-policy fields.

Update web player group
curl --request POST \
  --url http://localhost/api/vod-group/update \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "WEB_PLAYER_GROUP_ID",
  "name": "Main event language selector updated",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "PLAYER_ID_ENGLISH",
      "name": "English",
      "selected": true
    },
    {
      "id": "PLAYER_ID_SPANISH",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED",
    "credentials": []
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "support_email": "[email protected]",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true
}'
Response
updated web player group object
object

The backend returns the updated group object.

Response: Update web player group
JSON
{
  "_id": "6a1144aa22bb33cc44dd55ee",
  "id": "6a1144aa22bb33cc44dd55ee",
  "name": "Main event language selector updated",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "6a1144aa22bb33cc44dd5601",
      "name": "English",
      "selected": true
    },
    {
      "id": "6a1144aa22bb33cc44dd5602",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED"
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "cover_path": "",
  "logo_path": "",
  "useCustomLogo": "VOD_DISABLE_LOGO",
  "useCustomBackground": "VOD_DISABLE_BACKGROUND",
  "support_email": "[email protected]",
  "event_date": "2026-04-01T18:00:00.000Z",
  "timeZone": "Europe/Istanbul",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true,
  "created": "2026-03-24T18:00:00.000Z",
  "modified": "2026-03-24T18:30:00.000Z",
  "success": true
}
Start web player group
Expand
POST
/api/vod-group/start

Marks a web player group as active.

Use this when the grouped viewer experience should become available without changing the underlying player configuration.

For operator tooling, this is a good fit for a simple vMix Script button or shortcut because it toggles grouped playback availability with a minimal payload.

Request body parameters
id
string

Identifier of the web player group to start.

Start web player group
curl --request POST \
  --url http://localhost/api/vod-group/start \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "WEB_PLAYER_GROUP_ID"
}'
Response
started web player group object
object

The backend marks the group as active and returns the updated object.

Response: Start web player group
JSON
{
  "_id": "6a1144aa22bb33cc44dd55ee",
  "id": "6a1144aa22bb33cc44dd55ee",
  "name": "Main event language selector",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "6a1144aa22bb33cc44dd5601",
      "name": "English",
      "selected": true
    },
    {
      "id": "6a1144aa22bb33cc44dd5602",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED"
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "cover_path": "",
  "logo_path": "",
  "useCustomLogo": "VOD_DISABLE_LOGO",
  "useCustomBackground": "VOD_DISABLE_BACKGROUND",
  "support_email": "[email protected]",
  "event_date": "2026-04-01T18:00:00.000Z",
  "timeZone": "Europe/Istanbul",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true,
  "created": "2026-03-24T18:00:00.000Z",
  "modified": "2026-03-24T18:35:00.000Z",
  "success": true
}
Stop web player group
Expand
POST
/api/vod-group/stop

Marks a web player group as inactive.

Use this to take the grouped playback experience offline while leaving the saved player mapping intact.

This pairs naturally with the start method in vMix or other operator-side control flows.

Request body parameters
id
string

Identifier of the web player group to stop.

Stop web player group
curl --request POST \
  --url http://localhost/api/vod-group/stop \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "WEB_PLAYER_GROUP_ID"
}'
Response
stopped web player group object
object

The backend marks the group as inactive and returns the updated object.

Response: Stop web player group
JSON
{
  "_id": "6a1144aa22bb33cc44dd55ee",
  "id": "6a1144aa22bb33cc44dd55ee",
  "name": "Main event language selector",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "6a1144aa22bb33cc44dd5601",
      "name": "English",
      "selected": true
    },
    {
      "id": "6a1144aa22bb33cc44dd5602",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED"
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "cover_path": "",
  "logo_path": "",
  "useCustomLogo": "VOD_DISABLE_LOGO",
  "useCustomBackground": "VOD_DISABLE_BACKGROUND",
  "support_email": "[email protected]",
  "event_date": "2026-04-01T18:00:00.000Z",
  "timeZone": "Europe/Istanbul",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": false,
  "created": "2026-03-24T18:00:00.000Z",
  "modified": "2026-03-24T18:40:00.000Z",
  "success": true
}
Remove web player group
Expand
DELETE
/api/vod-group/remove

Removes a web player group by id.

The backend removes the group object and also clears linked per-group viewer users that were created for protected playback.

Query parameters
id
string

Identifier of the web player group to delete.

Remove web player group
curl --request DELETE \
  --url http://localhost/api/vod-group/remove \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "WEB_PLAYER_GROUP_ID"
}'
Response
removed web player group object
object

The backend deletes the group and returns the previously loaded object.

Response: Remove web player group
JSON
{
  "_id": "6a1144aa22bb33cc44dd55ee",
  "id": "6a1144aa22bb33cc44dd55ee",
  "name": "Main event language selector",
  "type": "LANGUAGE_LIST",
  "players": [
    {
      "id": "6a1144aa22bb33cc44dd5601",
      "name": "English",
      "selected": true
    },
    {
      "id": "6a1144aa22bb33cc44dd5602",
      "name": "Spanish",
      "selected": false
    }
  ],
  "authorization": {
    "authorization_type": "VOD_PASSWORD_DISABLED"
  },
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED"
  },
  "cover_path": "",
  "logo_path": "",
  "useCustomLogo": "VOD_DISABLE_LOGO",
  "useCustomBackground": "VOD_DISABLE_BACKGROUND",
  "support_email": "[email protected]",
  "event_date": "2026-04-01T18:00:00.000Z",
  "timeZone": "Europe/Istanbul",
  "eventDateStatus": "EVENTS_DATE_DISABLED",
  "active": true,
  "created": "2026-03-24T18:00:00.000Z",
  "modified": "2026-03-24T18:00:00.000Z",
  "success": true
}
Back toWeb playersNext toVideo calls