Dynamic Options Manager - TrackPlay Documentation

OptionsManager changes player configuration after the player has loaded. You can retune the player at runtime without reloading it.

The OptionsManager is available in TrackPlay player version 6.0+ and is automatically initialized with every player instance.

Overview

The OptionsManager changes player options by dot-notation path, so you can set a nested value and apply it to a running player without rebuilding the whole options object.

Key Features

Dot Notation Access - Use simple paths like 'style_options.main_color'
Batch Operations - Change multiple options efficiently in one call
Automatic Application - Changes are immediately applied to player components
Extensible Handlers - Register custom handlers for new option types
Event Notifications - Listen for option change events
Type Safety - Built-in validation and error handling

Basic Usage

Setting Single Options

document.addEventListener('TrackPlayReady', function (e) {
    let player = e.detail.player;
    
    // Change video time display color
    player.setOption('style_options.main_color', '#ff0000');
    
    // Toggle autoplay
    player.setOption('autoplay_options.autoplay', false);
    
    // Enable classic progress bar
    player.setOption('style_options.classic_progress_bar', true);
    
    // Set autoplay timing
    player.setOption('autoplay_options.time', '00:05:00');
});

Options can be set immediately when TrackPlayReady fires. If the OptionsManager is not ready yet, options are automatically queued and applied after player initialization completes, ensuring user settings always take precedence over default options.

Batch Option Changes

For multiple changes, use setMultipleOptions() for better performance:

player.setMultipleOptions({
    'style_options.main_color': '#00ff00',
    'style_options.corner_play_button': false,
    'autoplay_options.autoplay': true,
    'autoplay_options.time': '00:03:00'
});

Getting Current Values

// Get current values
const currentColor = player.getOption('style_options.main_color');
const isAutoplay = player.getOption('autoplay_options.autoplay');
const template = player.getOption('style_options.controls_template');

console.log('Current settings:', {
    color: currentColor,
    autoplay: isAutoplay,
    template: template
});

Supported Option Types

Style Options (`style_options`)

Control visual appearance and UI elements:

// Colors
// Recolors the whole controls chrome: buttons, settings menu, volume slider and the
// time display. Not the time display alone.
player.setOption('style_options.main_color', '#ff6b35');

// Control buttons (show/hide)
player.setOption('style_options.corner_play_button', true);
player.setOption('style_options.classic_progress_bar', true);
player.setOption('style_options.classic_fullscreen_button', true);
player.setOption('style_options.classic_rewind_button', true);
player.setOption('style_options.classic_forward_button', true);
player.setOption('style_options.classic_video_time', true);
player.setOption('style_options.settings_button', true);

// Fullscreen behavior
player.setOption('style_options.play_in_fullscreen', false);
player.setOption('style_options.fullscreen_video_element_desktop', false); // Container fullscreen on desktop
player.setOption('style_options.fullscreen_video_element_mobile', true);   // Video element with browser controls fullscreen on mobile

Autoplay Options (`autoplay_options`)

Configure automatic playback behavior:

// Basic autoplay control
player.setOption('autoplay_options.autoplay', true);
player.setOption('autoplay_options.time', '00:05:00');

// Custom autoplay video (if configured)
player.setOption('autoplay_options.video', videoObject);

Progress Options (`progress_options`)

Configure progress bar behavior:

// Progress bar styling
player.setOption('progress_options.background_color', '#333333');
player.setOption('progress_options.bar_color', '#ff0000');
player.setOption('progress_options.height', 4);

// Duration display
player.setOption('progress_options.duration', true);

Playback Options (`playback_options`)

Control video playback behavior:

// Volume and audio
player.setOption('playback_options.volume', 0.8);        // Volume level (0-1)
player.setOption('playback_options.muted', false);       // Mute/unmute video
player.setOption('playback_options.playback_rate', 1.75); // Playback speed (0.25-4.0)

Option keys are matched exactly. Set a key that does not exist and nothing happens: no error, no warning, no effect. Check the key against the lists below before you ship it.

Continue Watching Options (`continue_watching_options`)

The Continue or Restart choice a returning viewer sees.

player.setOption('continue_watching_options.enabled', true);
player.setOption('continue_watching_options.time', '00:30');
player.setOption('continue_watching_options.backdrop_color', '#000000');

time is a clock string, MM:SS or HH:MM:SS, not a number of seconds. Passing 30 fails validation.

Captions Options (`captions_options`)

