Latency Configuration

Some live streams can be delivered through both a standard media source and a lower-latency media source. Lura Player exposes a single latency mode contract so your application can detect when low latency playback is available, request it at startup, switch to it at runtime, and restrict it per viewer.

There are two latency modes:

• Default ("def") — uses the standard content.media source list. Always available for valid content.
• Low latency ("low") — uses the optional content.lowLatencyMedia source list. Available only when a low-latency source is provided.

Low latency playback applies to live and DVR-capable live content. It is not used for VOD content.

How low latency media is provided

When playback is resolved through Akta Cloud (app key + asset id), the low-latency source is returned automatically in content.lowLatencyMedia for live content that has one configured. For direct media configuration, provide it alongside content.media:

let config = LuraPlayerConfiguration(
    content: .init(
        media: [
            .init(url: "https://example.com/default.m3u8", type: "application/x-mpegURL")
        ],
        lowLatencyMedia: [
            .init(url: "https://example.com/low-latency.m3u8", type: "application/x-mpegURL")
        ]
    )
)
player?.setConfig(config)

content.lowLatencyMedia uses the same item shape and MIME types as content.media. When it is present and contains at least one valid playable item, low latency mode becomes available.

Requesting an initial latency mode

Use initialization.video.latencyMode to request the mode the player should start in. See Initialization Configuration for the full option set.

let config = LuraPlayerConfiguration(
    initialization: .init(
        video: .init(
            latencyMode: .LOW_LATENCY
        )
    )
)
player?.setConfig(config)

If "low" is requested but low latency mode is not available, the player falls back to "def" and starts with content.media. This fallback is not treated as an error.

Restricting which modes are exposed

Use latency.allowedModes to restrict which latency modes the player may expose for the viewer. This is useful for entitlement or premium-user gating.

let config = LuraPlayerConfiguration(
    latency: .init(
        allowedModes: .init(
            low: false
        )
    )
)
player?.setConfig(config)

When allowedModes.low is false, the low-latency source is not returned even if one is available. Default latency ("def") is always enabled and is not represented in allowedModes.

Reading availability and switching modes at runtime

You can check which modes are available and switch between them while playback is active. These methods are documented in the Player Methods Reference.

// Read the current latency mode
let mode = player?.getLatencyMode()

// Read which modes are available for the current content
let availability = player?.getLatencyModeAvailability()

// Switch to low latency mode
player?.setLatencyMode(.LOW_LATENCY)

setLatencyMode switches to the requested mode only when it is available. If the mode is unavailable, invalid, or already active, the call is a no-op and does not throw.

Reacting to latency mode changes

Listen to the LATENCY_MODE_CHANGED event to update your UI when availability becomes ready or when the effective mode changes.

let listener: LuraEventListener = { [weak self] eventBundle in
    DispatchQueue.main.async {
        switch eventBundle.type {
        case .LATENCY_MODE_CHANGED:
            guard let data = eventBundle.data as? LatencyModeChanged else { return }
            print(data.latencyMode)      // .DEFAULT or .LOW_LATENCY
            print(data.availability)      // [.DEFAULT: true, .LOW_LATENCY: true]
        default:
            break
        }
    }
}
player?.addListener(listener: listener)

The event is emitted when availability for the active content is ready, and again whenever the effective latency mode changes after a successful setLatencyMode call, a content change, or a DVR live-edge transition.