Web players
The Web players section covers the API endpoints used to provision and operate browser playback endpoints in Callaba Engine. This is the layer you use when one live source should become a managed web player, a browser-friendly HLS output, an embedded playback surface, or an access-controlled event page.
Compared with ingest-oriented modules, a web player is not the source boundary itself. It is the playback and viewer-facing layer built from input, HLS and DASH fragment settings, adaptive bitrate controls, optional authorization, optional pay-per-view, and optional group assignment.
The operational methods matter because a player is only useful when viewers can actually watch it. Teams use start and stop when a player should go live or come down on schedule, getAll and getCount to keep many players visible, getById for the full player object, and getStat when playback health needs to be checked during a live window.
This module matters both when a player is first published and when a live event is already underway. The practical questions are simple: where is the player URL, is it active, are viewers actually arriving, and does the live process still look healthy enough to trust.
If player activation is part of an operator workflow, the create, start, and stop examples below also include ready-to-adapt vMix Script tabs.
Live source signals
Many web players are still fed by a live SRT contribution on the input side. When playback quality looks wrong, teams usually want one fast answer first: is the incoming contribution still moving, is bitrate present, and is buffering still healthy before they blame the player layer itself.
The compact demo below reuses the same live SRT statistics stream used elsewhere in the docs. It is most helpful when a web player is fed from an SRT source and you want a quick upstream read alongside player process stats.
See live SRT stats as a moving chart
This demo shows the kind of live statistics you can watch during a real contribution: bitrate, buffer delay, packet flow, receive capacity, and active streams. It is connected to the public demo endpoint at demo.callaba.io and updates from the same live event stream used by the product.
Examples by preset
The most useful presets for this module are playback workflow shapes rather than transport families alone: expose one live source as one public player, protect the player behind authorization, group related players together, or prepare the player for adaptive bitrate playback.
SRT server to public web player
{
"vod_name": "Main stage player",
"vod_type": "VOD_TYPE_LIVE_STREAM",
"input": {
"input_type": "INPUT_TYPE_SRT_SOFTWARE",
"input_module_id": "SRT_SERVER_ID",
"input_stream_id": "",
"entity_name": "Main stage player",
"module_name": "MODULE_VOD"
},
"authorization": {
"authorization_type": "VOD_PASSWORD_DISABLED",
"credentials": []
},
"adaptive_bitrate_settings": {
"input_resolution": "MAX_RESOLUTION_UNSET"
},
"hls_fragment_size": 3,
"hls_fragment_length": 60,
"dash_fragment_size": 3,
"dash_fragment_length": 60,
"initial_live_manifest_size": 4,
"live_sync_duration_count": 5,
"pay_per_view_settings": {
"type": "PAY_PER_VIEW_DISABLED",
"client_id": ""
},
"active": true
}RTMP server to public web player
{
"vod_name": "RTMP browser player",
"vod_type": "VOD_TYPE_LIVE_STREAM",
"input": {
"input_type": "INPUT_TYPE_RTMP_SOFTWARE",
"input_module_id": "RTMP_SERVER_ID",
"input_stream_id": "",
"entity_name": "RTMP browser player",
"module_name": "MODULE_VOD"
},
"authorization": {
"authorization_type": "VOD_PASSWORD_DISABLED",
"credentials": []
},
"adaptive_bitrate_settings": {
"input_resolution": "MAX_RESOLUTION_UNSET"
},
"hls_fragment_size": 3,
"hls_fragment_length": 60,
"dash_fragment_size": 3,
"dash_fragment_length": 60,
"initial_live_manifest_size": 4,
"live_sync_duration_count": 5,
"pay_per_view_settings": {
"type": "PAY_PER_VIEW_DISABLED",
"client_id": ""
},
"active": true
}Password-protected web player
{
"vod_name": "Partner review player",
"vod_type": "VOD_TYPE_LIVE_STREAM",
"input": {
"input_type": "INPUT_TYPE_SRT_SOFTWARE",
"input_module_id": "SRT_SERVER_ID",
"input_stream_id": "",
"entity_name": "Partner review player",
"module_name": "MODULE_VOD"
},
"authorization": {
"authorization_type": "VOD_PASSWORD_ONLY_MANUALLY",
"credentials": [
{
"email": "[email protected]",
"password": "guest-password"
}
]
},
"adaptive_bitrate_settings": {
"input_resolution": "MAX_RESOLUTION_UNSET"
},
"hls_fragment_size": 3,
"hls_fragment_length": 60,
"dash_fragment_size": 3,
"dash_fragment_length": 60,
"initial_live_manifest_size": 4,
"live_sync_duration_count": 5,
"pay_per_view_settings": {
"type": "PAY_PER_VIEW_DISABLED",
"client_id": ""
},
"active": true
}Grouped variant player
{
"vod_name": "Main stage EN",
"vod_type": "VOD_TYPE_LIVE_STREAM",
"input": {
"input_type": "INPUT_TYPE_SRT_SOFTWARE",
"input_module_id": "SRT_SERVER_ID",
"input_stream_id": "",
"entity_name": "Main stage EN",
"module_name": "MODULE_VOD"
},
"authorization": {
"authorization_type": "VOD_PASSWORD_DISABLED",
"credentials": []
},
"adaptive_bitrate_settings": {
"input_resolution": "MAX_RESOLUTION_UNSET"
},
"hls_fragment_size": 3,
"hls_fragment_length": 60,
"dash_fragment_size": 3,
"dash_fragment_length": 60,
"initial_live_manifest_size": 4,
"live_sync_duration_count": 5,
"group_settings": {
"group_id": "VOD_GROUP_ID",
"name": "English",
"selected": true
},
"pay_per_view_settings": {
"type": "PAY_PER_VIEW_DISABLED",
"client_id": ""
},
"active": true
}Workflow examples
These scenarios frame why a web player exists in a production design, not only how the request body is shaped.
Use a web player when a live source should become a browser playback endpoint
Create a web player when the operational goal is not just to receive a stream, but to expose it as a viewer-facing browser experience with a stable player URL and a generated HLS output.
- Why it helps: one API object covers ingest hookup, playback packaging, and viewer-facing delivery settings.
- Typical fit: event pages, internal monitoring players, embedded live playback, and browser viewing for SRT or RTMP sources.
Use a web player when access control belongs in the playback layer
The web player module is also where playback access is shaped. That includes password-based access, optional pay-per-view settings, and player grouping for multi-variant or multi-language viewing experiences.
- Key controls:
authorization,group_settings, andpay_per_view_settings - Typical fit: partner review rooms, restricted event streams, grouped language feeds, and managed viewer onboarding.
Use a web player when delivery tuning matters as much as the source
The playback side is shaped by fragment size, playlist length, and adaptive bitrate settings, not only by the input source. That makes this module the right place to tune viewer experience rather than only ingest reliability.
- Key controls:
adaptive_bitrate_settings,hls_fragment_size,hls_fragment_length,initial_live_manifest_size, andlive_sync_duration_count - Operational fit: player startup tuning, buffering reduction, and ABR-oriented playback preparation.
Creates a new web player in Callaba Engine.
The backend exposes this method as POST /api/vod/create. The payload combines a live input definition with playback-specific controls such as HLS and DASH fragment settings, adaptive bitrate configuration, optional authorization, optional pay-per-view, optional group assignment, and optional presentation fields.
The create flow follows the same shape in the product UI. In practice, the request body is assembled from source settings, playback delivery settings, optional transcoding, optional audio or video modifications, optional overlay settings, and access-control choices.
In the dashboard, operators see this through labels such as Player name, Input type, Web player URL, HLS fragment size, and authorization controls for restricted playback.
Although the examples below focus on live playback, the same module also supports on-demand-style player types and group-driven viewer experiences.
Authentication uses the dashboard-issued JWT token in the x-access-token header.
Examples by preset
The examples below are grouped by playback presets rather than by one oversized payload. That makes them easier to reuse for real viewer-facing workflows.
Workflow-oriented use cases
Use a web player when a live source should become a browser playback endpoint with stable URLs, delivery settings, and viewer-facing access rules.
- Good fit for: public event pages, partner review players, embedded live playback, grouped language feeds, and browser-ready HLS delivery.
- Not the same as: an ingest boundary like
SRT serversor a processing pipeline likeRestreams.
Once a player is live, operators usually care about three things first: whether viewers can open the player, what viewer count the playback layer currently sees, and what live bitrate and FPS the process is reporting.
Use this preset when one managed SRT source should become one public browser playback endpoint with no access barrier.
This is the cleanest live-player setup for open browser viewing. The player layer handles packaging and playback while the source remains managed upstream.
This keeps the playback contract stable even if the ingest transport on the source side remains RTMP.
Use this preset when the player should exist, but not as a public page. The browser endpoint is still generated, but access is gated by player-side credentials.
This is a good fit for partner review, internal screenings, premium previews, or any case where access control belongs in the playback layer itself.
Use this preset when one player should join a group of related browser endpoints, for example different languages, programs, or alternate event views.
The grouped-player path is useful when the browser experience is bigger than one isolated URL and the viewer should move between related player variants.
Use this preset when the browser side should be prepared for adaptive bitrate playback rather than a single unscaled rendition.
The real product ties adaptive bitrate to playback tuning and transcoding. This makes it useful when startup stability and viewer-side quality adaptation matter more than one fixed rendition.
Dashboard label: Player name.
Human-readable playback endpoint name. The create form validates it as required.
Player type. The default live workflow uses VOD_TYPE_LIVE_STREAM, while the product also supports on-demand styles.
Optional media type descriptor stored on the player object.
Dashboard label: Input type.
Input definition built from the shared source form. Real product-facing inputs include SRT servers, RTMP servers, SRT routes, and URL-based live sources.
Adaptive bitrate settings for the player. The product uses input_resolution as the key delivery decision and ties ABR to the transcoding layer.
Dashboard label: HLS fragment size.
The UI guidance recommends 3 seconds for a good HLS experience.
Dashboard label: HLS fragment length.
The UI guidance recommends 60 seconds.
DASH-side fragment sizing controls stored with the player object.
Dashboard label: Minimal HLS fragment count.
Controls how many fragments are preloaded before playback begins.
Dashboard label: Edge of live delay.
Controls how far from the latest fragment playback should start for live viewing.
Player-side authorization settings. The UI uses this to require viewer authorization before the web player can be opened.
Optional group assignment block with group_id, per-group display name, and selected default state.
Optional monetization block. The disabled state remains the normal default for most players.
Optional presentation and branding settings for the browser-facing player experience.
Optional event and support metadata stored with the player object.
Optional media processing blocks used when the player should do more than simple pass-through packaging.
Dashboard label: Enable once created.
Controls whether the player should be active right after provisioning.
Mongo-style identifier of the web player.
Convenience alias for _id.
Name stored for the player object.
Player type and media-type fields stored on the object.
Generated internal port used by the player delivery runtime.
Linked input object or objects used by the playback pipeline.
Playback-delivery settings stored on the player object.
Access, monetization, group, and viewer-authorization state stored on the player.
Presentation and visibility settings returned with the player object.
Current running-state flag for the player.
Timestamps managed by the backend.
The model exposes success: true as a virtual field in successful responses.
Returns the current number of web players visible to the authenticated user.
This is the lightweight way to confirm how many player objects exist after provisioning or cleanup runs, without loading the full list.
Total number of web players currently visible to the authenticated user.
Returns the paginated list of web players.
In the dashboard, this listing is where operators scan the player name, current viewer count, current live bitrate, current FPS, and quick actions such as preview, edit, or remove.
The same row also exposes browser-facing delivery surfaces such as the web player URL, HLS URL, and embed code, even though those URLs are derived from the player object rather than returned as dedicated top-level API fields.
Optional page size for the list query.
Optional offset for paginated listing.
Optional sort descriptor. The dashboard store defaults to { created: 1 }.
Optional filter object forwarded to the backend query.
The backend returns a bare array of player objects, not a wrapped object.
Returns one populated web player object by id.
This is the best method to inspect the complete playback configuration, including the chosen input, authorization settings, adaptive bitrate controls, group assignment, and viewer-related settings stored on the player.
Identifier of the web player you want to load.
The backend returns the populated player object with linked input, access settings, and playback-delivery fields.
Updates an existing web player by id.
The update contract mirrors create. In practice, teams use it to swap the input source, change playback delivery settings, adjust access rules, tune ABR behavior, or move the player into or out of a group without recreating the whole playback endpoint.
Identifier of the web player being updated.
The update contract mirrors create and reuses the same validation plus runtime-regeneration path.
The backend returns the updated player object together with success: true.
Starts the selected web player.
For live players, this action restarts the delivery-side worker and the related HLS generation path. It is the operational counterpart to provisioning a player object and then taking it live when the event actually begins.
Identifier of the web player to start.
The backend marks the player as active and returns the updated player object.
Stops the selected web player.
This is useful when the player should remain provisioned but the active delivery process should be paused, for example between events, after a scheduled session ends, or during troubleshooting.
Identifier of the web player to stop.
The backend marks the player as inactive and returns the updated player object.
Deletes the selected web player and removes its related playback runtime assets.
In addition to removing the database object, the backend also tears down the generated playback side such as HLS output folders and runtime state.
Identifier of the web player to delete.
The backend removes the player and related runtime assets while returning the previously loaded player object.
Returns the current process statistics for active web players.
This is the playback-process counterpart to the dashboard's live labels. It exposes runtime values such as current bitrate, FPS, speed, and FFmpeg progress for active player workers.
Viewer count is related but separate: the product also tracks active viewers in memory for the playback layer, while getStat focuses on the running media process itself.
Current per-process statistics used by the dashboard polling layer.
Current FFmpeg-reported bitrate and a normalized integer bitrate_kbits field.
Current frames-per-second progress value when the runtime reports it.
Current worker speed, for example 1.00x.
FFmpeg progress status such as continue or end.
Viewer count is operationally important for players, but it is tracked separately from getStat in the playback layer runtime.