Web player groups
Use Web player groups to give viewers one page for switching between approved language feeds, camera angles, or replay variants.
Membership and availability
All management methods require x-access-token. Create and test each web player before adding its identifier to a group. create and update define membership, default selection, access, branding, and event settings; start and stop control group availability.
Publish safely
Choose the primary player as the default, then test the access flow and every member before publishing the group URL or embed. A group depends on valid, playable members: stopping or removing one can leave an unavailable viewer option until the group is updated. remove deletes only the group, not its member players.
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.
Use this when several parallel web players represent language or commentary variants and one should be selected by default.
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
}'Use this when the grouped browser experience should switch between on-demand assets or prepared file-backed players.
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
}'Use this when the grouped playback should stay private behind a shared guest password.
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
}'Use this when a branded event page should wrap one or more players with PayPal-based access and event timing metadata.
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
}'Dashboard label: Group name.
Human-readable name of the grouped playback experience.
Dashboard label: Type.
Real product values include LANGUAGE_LIST and FILES_LIST.
List of linked player entries. Each item includes id, display name, and a selected flag used for the default choice.
Optional viewer authorization block. Real product modes include VOD_PASSWORD_DISABLED, VOD_USE_PASSWORD, and email-plus-password flows.
Optional pay-per-view block. The current dashboard exposes a PayPal-based mode in addition to the disabled default.
Optional branding fields for the grouped playback page.
Optional support contact shown alongside the event-style player experience.
Optional event timing metadata stored on the group.
Dashboard label: Enable once created.
Controls whether the group should be active right after provisioning.
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
}'Identifiers and the core group identity fields.
Stored player entries in the group, including default-selection state.
Authorization state plus any linked viewer users that belong to the group.
Stored pay-per-view configuration for the group.
Branding and event metadata returned with the group object.
Current running-state flag and backend-managed timestamps.
The model exposes success: true as a virtual field in successful responses.
{
"_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
}Workflow examples and help
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.