The video player's playback behavior can be customized using the BlazeVideosPlaybackConfiguration on the global BlazeSDK.setDefaultVideosPlaybackConfiguration method, or for specific widgets utilizing the videosPlaybackConfiguration property.

The playback configuration controls aspects like aspect ratio handling and screen orientation behavior, which are separate from visual styling (handled by BlazeVideosPlayerStyle).

Presets

BlazeVideosPlaybackConfiguration.base()

Returns a BlazeVideosPlaybackConfiguration instance with default playback settings. This can be used to customize playback behavior without affecting the player's visual style.

// Get the base configuration and customize it
var playbackConfig = BlazeVideosPlaybackConfiguration.base()
playbackConfig.multiAspectRatio = true
playbackConfig.shouldOpenInLandscape = true

// Use the customized configuration globally
Blaze.shared.setDefaultVideosPlaybackConfiguration(playbackConfig)

// Or use it for a specific Videos widget
let widgetView = BlazeVideosWidgetView()
widgetView.videosPlaybackConfiguration = playbackConfig

Configuration Properties

multiAspectRatio

Controls whether the player dynamically selects the optimal aspect ratio based on device orientation.

• Default: false
• When true: The player automatically uses the biggest available aspect ratio for each orientation, switching between renditions to maximize screen utilization. This ensures optimal viewing experience as the device rotates.
  Example: Video contains renditions of; 9:16 & 16:9- The player will select 9:16 when in portrait, and automatically transition into displaying 16:9 when the interface is rotated to landscape (default behavior).
• When false: The player uses the first available rendition regardless of orientation changes.

var config = BlazeVideosPlaybackConfiguration.base()
config.multiAspectRatio = true
Blaze.shared.setDefaultVideosPlaybackConfiguration(config)

shouldOpenInLandscape

Determines whether the player should force rotation to landscape when entering fullscreen from portrait orientation, even when the user's device is configured to be locked in portrait.

• Default: false
• When true: Opening the player in fullscreen from portrait mode will automatically rotate the device to landscape orientation.
• When false: The player respects the current device orientation when entering fullscreen.

var config = BlazeVideosPlaybackConfiguration.base()
config.shouldOpenInLandscape = true
Blaze.shared.setDefaultVideosPlaybackConfiguration(config)

bufferingSpinnerDelay

The delay in seconds before the buffering spinner becomes visible during playback.

If the player finishes buffering before this threshold elapses, the spinner is never shown.

• Default: 1.0 seconds
• Type: TimeInterval
• Min: 0 (spinner appears immediately on buffering)

var config = BlazeVideosPlaybackConfiguration.base()
config.bufferingSpinnerDelay = 0.5
Blaze.shared.setDefaultVideosPlaybackConfiguration(config)

Usage Examples

Global Configuration

Set default playback configuration for all video players in your app:

var config = BlazeVideosPlaybackConfiguration.base()
config.multiAspectRatio = true
config.shouldOpenInLandscape = false

Blaze.shared.setDefaultVideosPlaybackConfiguration(config)

Widget-Specific Configuration (UIKit)

Override the global configuration for a specific widget:

let widgetView = BlazeVideosWidgetView()

var customConfig = BlazeVideosPlaybackConfiguration.base()
customConfig.multiAspectRatio = true
customConfig.shouldOpenInLandscape = true

widgetView.videosPlaybackConfiguration = customConfig

Widget-Specific Configuration (SwiftUI)

Configure playback behavior when initializing a SwiftUI widget:

var playbackConfig = BlazeVideosPlaybackConfiguration.base()
playbackConfig.multiAspectRatio = true
playbackConfig.shouldOpenInLandscape = true

let viewModel = BlazeSwiftUIVideosWidgetViewModel(
    widgetConfiguration: widgetConfiguration,
    videosPlaybackConfiguration: playbackConfig
)

Combined with Player Style

You can use both playback configuration and player style together:

// Configure playback behavior
var playbackConfig = BlazeVideosPlaybackConfiguration.base()
playbackConfig.multiAspectRatio = true
playbackConfig.shouldOpenInLandscape = true

// Configure visual style
var playerStyle = BlazeVideosPlayerStyle.base()
playerStyle.backgroundColor = .black
playerStyle.buttons.mute.isVisible = true

// Apply both to a widget
let widgetView = BlazeVideosWidgetView()
widgetView.videosPlaybackConfiguration = playbackConfig
widgetView.videosPlayerStyle = playerStyle