Windows SDK Advanced Usage

This page covers multiple sessions, live/VOD integration, authorization, and runtime controls. See Windows SDK Quick integration for standard integration.

Live and VOD integration policy

The SDK detects live/VOD automatically; both use the same quick integration. Player feedback is optional and helps P2P scheduling.

Live

Report the continuous playable buffer ahead of the current position to tune P2P prefetch. For example, position 60 s with buffer ending at 70 s means 10,000 ms. Live start position and target latency remain player settings.

meshstream_session_update_buffered_duration_ms(session, buffered_duration_ms);

VOD

Also report playback position so the SDK can prefer already-connected peers with nearby progress and the requested segment. Update position immediately after a completed seek.

meshstream_session_update_current_position_ms(session, position_ms);
meshstream_session_update_buffered_duration_ms(session, buffered_duration_ms);

Use non-negative milliseconds; do not count across buffer gaps. Send valid player state about once per second. Stop and drain updates before closing the session.

Complete player feedback example

Supply valid signed millisecond values from your player. The helper validates them before converting to the C API's uint64_t.

void sync_playback_state(
    meshstream_session_t* session,
    bool is_live,
    int64_t current_position_ms,
    int64_t buffered_duration_ms) {
    if (!session) return;
    if (buffered_duration_ms >= 0) {
        meshstream_session_update_buffered_duration_ms(
            session, static_cast<uint64_t>(buffered_duration_ms));
    }
    if (!is_live && current_position_ms >= 0) {
        meshstream_session_update_current_position_ms(
            session, static_cast<uint64_t>(current_position_ms));
    }
}

Direct MP4 / MP3 playback

MP4 and MP3 are direct VOD files: the player loads a file URL rather than an HLS .m3u8 or DASH .mpd manifest. Use a stable content_id for the same video or audio asset. Set mime_type explicitly when the URL has no file extension.

meshstream_playback_options_t options{};
options.struct_size = sizeof(options);
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
options.content_id = "trailer-2026";
options.mime_type = "mp4";

meshstream_session_t* session = nullptr;
int32_t rc = meshstream_client_create_playback_session(
    client,
    "https://cdn.example.com/video/trailer.mp4",
    &options,
    &session,
    nullptr);
if (rc == MESHSTREAM_OK) {
    const char* playback_url = meshstream_session_get_playback_url(session);
    // Pass playback_url to an MP4-capable player.
}

For MP3, change the URL and mime_type to .mp3 and "mp3", then pass the result to a host player that supports audio playback. The media origin must support a single Range request and return a valid Content-Range. If it does not, the file still plays normally but acceleration is not enabled.

Per-playback configuration

One meshstream_client_t can manage multiple independent meshstream_session_t instances. Each player instance needs its own session. Destroy the old session when content changes, then create one for the new asset.

Dynamic URLs and origin authorization

Use origin_headers_json for JSON request headers sent only to the origin:

meshstream_playback_options_t options{};
options.struct_size = sizeof(options);
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
options.content_id = "movie-2026-001";
options.mime_type = "m3u8"; // Set mpd for DASH, or mp4/mp3 for direct media, when the URL has no extension
options.origin_headers_json = "{\"Authorization\":\"Bearer origin-token\"}";

meshstream_session_t* session = nullptr;
if (meshstream_client_create_playback_session(
        client, signed_url, &options, &session, nullptr) == MESHSTREAM_OK) {
    const char* playback_url = meshstream_session_get_playback_url(session);
    // Pass playback_url to the player.
}

Never write this field to logs or send it to other viewers.

Preload and content switching

Explicit preload is an optional HLS/DASH warmup: it fetches the manifest and first media segment in the background, not the entire video. It may also start Tracker/Peer connections early, but a successful queue operation does not guarantee that peers or media are ready. An unplayed candidate session does not upload media to peers. MP4/MP3 direct files do not use this explicit preload path.

Keep the candidate session and reuse its playback URL when selected. Before closing a session, stop and drain its player-state updates and remove its event subscriptions; do not continue callbacks against a closed session. Preload does not prepare a decoder or render a frame.

The host owns current_session and next_session pointers of type meshstream_session_t*, initially nullptr. Each player has its own sessions. next_url is the candidate URL; next_content_id is its stable content ID.

