Web player groups

Use Web player groups to give viewers one page for switching between approved language feeds, camera angles, or replay variants.

What it doesLet viewers switch between feeds

Choose this whenSeveral existing players need one viewer page for language, angle, or replay switching.

Use another module whenUse Web Players to create and verify each underlying playback endpoint first.

1Choose the players2Set shared access3Publish one page

POST /api/vod-group/create

Filter endpoints8 endpoints

Before you start

All management methods require a valid x-access-token. Create and test the individual web players before adding their identifiers to a group.

What you can do

create and update define membership, default selection, access, branding, and event settings.
getAll, getCount, and getById inspect groups.
start and stop control group availability.
remove deletes the group but leaves its member web players intact.

Example workflow

Create and validate one web player for each language feed.
Create a group containing those player identifiers.
Select the primary language as the default.
Apply the shared access and event settings.
Start the group and publish its viewer URL or embed.

Common use cases

Offer parallel language or commentary feeds on one event page.
Publish a curated set of replay or episode variants.
Apply one restricted or pay-per-view policy to several players.

Limits and troubleshooting

A group depends on valid, playable member resources. Removing or stopping a member can leave an unavailable option in the group until it is updated. Test the default selection, access flow, and every member before publishing.

Next steps

Open Web players to prepare each source, then embed or link the tested group in the viewer experience.

REST solution recipe

Create a pay-per-view event experience

Prepare the player or players first, group the approved feeds under one viewer page, and apply the pay-per-view and access settings on that group.

Create the event playerPrepare each live or recorded feed that viewers may purchase.POST /api/vod/create
Create the paid groupAttach the player entries and configure pay_per_view_settings, access, branding, and event metadata.POST /api/vod-group/create
Open the viewer experienceStart the group only after purchase and playback checks pass.POST /api/vod-group/start

A payment configuration is not a completed commerce test. Validate purchase, authorization, support contact, and playback with a test customer before the event.

See the pay-per-view product

POST

/api/vod-group/create

API token required

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
}

POST

/api/vod-group/getCount

API token required

POST

/api/vod-group/getAll

API token required

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

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": "support@example.com",
    "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
  }
]

[
  {
    "_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
  }
]

POST

/api/vod-group/getById

API token required

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

string

Identifier of the web player group you want to load.

Get web player group by 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
}

POST

/api/vod-group/update

API token required

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

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
}

POST

/api/vod-group/start

API token required

Use this to publish a prepared web player group at event start without changing its 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

string

Identifier of the web player group to start.

Start web player group

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
}

POST

/api/vod-group/stop

API token required

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

string

Identifier of the web player group to stop.

Stop web player group

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
}

DELETE

/api/vod-group/remove

API token required

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

string

Identifier of the web player group to delete.

Remove web player group

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 players Next toVideo calls