网页播放器
网页播放器 是 Callaba Engine 中面向浏览器观看的交付与播放控制层。你可以用这个 API 从已有的直播 input 创建观众侧端点，发布浏览器可用的 HLS 或 DASH 输出，配置嵌入与访问设置，并控制播放器何时可用。
职责要分清：接入 API 负责源侧可靠性和传输连续性，而网页播放器负责观众体验调优和播放操作。在这个模块中，你需要指定源信号、调整打包与自适应码率行为，按需启用鉴权或按次付费，并通过 start、stop 和 getStat 之类的方法来运营直播交付。
直播播放演练场
这个模块最好同时把两种交付表面放在一起看：一种是对公共 HLS manifest 的直连浏览器播放，另一种是托管的 Callaba 播放器 iframe 嵌入。下面的演练场把两者放到一起，同时给出观众侧实时统计，方便你看到播放层实际上在做什么。
当问题是观众体验时，先看播放器本身；当问题是播放进程上游是否仍有可信的码率与画面节奏时，再看 getStat。
运行时播放信号
对于网页播放器，getStat 首先回答的是源侧问题：播放进程当前是否仍在收到具有可信码率和画面节奏的媒体。这是最直接的运营检查，能帮助你在责怪嵌入逻辑、品牌样式、访问控制或浏览器之前，先确认上游是不是还健康。
下面的预览镜像了 getStat 文档中同样的运行时字段。当播放质量看起来不对时，用它快速确认播放器进程上游是否仍有健康的输入可供打包。
Preview the runtime shape behind a live web player
For web players, getStat answers both sides of the first operational question: is the player process still receiving believable source media, and are viewers actually connected right now. Together these fields tell you whether playback still has a healthy upstream signal and whether the audience is actively watching.
bitrate_kbits
Previewing the same runtime signal operators usually inspect first.
4,700 kbits/s
This is the source-side signal the player process still has something healthy to package.
30.0
The fastest way to tell whether playback quality issues already started before the viewer layer.
8
Current connected audience reported by the same getStat response used for the live player process.
continue
3:00 packaged · 1.00x worker speed
Use this runtime check before you blame the viewer layer. If bitrate and cadence already look wrong here, the issue is usually upstream of branding, access control, or embed logic.
按预设理解示例
这个模块最有价值的预设，不是只按传输协议来分，而是按播放工作流形态来分：把一个直播源暴露为一个公共播放器、在鉴权后保护播放器、把相关播放器组合在一起，或者把播放器准备成自适应码率播放。
SRT server 到公共网页播放器
{
"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 到公共网页播放器
{
"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
}带密码保护的网页播放器
{
"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
}分组变体播放器
{
"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
}工作流示例
这些场景强调的不是请求体怎么写，而是网页播放器为什么会出现在你的生产设计里。
当直播源需要变成浏览器播放端点时，使用网页播放器
当你的目标不只是接收一条流，而是把它暴露成一个面向观众的浏览器体验，并拥有稳定的播放器 URL 与生成的 HLS 输出时，就应创建一个网页播放器。
- 价值所在：一个 API 对象就覆盖了接入挂接、播放打包和观众侧交付设置。
- 典型场景：活动页面、内部监看播放器、嵌入式直播播放，以及面向 SRT 或 RTMP 来源的浏览器观看。
当访问控制属于播放层时，使用网页播放器
网页播放器模块也是控制播放访问的地方，包括密码访问、按次付费，以及针对多变体或多语言观看体验的播放器分组。
- 关键控制：
authorization、group_settings和pay_per_view_settings - 典型场景：合作方审核房间、受限活动直播、分语言分组播放，以及托管式观众引导。
当交付调优和源本身同样重要时，使用网页播放器
播放侧体验由分片大小、播放列表长度和自适应码率设置决定，而不仅仅是输入源本身。这意味着当你要调的是观众体验，而不只是接入可靠性时，这个模块才是正确的位置。
- 关键控制：
adaptive_bitrate_settings、hls_fragment_size、hls_fragment_length、initial_live_manifest_size和live_sync_duration_count - 运营适配：播放器启动调优、缓冲降低，以及面向 ABR 的播放准备。
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.
Current connected viewer count returned by getStat for the player process.