Prepare candidate content

meshstream_playback_options_t options{};
options.struct_size = sizeof(options);
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
options.content_id = next_content_id;
options.mime_type = "m3u8";

meshstream_session_t* candidate = nullptr;
int32_t rc = meshstream_client_create_playback_session(
    client, next_url, &options, &candidate, nullptr);
if (rc == MESHSTREAM_OK) {
    if (next_session) meshstream_session_destroy(next_session);
    next_session = candidate;
    int32_t preload_rc = meshstream_session_preload(next_session);
    // MESHSTREAM_OK: queued; MESHSTREAM_PRELOAD_SKIPPED: not queued.
    (void)preload_rc;
}

MESHSTREAM_OK means queued; MESHSTREAM_PRELOAD_SKIPPED means this call did not queue a warmup, for example for direct files or an already-running warmup. It is not a playback error. Handle other return codes as errors; creation failure must not replace the active session.

Switch to the candidate

Before running the following code, stop and drain old-session callbacks, stop the host player, and detach the old media. After promoting the candidate, load its URL using the host player API. Keep the current session alive while it is playing:

if (next_session) {
    if (current_session) meshstream_session_destroy(current_session);
    current_session = next_session;
    next_session = nullptr;
    const char* playback_url = meshstream_session_get_playback_url(current_session);
    // Load playback_url in the host player, then start playback.
    (void)playback_url;
}

Cancel candidate content

Close only the discarded candidate; the current session keeps playing:

if (next_session) {
    meshstream_session_destroy(next_session);
    next_session = nullptr;
}

Runtime controls

meshstream_session_set_p2p_enabled(session, 0); // Temporarily disable P2P
meshstream_session_set_p2p_enabled(session, 1);

meshstream_stats_t stats{};
meshstream_session_get_stats(session, &stats);

meshstream_session_set_p2p_enabled affects acceleration for the current session only; it does not prevent the player from continuing with playback_url.

Events and monitoring

Windows SDK monitoring uses snapshots:

meshstream_stats_t stats{};
meshstream_session_get_stats(session, &stats);

meshstream_status_t status{};
meshstream_session_get_status(session, &status);

Monitor P2P download, sharing, and media-origin download traffic, plus connection and segment success/failure counters. Status and statistics are for display, alerting, and diagnostics only; they must not determine whether the player continues playback.

Verify P2P delivery

1. Start with one device: verify playback, seeking for VOD, and normal playback with P2P disabled.
2. Run two devices on the same content with a consistent content_id. For VOD, use overlapping playback positions; for live, play the same channel. Keep the media bytes and timeline consistent; do not reuse an ID for different assets or personalized manifests.
3. Check that player updates use milliseconds and continue after the manifest loads. At position 60 seconds with continuous buffer ending at 70 seconds, the buffer value is 10,000 ms; refresh VOD position after a completed seek.
4. Observe changes in P2P downloaded bytes and offload ratio over a playback interval. A connected peer alone does not prove that media was downloaded through P2P. Results depend on overlapping available segments, network conditions, and platform policy.
5. Disable P2P and verify that playback continues through CDN. Then stop state updates and event subscriptions before closing the session, and verify that switching content creates no calls against the closed session.

Network and platform policy

The SDK manages application identity and service connectivity automatically. Application code does not provide service addresses, regions, or access tokens. meshstream_session_set_p2p_enabled is a local session switch, while console policy has higher priority.

Lifecycle and fallback

• Use one meshstream_session_t per player instance.
• Destroy the session before switching channels or programs, then create a new session.
• Destroy all sessions before calling meshstream_client_destroy at application shutdown.
• When acceleration, authorization, or network handling is unavailable, continue using the SDK playback URL.
• MESHSTREAM_CREATE_PLAYBACK_SESSION_FAILED means session creation failed; retain the original playback URL as the business fallback.

Destroy sessions before destroying the client. When acceleration is temporarily unavailable, normal playback continues. Record traffic statistics and diagnostics for production troubleshooting.

Capability boundary

The SDK owns playback sessions and acceleration handling. VLC, libVLC, mpv, or an application player owns manifest parsing, ABR, decoding, rendering, and player caching. The SDK does not replace the player or promise continued media sharing after the application exits or enters the background.