Captions are a list of tracks plus the styling applied to all of them. There is no enabled key and no language key. A track is selected by its lang, and the one marked default is the one that shows.

player.setOption('captions_options.font_size', '16px');
player.setOption('captions_options.text_color', '#ffffff');
player.setOption('captions_options.background_color', 'rgba(0,0,0,0.75)');

Styling keys: text_color, background_color, font_family, font_weight, font_size, padding. Each track carries lang, label, default and its cue data.

Smart Orientation Options (`smart_orientation_options`)

Serves the portrait version of the video to a portrait device.

player.setOption('smart_orientation_options.enabled', true);

enabled is the only key. Which video is served is decided by the uploaded portrait version, not by a switching option.

Turbo Options (`turbo_options`)

Playback speed, and speed as a test.

// A fixed speed for every viewer
player.setOption('turbo_options.speed', 1.25);

// Or let two speeds compete, split by weight
player.setOption('turbo_options.ab_testing', true);
player.setOption('turbo_options.items', [
  { speed: 1.0,  weight: 50 },
  { speed: 1.25, weight: 50 },
]);

Key	Type	Bounds
`speed`	number	0.6 to 2
`ab_testing`	boolean	Arms are only split when this is true
`items`	array	Up to 10 arms, each with `speed` and `weight`

items on its own does nothing. The split runs only when ab_testing is true, which is deliberate: the editor seeds two default arms as soon as the tab is opened, and without that guard opening the tab would start a speed test on the video by itself.

Paused Options (`paused_options`)

The paused state is a designed overlay, not a blank frame.

player.setOption('paused_options.enabled', true);
player.setOption('paused_options.html', '<h2>Still there?</h2>');
player.setOption('paused_options.backdrop_color', 'rgba(0,0,0,0.6)');

Keys: enabled, template, html, custom_html (required when template is custom), backdrop_color, and the per-orientation style and canvas blocks.

Thumbnail Options (`thumbnail_options`)

Configure thumbnail display:

// Thumbnail settings
player.setOption('thumbnail_options.enabled', true);
player.setOption('thumbnail_options.landscape_image', 'https://example.com/thumb.jpg');
player.setOption('thumbnail_options.portrait_image', 'https://example.com/thumb-portrait.jpg');

Timed Events Options (`timed_events_options`)

Configure time-based events:

// Individual timed events with time and event data
// These are arrays of event objects configured via dashboard

Pixels Options (`pixels_options`)

Configure conversion tracking pixels:

// Individual pixel events with time and pixel data
// These are arrays of pixel objects configured via dashboard

Security Options (`security_options`)

Configure player security features:

// Security settings
player.setOption('security_options.use_shadow_dom', true);
player.setOption('security_options.use_blob_urls', false);
player.setOption('security_options.detect_devtools', true);
player.setOption('security_options.prevent_extensions', true);
player.setOption('security_options.obfuscate_urls', true);

Advanced Usage

Event Listening

Listen for option changes to trigger custom behavior:

player.on('option-changed', (event) => {
    const { path, value, oldValue } = event.detail;
    
    console.log(`Option ${path} changed from ${oldValue} to ${value}`);
    
    // React to specific changes
    if (path === 'style_options.main_color') {
        updateExternalUI(value);
    }
});

Custom Option Handlers

// Register a custom handler for your own option namespace
player.registerOptionHandler('custom_options', (path, value, oldValue) => {
    console.log(`Custom option ${path} changed:`, { value, oldValue });
    
    // Handle your custom logic
    if (path === 'custom_options.theme_mode') {
        updatePageTheme(value);
    }
});

// Use your custom options
player.setOption('custom_options.theme_mode', 'dark');
player.setOption('custom_options.analytics_enabled', true);

Conditional Updates

Apply options based on conditions:

// Update based on screen size
function updateForScreenSize() {
    const isMobile = window.innerWidth < 768;
    
    player.setMultipleOptions({
        'style_options.controls_template': isMobile ? 'template-1' : 'template-2',
        'autoplay_options.autoplay': !isMobile, // Disable autoplay on mobile
        'style_options.classic_progress_bar': isMobile
    });
}

// Update on resize
window.addEventListener('resize', updateForScreenSize);
updateForScreenSize(); // Initial call

Time-Based Updates

Change options at specific times:

