Web player groups

Use a web player group when one viewer entry point needs to expose multiple browser players. In production, this is the control layer for multi-language events, alternate commentary, file-based variants, and branded event pages where access rules and presentation must stay consistent while the selected player changes.

A group does more than list players. It lets you set the default selection, apply group-level authorization, add optional pay-per-view rules, attach event metadata, and keep branding consistent across every option in the group. Update the group when the lineup or default feed changes without replacing the viewer-facing page.

For operator-driven events, the create, start, and stop flows fit cleanly into control-room automation. Use the API from your backend, or adapt the included vMix Script examples when grouped playback is managed from an operator console.

What this solves in production

  • Keep one embed or event page while viewers switch between approved feeds.
  • Apply one access policy, branding package, and event identity across multiple players.
  • Change the default player or available options without moving viewers to a new page.
  • Expose a controlled set of live feeds or file-based assets instead of separate standalone players.

Examples by preset

Common presets map to real operating needs:

  • Language selector: one event page with parallel language or commentary feeds.
  • File variant list: a branded page where viewers choose among pre-published assets, episodes, or replay versions.
  • Private event group: selected players behind a shared password or restricted access policy.
  • Pay-per-view event: a branded event page that combines grouped playback with purchase rules.

Workflow examples

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

Create a group when several players carry the same program in different languages. Set the primary feed as the default selection, attach the alternate feeds to the same group, and publish one embed so viewers can switch language without leaving the event page.

Use a group as a curated file playlist selector

Use a group when the page design and access policy should stay fixed while viewers choose among approved on-demand assets. This works well for episode lists, replay packages, and alternate cuts that must share one branded presentation.

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

Use the group as the policy boundary when the event needs viewer passwords, optional pay-per-view, support contact details, and event metadata in one place. The underlying players handle playback; the group controls how that playback is exposed to viewers.

Typical operator flow

  1. Create or identify the individual web players for each feed or asset.
  2. Create the group and attach the required players.
  3. Set the default selection and any access, branding, or event rules.
  4. Publish the group page or embed in your viewer experience.
  5. Use update, start, and stop operations to manage the event lifecycle.
Create web player group
Collapse
POST
/api/vod-group/create

Use this method when several players should go live as one viewer-facing experience with shared switching, branding, event framing, or access policy.

It is the standard setup step for multi-language, multi-angle, or commentary groups, especially when password or pay-per-view rules must apply across the whole group. If operators trigger publication from production tools, the preset examples below include matching vMix Script requests.

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

Use this with paginated group listings and housekeeping tools.

It reports how many web player groups are visible to the authenticated user before you fetch the page data.

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

Use this to populate admin lists and publishing dashboards for grouped playback.

It lists the web player groups visible to the current user 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

Use this when an operator opens one grouped viewer experience for review, policy checks, or editing.

It loads the full group definition, including linked players and any viewer users attached for 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

Use this to change player membership, branding, event framing, or viewer access rules on an existing group without rebuilding the public entry point.

The update contract mirrors create, so you can revise the grouped viewing policy while keeping the same group identity.

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

Use this to publish a prepared web player group at event start without changing the underlying player configurations.

It makes the grouped viewer experience and its configured access policy active, which is why it fits simple operator buttons or vMix Script control flows.

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

Use this to take the grouped viewer experience offline while keeping its player mapping and policy ready for later use.

It is the normal companion to start when an event ends or access must be paused without deleting the group.

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

Use this to withdraw a grouped viewer entry point when that combined playback experience should no longer be published.

Removal also clears linked per-group viewer users that were created for protected playback, so run it only when the group and its access policy are no longer needed.

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