Windows SDK quick integration

meshstream_client_create validates local inputs and creates a client only; it never requests Bootstrap, a Tracker, or ICE. meshstream_client_create_playback_session immediately returns a CDN-safe playback URL, then resolves P2P configuration in the background.

MeshStream Windows SDK exposes a C ABI for native desktop players. Your app keeps its existing player; the SDK manages playback sessions, media request routing, and CDN fallback.

Before running the code, complete Installation and setup, prepare your SDK Key and playable media URL, and configure the application network policy.

Quick start

Follow four steps: initialize the Client, create a playback session, pass the SDK URL to the player, then release resources when playback ends.

1. Initialize the Client

#include "meshstream.h"

meshstream_config_t config = {0};
meshstream_config_default(&config);
config.key = "your_sdk_key";

meshstream_client_t* client = NULL;
if (meshstream_client_create(&config, &client) != MESHSTREAM_OK) {
    // Record the local initialization error. The application may explicitly
    // choose a direct origin fallback.
    return;
}

2. Create a session and pass it to the player

origin_url is the original media URL. Create one session for each playback and always pass the SDK playback_url to the player. The session URL preserves the existing media path; P2P availability changes acceleration state, not whether that URL is used.

const char* origin_url = "https://cdn.example.com/video/master.m3u8";

meshstream_session_t* session = NULL;
meshstream_playback_options_t options = {0};
options.struct_size = sizeof(options);
options.version = MESHSTREAM_PLAYBACK_OPTIONS_VERSION;
options.content_id = "asset-12345";

if (meshstream_client_create_playback_session(
        client, origin_url, &options, &session, NULL) != MESHSTREAM_OK) {
    meshstream_client_destroy(client);
    return;
}
const char* playback_url = meshstream_session_get_playback_url(session);

// Pass playback_url to VLC, libVLC, mpv, or your own player while session is alive.

3. Release the session when playback ends

if (session != NULL) {
    meshstream_session_destroy(session);
}

4. Release the Client when the app exits

meshstream_client_destroy(client);

Temporary acceleration unavailability does not interrupt playback; the player continues using the session's playback_url. Only when client or session creation fails because of a local configuration, resource, or programming error may the application explicitly log the error and play origin_url directly. That is an application fallback, bypasses the SDK, and is not included in SDK usage reporting.

Preload the next item

For a likely next HLS or DASH item, create its candidate session and call meshstream_session_preload. It asynchronously warms the manifest and first segment without waiting for network I/O, and does not create or control a player. Use that session's playback URL directly if the user switches; destroy it when the candidate is discarded.

Configuration

Field	Default	Description
key	Required	SDK Key issued by the console
log_level	0	Log level; keep the default in production

The SDK handles service discovery, application identity, and policy automatically. Your app does not need to provide service URLs or tokens.

The SDK does not accept a client-selected region. The service resolves the SDK Key's tenant home region (homeRegion) and derives access-side locality (edgeRegion) from trusted request-network signals for Tracker and ICE scheduling. This is separate from data residency. Do not add areaCode, area_code, or region to the client configuration. In multi-center strict mode, an unresolved home region returns 503 HOME_REGION_UNRESOLVED; a request sent to the wrong center returns 421. The SDK does not switch centers itself, and all acceleration failures retain the CDN playback path.

Playback session API

Method	Description
meshstream_client_create_playback_session	Creates a playback session and returns the SDK playback URL
meshstream_session_get_playback_url	Gets the playback URL to pass to the player
meshstream_session_preload	Asynchronously warms an HLS/DASH manifest and first segment without playing media
meshstream_session_set_p2p_enabled	Enables or disables P2P at runtime without affecting CDN playback
meshstream_session_update_buffered_duration_ms	Reports the time from the current position to the buffer edge so background P2P prefetch can be adjusted
meshstream_session_update_current_position_ms	Reports the current playback position; VOD uses it to match peers at a similar position and it should be called immediately after a seek
meshstream_session_get_stats	Gets a snapshot of current traffic and peer counts
meshstream_session_destroy	Ends the playback session and releases its resources
meshstream_client_destroy	Releases the client and its resources

Events and statistics

Windows SDK exposes statistics through meshstream_session_get_stats. Important fields include:

• p2p_downloaded: bytes received by this device over P2P;
• p2p_uploaded: bytes shared by this device with other devices;
• http_downloaded: bytes received from your CDN;
• connected_peers: number of currently connected peers;
• peer_connect_errors: cumulative failed peer-connection attempts.

HLS, DASH, and compatibility

• The SDK supports HLS and DASH media requests but does not decode media formats.
• The player must support the selected format and play the URL returned by the SDK.
• When acceleration, network, or configuration handling is temporarily unavailable, playback continues and acceleration state must not be used as a condition to stop the player.

Playback resilience

The following conditions only disable or reduce acceleration; they do not block media playback:

• SDK Key, application, or platform validation does not pass.
• No acceleration connection is currently available.
• Network conditions do not meet acceleration requirements.
• An individual media request times out or fails.
• The platform service is temporarily unavailable.

Error codes

Macro	Value	Meaning
MESHSTREAM_OK	0	Success
MESHSTREAM_INVALID_ARGUMENT	1	Invalid argument
MESHSTREAM_RUNTIME_ERROR	2	Runtime error
MESHSTREAM_CREATE_PLAYBACK_SESSION_FAILED	3	Failed to create the playback session
MESHSTREAM_PRELOAD_SKIPPED	4	Preload is unsupported or already running

Next steps

Quick start · Best practices · Troubleshooting

Related guides: Installation and setup · Advanced usage.