// Update options during video playback
player.on('time', (event) => {
    const currentTime = event.detail.time;
    
    // Change colors at 30 seconds
    if (currentTime > 30 && !colorChanged) {
        player.setOption('style_options.main_color', '#ff0000');
        colorChanged = true;
    }
    
    // Speed the video up once past the first minute
    if (currentTime > 60 && !spedUp) {
        player.setOption('turbo_options.speed', 1.25);
        spedUp = true;
    }
});

API Reference

Methods

`setOption(path, value, apply = true)`

Set a single option using dot notation. Parameters:

path (string) - Dot notation path to the option
value (any) - New value to set
apply (boolean) - Whether to immediately apply changes

Returns: boolean - Success status Example:

const success = player.setOption('style_options.main_color', '#ff0000');

`setMultipleOptions(options, apply = true)`

Set multiple options at once for better performance. Parameters:

options (object) - Object with paths as keys and values
apply (boolean) - Whether to immediately apply changes

Returns: boolean - Success status Example:

const success = player.setMultipleOptions({
    'style_options.main_color': '#ff0000',
    'autoplay_options.autoplay': true
});

`getOption(path)`

Get the current value of an option. Parameters:

path (string) - Dot notation path to the option

Returns: any - Current option value Example:

const color = player.getOption('style_options.main_color');

`registerOptionHandler(type, handler)`

type (string) - Root option type. Nothing stops you reusing an existing name, and no error is raised if you do: registering style_options silently replaces the built-in handler for the rest of the page’s life. Pick a name of your own.
handler (function) - Handler function (path, value, oldValue) => void

Returns: boolean - Success status Example:

player.registerOptionHandler('custom_options', (path, value, oldValue) => {
    console.log('Custom option changed:', { path, value, oldValue });
});

Avoid using existing option type names like style_options, autoplay_options, etc. Use your own namespace like custom_options or my_app_options.

Events

`option-changed`

Fired when any option is changed via the OptionsManager. Event Data:

{
    path: string,      // The option path that changed
    value: any,        // New value
    oldValue: any,     // Previous value
    applied: boolean   // Whether the change was applied immediately
}

Common Use Cases

A/B Testing

// Randomly assign variant
const variant = Math.random() > 0.5 ? 'A' : 'B';

if (variant === 'A') {
    player.setMultipleOptions({
        'style_options.main_color': '#ff0000',
        'style_options.controls_template': 'template-1'
    });
} else {
    player.setMultipleOptions({
        'style_options.main_color': '#0000ff',
        'style_options.classic_progress_bar': true
    });
}

// Track the variant
analytics.track('player_variant_assigned', { variant });

User Preferences

// Load user preferences from localStorage
const preferences = JSON.parse(localStorage.getItem('playerPreferences') || '{}');

// Apply saved preferences
if (preferences.volume !== undefined) {
    player.setOption('playback_options.volume', preferences.volume);
}

if (preferences.autoplay !== undefined) {
    player.setOption('autoplay_options.autoplay', preferences.autoplay);
}

// Save preferences when changed
player.on('option-changed', (event) => {
    const { path, value } = event.detail;
    
    if (path.startsWith('playback_options.') || path.startsWith('autoplay_options.')) {
        preferences[path] = value;
        localStorage.setItem('playerPreferences', JSON.stringify(preferences));
    }
});

Fullscreen Configuration

Configure different fullscreen behaviors for desktop and mobile:

// Desktop: Use container fullscreen, Mobile: Use video element fullscreen
const options = {
    style_options: {
        fullscreen_video_element_desktop: false, // Container fullscreen on desktop
        fullscreen_video_element_mobile: true,   // Video element fullscreen on mobile
        classic_fullscreen_button: true          // Show fullscreen button
    }
};

// Apply the configuration
player.setMultipleOptions(options.style_options);

// Or set individually
player.setOption('style_options.fullscreen_video_element_desktop', false);
player.setOption('style_options.fullscreen_video_element_mobile', true);
player.setOption('style_options.classic_fullscreen_button', true);

Best Practices

Option Precedence

User-set options always take precedence over player defaults:

// This user setting will override any default corner_play_button setting
player.setOption('style_options.corner_play_button', false);

// Even if set immediately when TrackPlayReady fires, it will override defaults
document.addEventListener('TrackPlayReady', function (e) {
    let player = e.detail.player;
    
    // This overrides the default value from the dashboard
    player.setOption('style_options.main_color', '#custom');
});

Performance

