media server logo
PricingSign inLaunch web player
API docsOverview
Recordings
Files
Web players
Web player groups
Toggle documentation navigation
Callaba home

Web players

Use Web players to publish live or recorded media for browser playback with access control, adaptive delivery, embeds, and viewer-facing URLs.

What it doesCreate browser playback

Choose this whenOne live or recorded source needs an HLS or DASH viewer URL or embed with access control or pay-per-view.

Use another module whenUse Multiview for operators; use Web Player Groups when viewers need several existing players.

1Select a stream2Create a player3Embed playback
POST /api/vod/create
9 endpoints

Before you start

All management methods require a valid x-access-token. Prepare the input resource first and decide whether playback is open, password-protected, grouped, or connected to pay-per-view.

What you can do

  • create and update configure input, playback type, packaging, adaptive bitrate, access, grouping, and pay-per-view settings.
  • getAll, getCount, and getById inspect players.
  • start and stop control playback availability.
  • getStat reports available input bitrate and cadence for the player process.
  • remove deletes a player.

Example workflow

  1. Create a player from an SRT server, RTMP server, or supported media input.
  2. Choose HLS or DASH playback and tune segment duration and adaptive bitrate for the required latency and resilience.
  3. Apply open, password, group, or pay-per-view access settings.
  4. Start the player and check getStat before testing the viewer URL.
  5. Validate playback and the embed in representative browsers and networks.

Common use cases

  • Publish an SRT or RTMP contribution as embedded live playback.
  • Protect a partner review stream with viewer credentials.
  • Deliver a paid event through configured pay-per-view access.
  • Create language variants that belong to one web player group.

Limits and troubleshooting

A healthy page does not prove that the upstream media process is healthy; check getStat. Smaller fragments can reduce latency but increase request overhead and sensitivity to network variation. Test authorization, payment, embed policy, codecs, and adaptive variants before publishing.

Next steps

Open the player in a browser, verify access and playback, then use Web player groups when viewers need several selectable feeds.

REST solution recipe

Publish a managed file for browser playback

Prepare the media file, create a web player from the matching file input preset, and validate the generated HLS or DASH playback.

  1. Upload the sourceCreate the managed file record and keep its id for the player input.POST /api/files/uploadFile
  2. Create VOD playbackChoose the file input preset, delivery format, access policy, and presentation settings.POST /api/vod/create
  3. Start and test the playerStart the resource and test its viewer URL in representative browsers.POST /api/vod/start

The player is a delivery resource; keep the source file managed separately and verify authorization, codecs, and browser playback before publishing its URL.

See the Video on Demand product
POST
/api/vod/create
API token required

Create a web player through POST /api/vod/create. Send the dashboard-issued JWT in the x-access-token header.

The request combines a live input with HLS or DASH delivery settings, optional adaptive bitrate, transcoding, overlays, viewer authorization, pay-per-view, group assignment, and presentation fields.

Request examples

Choose the preset that matches the desired playback and access policy, then add only the optional fields that the viewer experience requires.

Common use cases

  • Publish a public event stream as browser-ready HLS playback.
  • Embed a restricted review player with password or viewer authorization.
  • Prepare language, angle, or commentary players for a grouped viewing experience.

After starting a live player, use its playback URL and monitor viewer count, bitrate, and FPS.

Public playback

Use this preset when one managed SRT source should become one public browser playback endpoint with no access barrier.

SRT server to public web player

This is the cleanest live-player setup for open browser viewing. The player layer handles packaging and playback while the source remains managed upstream.

SRT server to public web player
Copy code
curl --request POST \
  --url http://localhost/api/vod/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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": ""
  },
  "support_email": "",
  "transcoding": {
    "video_transcoding": "Disabled",
    "output_video_bitrate": 6000,
    "preset": "ultrafast",
    "tune": "Disabled",
    "crf": "Disabled",
    "pix_fmt": "Disabled",
    "encoding_rate": "",
    "filter_fps": "",
    "gop": "Disabled",
    "force_key_frames": 2,
    "frame_width": "",
    "frame_height": "",
    "slices": "",
    "cores": "",
    "xlnx_hwdev": "0",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "modify_audio": {
    "type": "DISABLED",
    "channel": "1,2",
    "track": "0"
  },
  "modify_video": {
    "type": "DISABLED"
  },
  "overlay": {
    "type": "DISABLED",
    "position": {
      "x": 1,
      "y": 1
    }
  },
  "active": true
}'
RTMP server to public web player

This keeps the playback contract stable even if the ingest transport on the source side remains RTMP.

RTMP server to public web player
Copy code
curl --request POST \
  --url http://localhost/api/vod/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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": ""
  },
  "support_email": "",
  "transcoding": {
    "video_transcoding": "Disabled",
    "output_video_bitrate": 6000,
    "preset": "ultrafast",
    "tune": "Disabled",
    "crf": "Disabled",
    "pix_fmt": "Disabled",
    "encoding_rate": "",
    "filter_fps": "",
    "gop": "Disabled",
    "force_key_frames": 2,
    "frame_width": "",
    "frame_height": "",
    "slices": "",
    "cores": "",
    "xlnx_hwdev": "0",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "modify_audio": {
    "type": "DISABLED",
    "channel": "1,2",
    "track": "0"
  },
  "modify_video": {
    "type": "DISABLED"
  },
  "overlay": {
    "type": "DISABLED",
    "position": {
      "x": 1,
      "y": 1
    }
  },
  "active": true
}'
Restricted playback

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.

