Sardius Player Settings — SCP Reference
Complete reference for the SCP Player Editor (Players → select player). Covers all five tabs — Features, Advertising, Appearance, Security, and History — plus header actions. Field names match the exact English labels shown in SCP.
Search by SCP UI label, form variable, control bar ID, or JSON path · Click any field row for a detailed explanation
No matching fields. Try a different SCP label, form variable, or JSON path.
Overview
The Player Editor saves settings to the Dynamo player record when you click Save on PlayerInfo. Most fields use react-hook-form; Advertising modal fields use separate sardiusAdSettings state merged on save.
Player type naming in SCP: Form value
sardius → UI label Legacy Player (Video.js). Form value bitmovin → UI label Sardius Player (Bitmovin). Persisted as setup.playerType.
| Player type (UI) | Form value | JSON path | Runtime engine |
|---|---|---|---|
| Legacy Player | sardius |
setup.playerType |
Video.js + Sardius plugins |
| Sardius Player | bitmovin |
setup.playerType |
Bitmovin player (api-players loader) |
| Tab (UI) | What it configures | Saved on player record? |
|---|---|---|
| Features | Name, player type, playback toggles | Yes |
| Advertising | Pre/post-roll MP4 ads, smart ad frequency | Yes (plugins.sardiusAds) |
| Appearance | Scrub color, control bar on/off, icon order | Yes |
| Security | Secure stream geo rules, auth key | Yes |
| History | Created/edited metadata | Read-only |
Notion status: The older Technical Documentation page (Aug 2025) is outdated for ads.
The newer Player Ads page (May 2026) matches
api-players/docs/ads.md.
All Player Editor tabs
Navigation: Players → select player → tab bar in PlayerInfo.
| Tab order | SCP tab name | Section anchor | Primary JSON paths |
|---|---|---|---|
| 1 | Features | #features | title, setup.playerType, autoplay, muted, loop, theme.id |
| 2 | Advertising | #pre-post | plugins.sardiusAds |
| 3 | Appearance | #appearance-settings | theme.styles.primaryColor, background, setup.controlBar.children |
| 4 | Security | #security | securedUrls, securedData, authKey |
| 5 | History | #history | createdAt, updatedAt (display only) |
Features tab
Click a row to expand details.
File: sardius-control-panel/.../tabs/Features/Features.tsx
| SCP field name (UI) | Form variable | JSON path | Effect on player | Player type notes |
|---|---|---|---|---|
| Player Name | title |
title |
Display name in SCP and embed contexts | Both |
| Player type | playerType |
setup.playerType |
Selects Legacy (Video.js) vs Bitmovin engine | Switching to Bitmovin sanitizes control bar icons in UI |
| Show Scrub Bar | scrubBar |
theme.id (default on, noScrubBar off) |
Shows or hides progress/scrub bar | Both; Bitmovin may also hide playback speed when off |
| Autoplay | autoPlay |
autoplay |
Starts playback automatically on load | Both |
| Mute player on Start | mutePlayerOnStart |
muted |
Starts with audio muted | Both |
| Loop Video | loopVideo |
loop |
Restarts video when it ends | Both |
| iOS Native on Fullscreen | iosNativeOnFullscreen |
nativeiOSFullscreen |
Uses native Apple fullscreen player instead of in-page fullscreen | Both |
Appearance tab
File: sardius-control-panel/.../tabs/Appearance/Appearance.tsx
| SCP field name (UI) | Form variable | JSON path | Effect on player | Player type notes |
|---|---|---|---|---|
| Scrub Bar Color | scrubColor |
theme.styles.primaryColor |
Primary/accent color for scrub bar and player chrome | Both; theme.styles reset to only primaryColor on each save |
| Control Bar Icons (toggle) | controls |
background (inverted: on → false, off → true) |
On: normal player with control bar. Off: background player (no chrome, embed-only) | Both; background mode strips ads at parse time (Legacy) |
| Displayed Icons / Hidden Icons | controlBarIcons (mainSection / otherSection) |
setup.controlBar.children[] |
Which control bar buttons appear and their order | See Control bar icons for per-icon details |
SortableBoard columns: Left column = Displayed Icons (
mainSection). Right column = Hidden Icons (otherSection). Only shown when Control Bar Icons toggle is on.
Bitmovin hint text: First three reorderable icons appear left of spacer; rest align right. Time, scrub bar, subtitles, and playback speed are not re-orderable in UI but preserved on save.
Advertising — quick answers
What affects pre-roll?
- Pre-Roll Ads URL list
- Modal settings under pre-roll (Amount, Skip, Countdown, break text)
- Frequency of Ad (pre-roll smart ads only)
- Account Pre-Roll MP4 URL (merged at parse time)
What affects post-roll?
- Post-Roll Ads URL list
- Modal settings under post-roll (Amount, Skip, Countdown, break text)
Post-roll does not use Frequency of Ad or Amount of Ads.
What does NOT control ad count?
Amount of Ads (top-level) only unlocks the Frequency dropdown in SCP. Multi-ad playback uses modal Amount per break.
Control bar icons — Quality menu vs standalone
Important: A newer UI design shows Left side / Right side / Hidden columns with an expandable Quality menu and per-item toggles (video quality, playback speed, subtitles, languages). That layout is not in the current SCP codebase — what ships today uses Displayed Icons / Hidden Icons with a flat drag list.
All control bar icon IDs
Labels from SCP Appearance SortableBoard. Bitmovin fixed icons are hidden from drag UI but preserved on save.
| SCP field name (UI) | Control bar ID | In reorder UI? | JSON path | Player type notes |
|---|---|---|---|---|
| Play | playToggle |
Yes | setup.controlBar.children |
Both |
| Skip Back | LiveToggle |
Yes | setup.controlBar.children |
Both |
| Volume | volumePanel |
Yes | setup.controlBar.children |
Both |
| Airplay | airplay |
Yes | setup.controlBar.children |
Both |
| Casting | chromecast |
Yes | setup.controlBar.children |
Both |
| Picture In Picture | settingsMenu |
Yes | setup.controlBar.children |
Bitmovin-supported; Legacy save appends settingsMenu separately |
| Quality (Legacy) / Settings Menu (Bitmovin) | settingsMenuLegacy |
Yes | setup.controlBar.children |
Label differs by player type; opens settings/quality overlay |
| Full Screen | FullscreenToggle |
Yes | setup.controlBar.children |
Both |
| Time | currentTimeDisplay |
No (Bitmovin fixed) | setup.controlBar.children |
Preserved from prior record on Bitmovin save |
| Scrub bar | progressControl |
No (Bitmovin fixed) | setup.controlBar.children |
Same as Time |
| Subtitles | closedCaptions |
No (Bitmovin fixed) | setup.controlBar.children |
Standalone button independent of settings menu |
| Playback Speed | playbackRateMenuButton |
No (Bitmovin fixed) | setup.controlBar.children |
Hidden globally on live/no-scrub via api-players |
Save behavior for control bar
| Player type | setup.controlBar.children on save |
|---|---|
Legacy (sardius) | [...mainSection icons, 'settingsMenu'] |
| Bitmovin | [...fixed icons from prior record, ...mainSection icons] |
Current shipped behavior — Bitmovin player
| SCP field name | Code ID | Where it lives |
|---|---|---|
| Settings Menu (gear / quality menu) | settingsMenuLegacy |
Control bar — opens Bitmovin native settings overlay |
| Subtitles | closedCaptions |
Control bar button (fixed — not draggable in SCP UI) |
| Playback Speed | playbackRateMenuButton |
Control bar button (fixed — not draggable in SCP UI) |
Inside the gear menu, Bitmovin natively shows video quality, playback speed, subtitles, and languages.
SCP does not expose per-item toggles for those today.
Subtitles and playback speed on the control bar are always preserved on save (BITMOVIN_FIXED_ICONS in PlayerInfo.tsx).
Playback speed can be hidden globally (menu + bar) on live streams, no-scrub theme, or when setup.hidePlaybackSpeed is set via applyHidePlaybackRatesUiConfig.html.
Current shipped behavior — Legacy (VideoJS) player
Two separate systems control menu vs bar content:
| System | JSON path | What it controls | Edited in SCP Appearance tab? |
|---|---|---|---|
| Control bar children | setup.controlBar.children |
Standalone buttons (Subtitles, Playback speed, etc.) | Yes |
| Settings popup menu | plugins.spMenuBar.items |
Items inside the gear/quality popup (video quality, languages, audio, subtitles) | No |
Answer for Legacy today: Yes — standalone Subtitles and Playback speed are independent from the settings popup. Hide standalone subtitles by moving Subtitles to Hidden. Popup content comes from
spMenuBar defaults, not from nested toggles.
When the new UI ships (design preview)
The design shows both nested toggles under Quality menu and standalone Subtitles / 1X on the right column. Unless implementation explicitly couples them, expected behavior is:
- Toggle off inside Quality menu → hidden inside the gear menu only
- Standalone items on Right side → controlled separately by column placement
Verify coupling behavior when the new UI is merged — it is not defined in code yet.
Advertising tab
File: sardius-control-panel/.../tabs/Advertising/Advertising.tsx
Pre-roll vs post-roll settings
Pre-roll only
- Pre-Roll Ads URL list →
plugins.sardiusAds.preroll.urls - Amount (modal)
- Skip Ad Button
- Countdown Timer
- Custom text before Ad
- Custom text after Ad
- Frequency of Ad →
frequencyEach(smart ads via localStorage)
Post-roll only
- Post-Roll Ads URL list →
plugins.sardiusAds.postroll.urls - Amount (modal)
- Skip Ad Button
- Countdown Timer
- Custom text before Ad
- Custom text after Ad
Global (misleading placement)
- Amount of Ads →
plugins.sardiusAds.amount
Gates Frequency UI only — not ad count - Frequency of Ad →
plugins.sardiusAds.frequencyEach
Pre-roll smart ads only
These render below both Pre-roll and Post-roll sections but apply to pre-roll only.
Do not confuse: Modal Amount (
preroll.amount / postroll.amount) controls multi-ad sequencing for that break.
Top-level Amount of Ads (plugins.sardiusAds.amount) does not control how many ads play.
Advertising — master field mapping
SCP field name (UI) → form variable → persisted JSON path.
Advertising tab
| SCP field name (UI) | Form variable | JSON path | Scope |
|---|---|---|---|
| (Pre-Roll URL list) | sardiusAdSettings.preroll.urls |
plugins.sardiusAds.preroll.urls |
Pre-roll |
| (Post-Roll URL list) | sardiusAdSettings.postroll.urls |
plugins.sardiusAds.postroll.urls |
Post-roll |
| Amount of Ads | adAmount |
plugins.sardiusAds.amount |
Global |
| Frequency of Ad | adFrequency |
plugins.sardiusAds.frequencyEach |
Pre-roll |
Account → General Settings (not on Advertising tab)
| SCP field name | Form variable | JSON path | Effect |
|---|---|---|---|
| Pre-Roll MP4 URL | preRollUrls |
account.preRollUrls[] |
Merged into every player's preroll.urls at parse time |
Frequency of Ad — dropdown values
| Option label | Seconds (frequencyEach) |
|---|---|
| Once every hour | 3600 |
| Once every 6 hour | 21600 |
| Once every 12 hour | 43200 |
| Once a day | 86400 |
| Once every 2 days | 172800 |
Frequency dropdown visible only when Amount of Ads = 1. Select is clearable — cleared value omits frequencyEach.
Add Asset modal fields
Opened from Add an asset or Edit Advanced Settings on either pre-roll or post-roll section.
| SCP field name | Form variable | JSON path | Default |
|---|---|---|---|
| (URL list in modal) | urlsList |
*.urls |
From player |
| Amount | amount |
*.amount |
1 |
| Skip Ad Button | skip |
*.skippable |
false |
| Countdown Timer | countDown |
*.showCountdown |
true |
| Custom text before Ad | customTextBefore |
*.beforeBreakText |
'' |
| Custom text after Ad | customTextAfter |
*.afterBreakText |
'' |
Modal save writes one object to sardiusAdSettings.preroll or .postroll. Global fields merge on main PlayerInfo Save, not when the modal closes.
Runtime behavior by field
URL lists
| Break | Legacy (Video.js) | Bitmovin |
|---|---|---|
| Pre-roll | Plays before main via contrib-ads readyforpreroll |
Initial player.load() source may be first preroll URL |
| Post-roll | Plays after main via readyforpostroll |
After main playbackfinished, loads postroll URLs |
Modal Amount (multi-ad sequencing)
| Value | Legacy | Bitmovin |
|---|---|---|
1 (default) |
Random pick from URL pool; records URL in localStorage history | First URL in filtered list (after history) — not random |
> 1 |
Plays up to min(amount, urls.length) ads in list order |
Same — sequential index through URL list |
Countdown Timer defaults if unset in old records
| Player | Runtime default |
|---|---|
| Legacy | Countdown on (!== false) |
| Bitmovin | Countdown off (?? false) |
Custom break text
SCP saves per-break text on
preroll / postroll, but the Video.js plugin reads top-level beforeBreakText / afterBreakText only. Custom break text from SCP is likely broken on Legacy. Bitmovin does not implement break text overlays at all.
Frequency of Ad (pre-roll smart ads)
Uses browser localStorage key: {accountId}_{assetId}_break_history (JSON array of { url, ts }).
| Player | When applied |
|---|---|
| Legacy | Only if frequencyEach is truthy |
| Bitmovin | History filter runs if stored history exists; age filter only if frequencyEach > 0 |
Behavioral discrepancy: With history in localStorage but no Frequency set, Bitmovin may still skip prerolls in history; Legacy will not apply history filtering.
Bitmovin vs Legacy — parity check
| Feature / SCP field | Legacy | Bitmovin | Parity? |
|---|---|---|---|
| Pre-Roll / Post-Roll URL lists | Yes | Yes | Yes |
| Amount (modal) | Sequential / random | Sequential / first URL | Partial |
| Skip Ad Button | Yes | Yes | Yes |
| Countdown Timer | Default on | Default off if unset | Partial |
| Custom text before/after Ad | Broken mapping | Not implemented | No |
| Frequency of Ad | Requires value set | Stricter without it | Partial |
| Amount of Ads (top-level) | UI only | Not passed to player | N/A |
| Pre-Roll MP4 URL (account) | Merged at parse | Merged at parse | Yes |
| Background mode | Ads stripped | — | — |
Security tab
File: sardius-control-panel/.../tabs/Security/Security.tsx
| SCP field name (UI) | Form variable | JSON path | Effect on player | Notes |
|---|---|---|---|---|
| Secure Stream | secureStream |
securedUrls |
Enables URL encryption / secure origin delivery | When off, geo criteria arrays cleared on save |
| Cities | cities |
securedData.cities[] |
Geo allow/deny criteria | Disabled when Secure Stream off |
| Continents | continents |
securedData.continents[] |
Geo allow/deny criteria | Disabled when Secure Stream off |
| Countries | countries |
securedData.countries[] |
Geo allow/deny criteria | Disabled when Secure Stream off |
| Postal Codes | codes |
securedData.postalCodes[] |
Geo allow/deny criteria | Form name codes; JSON key postalCodes |
| Time Zones | zones |
securedData.timezones[] |
Geo allow/deny criteria | Disabled when Secure Stream off |
| Tokenization | tokenization |
(UI only — not persisted as boolean) | Enables/disables encryption key field in UI | Load: true if authKey is a string |
| Encryption Key Generator | encryptedKey |
authKey (string or null) |
JWT/token auth key for securing content access | Does not auto-update URLs; regenerate creates 15-char UUID |
History tab
File: sardius-control-panel/.../tabs/History/History.tsx — read-only, not saved from Player Editor.
| SCP field name (UI) | JSON path | Description |
|---|---|---|
| Edited | updatedAt, updatedBy |
Last edit timestamp and user |
| Created | createdAt / createdDate, createdBy |
Creation timestamp and user |
| Player ID (header copy button) | id |
Read-only identifier for embed/API; copy to clipboard |
Header actions & account settings
Actions in PlayerInfo header menu — not part of playerUpdate() except where noted.
| SCP action / field name | Form variable | JSON path | Effect |
|---|---|---|---|
| Make Player Default | — | account.defaultPlayerId |
Sets account default player (not on player record) |
| Duplicate Player | — | New player record | Clones player to a new ID |
| Delete Player | — | Record removed | Deletes player; locked for dvr / noDvr types |
| Pre-Roll MP4 URL (Account → General Settings) | preRollUrls |
account.preRollUrls[] |
Merged into all players' preroll.urls at api-players parse time |
UI-only fields (loaded but not saved):
showControlBarIcons (derived from control bar children length), tokenization boolean (only authKey is persisted).
Complete save mapping
All fields written by PlayerInfo.playerUpdate() on Save.
| Form variable / state | JSON path | Tab |
|---|---|---|
title | title | Features |
playerType | setup.playerType | Features |
scrubBar | theme.id | Features |
autoPlay | autoplay | Features |
mutePlayerOnStart | muted | Features |
loopVideo | loop | Features |
iosNativeOnFullscreen | nativeiOSFullscreen | Features |
scrubColor | theme.styles.primaryColor | Appearance |
controls | background (inverted) | Appearance |
controlBarIcons | setup.controlBar.children | Appearance |
sardiusAdSettings + adAmount + adFrequency | plugins.sardiusAds | Advertising |
secureStream | securedUrls | Security |
cities | securedData.cities | Security |
continents | securedData.continents | Security |
countries | securedData.countries | Security |
codes | securedData.postalCodes | Security |
zones | securedData.timezones | Security |
encryptedKey | authKey | Security |
Known gaps & SCP UI bugs
- Layout confusion: Global Amount of Ads and Frequency of Ad appear below both pre-roll and post-roll sections — looks like they apply to both.
- Hidden settings: Account Pre-Roll MP4 URL,
contribConfig.contentIsLive, and background mode ad stripping are not surfaced on Advertising tab. - Break text mapping: SCP saves per-break; Video.js plugin reads top-level — likely broken for SCP-configured text.
- Bitmovin break text: Not implemented at all.
- Single preroll selection: Legacy random vs Bitmovin first URL in list.
- Copy bug: Post-roll section reuses pre-roll description i18n key (
advertisingPreRollDescription). - Tooltip bug: Amount of Ads tooltip duplicates modal Amount tooltip and describes random selection — misleading for the global field.
- No live preview:
PlayerPreviewon Advertising tab is commented out.
Recommendations for SCP UI work
- Relabel global fields: Move or header Amount of Ads / Frequency of Ad as "Pre-roll smart ads (global)" — not post-roll.
- Surface account prerolls: Add callout linking Account → General Settings → Pre-Roll MP4 URL.
- Break text tooltips: Label as Legacy-only or hide for Bitmovin until implemented.
- Countdown copy: Document different defaults per player type.
- Bitmovin random pool: Implement random selection when modal Amount = 1 if product expects parity with Legacy.
End-to-end flow
Save path (SCP)
Advertising tab state (sardiusAdSettings)
+ react-hook-form (adAmount, adFrequency)
↓ PlayerInfo.playerUpdate()
plugins.sardiusAds { preroll, postroll, amount, frequencyEach }
↓ api-players update
Dynamo player record
Playback path
Dynamo player.plugins.sardiusAds
↓ api-players parseResults
├─ sardiusAds.ts merge (account preRollUrls, contribConfig)
├─ Legacy: buildPlayerConfig → player-plugin-ads
└─ Bitmovin: getSardiusAdsForPlayerData → sourceConfig.html + onSourceLoaded.html
Code index
| Topic | Path |
|---|---|
| Type definitions | types-sardius-player/src/player.ts |
| SCP Advertising tab | sardius-control-panel/.../Advertising/Advertising.tsx |
| SCP modal | sardius-control-panel/.../AddAssetModal/AddAssetModal.tsx |
| SCP save | sardius-control-panel/.../PlayerInfo/PlayerInfo.tsx |
| SCP Appearance / Features | sardius-control-panel/.../tabs/Appearance/Appearance.tsx, .../Features/Features.tsx |
| SCP Security tab | sardius-control-panel/.../tabs/Security/Security.tsx |
| SCP History tab | sardius-control-panel/.../tabs/History/History.tsx |
| DefaultValues / types | sardius-control-panel/.../PlayerInfo.types.ts |
| Localization (EN labels) | sardius-control-panel/src/common/localization.i18n.js |
| Control bar helpers | sardius-control-panel/src/app/Players/functions.tsx |
| Account prerolls UI | sardius-control-panel/.../GeneralAccountSettings.tsx |
| Account merge | api-players/.../parseResults/sardiusAds.ts |
| Bitmovin extraction | api-players/.../getSardiusAdsForPlayerData.ts |
| Bitmovin preroll init | api-players/.../bitmovin/loadPlayer/sourceConfig.html |
| Bitmovin ad transitions | api-players/.../bitmovin/loadPlayer/onSourceLoaded.html |
| Video.js plugin | player-plugin-ads/src/index.ts |
| Video.js ad playback | player-plugin-ads/src/libs/Ads.ts |
| In-repo dev doc | api-players/docs/ads.md |