Use setMultipleOptions() for batch changes instead of multiple setOption() calls
Set apply: false when making multiple sequential changes, then apply manually
Avoid frequent option changes during video playback

Error Handling

// Always check return values
const success = player.setOption('style_options.main_color', '#ff0000');
if (!success) {
    console.error('Failed to set option');
}

// Handle invalid paths gracefully
try {
    player.setOption('invalid.path.here', 'value');
} catch (error) {
    console.error('Option setting failed:', error);
}

Type Safety

// Validate values before setting
function setMainColor(color) {
    if (typeof color === 'string' && /^#[0-9A-F]{6}$/i.test(color)) {
        player.setOption('style_options.main_color', color);
    } else {
        console.error('Invalid color format:', color);
    }
}

Dynamic option changes are applied immediately to the running player. Some changes may cause visual flicker or interruption of user experience. Test thoroughly in your specific use case.

AI Segments (`ai_segments_options`)

If you use ElevenLabs-powered AI voice segments, the ai_segments_options group (enable flag, preload timing, segment list, voice IDs, prompts, volumes) can be updated at runtime with setOption / setMultipleOptions like other nested options, provided your deployed player build includes the AI Segments feature. See ElevenLabs & AI Segments for setup, trackplay_data, and viewer experience (including unmute behavior).

Troubleshooting

Common Issues

Option not applying:

Verify the option path is correct
Check if the component supports dynamic updates
Ensure the OptionsManager is initialized

Performance issues:

Use batch operations for multiple changes
Avoid rapid sequential option changes
Consider debouncing frequent updates

Memory leaks:

Always clean up event listeners
Remove custom handlers when no longer needed
Call player.destroy() when removing player

Debug Mode

Enable debug logging to see option changes:

// Enable debug mode
window.trackplay_debug = true;

// All option changes will be logged to console
player.setOption('style_options.main_color', '#ff0000');
// Console: 🔧 OptionsManager: Set style_options.main_color { oldValue: "#000000", newValue: "#ff0000", willApply: true }

​Overview

​Key Features

​Basic Usage

​Setting Single Options

​Batch Option Changes

​Getting Current Values

​Supported Option Types

​Style Options (style_options)

​Autoplay Options (autoplay_options)

​Progress Options (progress_options)

​Playback Options (playback_options)

​Continue Watching Options (continue_watching_options)

​Captions Options (captions_options)

​Smart Orientation Options (smart_orientation_options)

​Turbo Options (turbo_options)

​Paused Options (paused_options)

​Thumbnail Options (thumbnail_options)

​Timed Events Options (timed_events_options)

​Pixels Options (pixels_options)

​Security Options (security_options)

​Advanced Usage

​Event Listening

​Custom Option Handlers

​Conditional Updates

​Time-Based Updates

​API Reference

​Methods

​setOption(path, value, apply = true)

​setMultipleOptions(options, apply = true)

​getOption(path)

​registerOptionHandler(type, handler)

​Events

​option-changed

​Common Use Cases

​A/B Testing

​User Preferences

​Fullscreen Configuration

​Best Practices

​Option Precedence

​Performance

​Error Handling

​Type Safety

​AI Segments (ai_segments_options)

​Troubleshooting

​Common Issues

​Debug Mode

Overview

Key Features

Basic Usage

Setting Single Options

Batch Option Changes

Getting Current Values

Supported Option Types

Style Options (`style_options`)

Autoplay Options (`autoplay_options`)

Progress Options (`progress_options`)

Playback Options (`playback_options`)

Continue Watching Options (`continue_watching_options`)

Captions Options (`captions_options`)

Smart Orientation Options (`smart_orientation_options`)

Turbo Options (`turbo_options`)

Paused Options (`paused_options`)

Thumbnail Options (`thumbnail_options`)

Timed Events Options (`timed_events_options`)

Pixels Options (`pixels_options`)

Security Options (`security_options`)

Advanced Usage

Event Listening

Custom Option Handlers

Conditional Updates

Time-Based Updates

API Reference

Methods

`setOption(path, value, apply = true)`

`setMultipleOptions(options, apply = true)`

`getOption(path)`

`registerOptionHandler(type, handler)`

Events

`option-changed`

Common Use Cases

A/B Testing

User Preferences

Fullscreen Configuration

Best Practices

Option Precedence

Performance

Error Handling

Type Safety

AI Segments (`ai_segments_options`)

Troubleshooting

Common Issues

Debug Mode