Password-protected web player

This is a good fit for partner review, internal screenings, premium previews, or any case where access control belongs in the playback layer itself.

Password-protected web player
Copy code
curl --request POST \
  --url http://localhost/api/vod/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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": ""
  },
  "support_email": "",
  "transcoding": {
    "video_transcoding": "Disabled",
    "output_video_bitrate": 6000,
    "preset": "ultrafast",
    "tune": "Disabled",
    "crf": "Disabled",
    "pix_fmt": "Disabled",
    "encoding_rate": "",
    "filter_fps": "",
    "gop": "Disabled",
    "force_key_frames": 2,
    "frame_width": "",
    "frame_height": "",
    "slices": "",
    "cores": "",
    "xlnx_hwdev": "0",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "modify_audio": {
    "type": "DISABLED",
    "channel": "1,2",
    "track": "0"
  },
  "modify_video": {
    "type": "DISABLED"
  },
  "overlay": {
    "type": "DISABLED",
    "position": {
      "x": 1,
      "y": 1
    }
  },
  "active": true
}'
Grouped playback

Use this preset when one player should join a group of related browser endpoints, for example different languages, programs, or alternate event views.

Grouped variant player

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.

Grouped variant player
Copy code
curl --request POST \
  --url http://localhost/api/vod/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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,
  "pay_per_view_settings": {
    "type": "PAY_PER_VIEW_DISABLED",
    "client_id": ""
  },
  "support_email": "",
  "transcoding": {
    "video_transcoding": "Disabled",
    "output_video_bitrate": 6000,
    "preset": "ultrafast",
    "tune": "Disabled",
    "crf": "Disabled",
    "pix_fmt": "Disabled",
    "encoding_rate": "",
    "filter_fps": "",
    "gop": "Disabled",
    "force_key_frames": 2,
    "frame_width": "",
    "frame_height": "",
    "slices": "",
    "cores": "",
    "xlnx_hwdev": "0",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "modify_audio": {
    "type": "DISABLED",
    "channel": "1,2",
    "track": "0"
  },
  "modify_video": {
    "type": "DISABLED"
  },
  "overlay": {
    "type": "DISABLED",
    "position": {
      "x": 1,
      "y": 1
    }
  },
  "active": true,
  "group_settings": {
    "group_id": "VOD_GROUP_ID",
    "name": "English",
    "selected": true
  }
}'
Delivery tuning

Use this preset when the browser side should be prepared for adaptive bitrate playback rather than a single unscaled rendition.

ABR-ready web player

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.

ABR-ready web player
Copy code
curl --request POST \
  --url http://localhost/api/vod/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "vod_name": "ABR 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": "1080"
  },
  "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": ""
  },
  "support_email": "",
  "transcoding": {
    "video_transcoding": "libx264",
    "output_video_bitrate": 6000,
    "preset": "ultrafast",
    "tune": "Disabled",
    "crf": "Disabled",
    "pix_fmt": "Disabled",
    "encoding_rate": "",
    "filter_fps": "",
    "gop": "Disabled",
    "force_key_frames": 2,
    "frame_width": "",
    "frame_height": "",
    "slices": "",
    "cores": "",
    "xlnx_hwdev": "0",
    "audio_transcoding": "aac",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "modify_audio": {
    "type": "DISABLED",
    "channel": "1,2",
    "track": "0"
  },
  "modify_video": {
    "type": "DISABLED"
  },
  "overlay": {
    "type": "DISABLED",
    "position": {
      "x": 1,
      "y": 1
    }
  },
  "active": true
}'
Request body parameters
Identity
vod_name
string
Copy direct link

Dashboard label: Player name.

Human-readable playback endpoint name. The create form validates it as required.

vod_type
string
Copy direct link

Player type. The default live workflow uses VOD_TYPE_LIVE_STREAM, while the product also supports on-demand styles.

vod_media_type
string
Copy direct link

Optional media type descriptor stored on the player object.

Input
input
object
Copy direct link

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.

Playback delivery
adaptive_bitrate_settings
object
Copy direct link

Adaptive bitrate settings for the player. The product uses input_resolution as the key delivery decision and ties ABR to the transcoding layer.

hls_fragment_size
integer
Copy direct link

Dashboard label: HLS fragment size.

The UI guidance recommends 3 seconds for a good HLS experience.

hls_fragment_length
integer
Copy direct link

Dashboard label: HLS fragment length.

The UI guidance recommends 60 seconds.

dash_fragment_size / dash_fragment_length
mixed
Copy direct link

DASH-side fragment sizing controls stored with the player object.

initial_live_manifest_size
integer
Copy direct link

Dashboard label: Minimal HLS fragment count.

Controls how many fragments are preloaded before playback begins.

live_sync_duration_count
integer
Copy direct link

Dashboard label: Edge of live delay.

Controls how far from the latest fragment playback should start for live viewing.

Access and grouping
authorization
object
Copy direct link

Player-side authorization settings. The UI uses this to require viewer authorization before the web player can be opened.

group_settings
object
Copy direct link

Optional group assignment block with group_id, per-group display name, and selected default state.

pay_per_view_settings
object
Copy direct link

Optional monetization block. The disabled state remains the normal default for most players.

Presentation
cover_path / logo_path / useCustomLogo / useCustomBackground
mixed
Copy direct link

Optional presentation and branding settings for the browser-facing player experience.

event_date / timeZone / eventDateStatus / support_email
mixed
Copy direct link

Optional event and support metadata stored with the player object.

Processing
transcoding / modify_audio / modify_video / overlay
object
Copy direct link

Optional media processing blocks used when the player should do more than simple pass-through packaging.

Runtime
active
boolean
Copy direct link

Dashboard label: Enable once created.

Controls whether the player should be active right after provisioning.

Create web player
Copy code
curl --request POST \
  --url http://localhost/api/vod/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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": ""
  },
  "support_email": "",
  "transcoding": {
    "video_transcoding": "Disabled",
    "output_video_bitrate": 6000,
    "preset": "ultrafast",
    "tune": "Disabled",
    "crf": "Disabled",
    "pix_fmt": "Disabled",
    "encoding_rate": "",
    "filter_fps": "",
    "gop": "Disabled",
    "force_key_frames": 2,
    "frame_width": "",
    "frame_height": "",
    "slices": "",
    "cores": "",
    "xlnx_hwdev": "0",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "modify_audio": {
    "type": "DISABLED",
    "channel": "1,2",
    "track": "0"
  },
  "modify_video": {
    "type": "DISABLED"
  },
  "overlay": {
    "type": "DISABLED",
    "position": {
      "x": 1,
      "y": 1
    }
  },
  "active": true
}'
Response
Identity
_id
string
Copy direct link

Resource id returned when you create or list the web player.

id
string
Copy direct link

Convenience alias for _id.

vod_name
string
Copy direct link

Name stored for the player object.

vod_type / vod_media_type
mixed
Copy direct link

Player type and media-type fields stored on the object.

Playback delivery
vod_port
integer
Copy direct link

Generated internal port used by the player delivery runtime.

Input
input[]
array
Copy direct link

Linked input object or objects used by the playback pipeline.

Playback delivery
adaptive_bitrate_settings / hls_fragment_* / dash_fragment_*
mixed
Copy direct link

Playback-delivery settings stored on the player object.

Access and grouping
authorization / pay_per_view_settings / group_id / users
mixed
Copy direct link

Access, monetization, group, and viewer-authorization state stored on the player.

Presentation
hidden / support_email / logo / background fields
mixed
Copy direct link

Presentation and visibility settings returned with the player object.

Runtime
active
boolean
Copy direct link

Current running-state flag for the player.

created / modified
string
Copy direct link

Timestamps managed by the backend.

Operation result
success
boolean
Copy direct link

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

Response: Create web player
JSON
Copy code
{
  "_id": "66015d2997300f9385d32c00",
  "id": "66015d2997300f9385d32c00",
  "vod_name": "Main stage player",
  "vod_type": "VOD_TYPE_LIVE_STREAM",
  "vod_media_type": "video",
  "vod_port": 20840,
  "input": [
    {
      "_id": "66015d2997300f9385d32c01",
      "id": "66015d2997300f9385d32c01",
      "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": ""
  },
  "group_id": null,
  "users": [],
  "hidden": false,
  "support_email": "",
  "transcoding": {
    "video_transcoding": "Disabled",
    "output_video_bitrate": 6000,
    "preset": "ultrafast",
    "tune": "Disabled",
    "crf": "Disabled",
    "pix_fmt": "Disabled",
    "encoding_rate": "",
    "filter_fps": "",
    "gop": "Disabled",
    "force_key_frames": 2,
    "frame_width": "",
    "frame_height": "",
    "slices": "",
    "cores": "",
    "xlnx_hwdev": "0",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "modify_audio": {
    "type": "DISABLED",
    "channel": "1,2",
    "track": "0"
  },
  "modify_video": {
    "type": "DISABLED"
  },
  "overlay": {
    "type": "DISABLED",
    "position": {
      "x": 1,
      "y": 1
    }
  },
  "active": true,
  "created": "2026-03-24T14:00:00.000Z",
  "modified": "2026-03-24T14:00:00.000Z",
  "success": true
}
POST
/api/vod/getCount
API token required
POST
/api/vod/getAll
API token required
POST
/api/vod/getById
API token required
POST
/api/vod/update
API token required
POST
/api/vod/start
API token required
POST
/api/vod/stop
API token required
DELETE
/api/vod/remove
API token required
POST
/api/vod/getStat
API token required
Back toFilesNext toWeb player groups