API Reference

This document describes the application-facing API for the Stream Video ESP32 SDK.

Essential API
Initialization
Join and leave
Error handling
Types

Essential API

The core API for an end-to-end call:

API	Purpose
`stream_video_init()`	Initialize the SDK (call once at startup)
`stream_video_join_call(params, &client)`	Join a call — handles coordinator, SFU, WebRTC, and media publishing automatically
`stream_video_leave_call(client)`	Leave and clean up
`stream_video_deinit()`	Tear down the SDK
`stream_video_error_to_string(err)`	Convert error codes to human-readable strings

Recommended flow:

Initialize – stream_video_init()
Fetch auth data – The app obtains auth data (userId, apiKey, token) from its backend or Stream's token service; the SDK does not fetch tokens.
Join call – stream_video_join_call(&params, &client) with params.auth_data set to the fetched auth data, plus call_type, call_id, mute flags, and result callback
Leave call – stream_video_leave_call(client)
Deinitialize – stream_video_deinit()

The SDK uses the provided auth data for coordinator connection, joinCall REST, SFU WebSocket, and publishing. Publishing starts automatically after the SFU join response (no separate start/stop publish API).

Initialization

stream_video_init

Initialize the Stream Video SDK. Must be called before any other SDK functions.

stream_video_error_t stream_video_init(void);

Returns: STREAM_VIDEO_ERR_OK on success, or an error code.

stream_video_deinit

Deinitialize the Stream Video SDK.

void stream_video_deinit(void);

Join and leave

stream_video_join_call

Join a call using the SDK-managed flow (coordinator, joinCall REST, SFU connect). The app must pass auth data (from its token service) in params.auth_data. Publishing starts automatically after the SFU join response.

stream_video_error_t stream_video_join_call(
    const stream_video_join_call_params_t *params,
    stream_video_client_handle_t *client_out);

Parameters:

params – Join parameters (see below).
client_out – On success, receives the client handle.

Returns: STREAM_VIDEO_ERR_OK on success.

stream_video_join_call_params_t

Field	Type	Description
`auth_data`	`const stream_video_auth_data_t *`	Auth data from your token service (required). Must contain valid `user_id`, `api_key`, and `token`. The app obtains this; the SDK does not fetch tokens.
`call_type`	`const char *`	Call type (e.g. `"default"`).
`call_id`	`const char *`	Call ID; `NULL` to create a new call.
`create`	`bool`	If true, create the call if it does not exist.
`location`	`const char *`	Optional location hint; `NULL` for auto.
`result_cb`	`stream_video_join_result_cb_t`	Called with join success or failure (optional).
`user_data`	`void *`	User context for `result_cb`.
`mute_audio`	`bool`	If true, do not publish audio.
`mute_video`	`bool`	If true, do not publish video.

stream_video_leave_call

Leave the call and release resources. Stops publishing and disconnects from the SFU and coordinator.

stream_video_error_t stream_video_leave_call(stream_video_client_handle_t client);

Parameters: client – Handle returned from stream_video_join_call.

Error handling

stream_video_error_to_string

Get a human-readable string for an error code.

const char* stream_video_error_to_string(stream_video_error_t error);

stream_video_error_t

typedef enum {
    STREAM_VIDEO_ERR_OK = 0,
    STREAM_VIDEO_ERR_INVALID_ARG,
    STREAM_VIDEO_ERR_NO_MEM,
    STREAM_VIDEO_ERR_INVALID_STATE,
    STREAM_VIDEO_ERR_NETWORK,
    STREAM_VIDEO_ERR_TIMEOUT,
    STREAM_VIDEO_ERR_FAIL,
} stream_video_error_t;

stream_video_join_result_t

Passed to the join result callback:

typedef struct {
    bool success;
    char error_message[256];
} stream_video_join_result_t;

Types

stream_video_client_handle_t – Opaque handle for the Stream Video client (from stream_video_join_call).
stream_video_room_handle_t – Opaque handle for a room (reserved for future use).
stream_video_join_result_cb_t – Callback type for join result: void (*)(const stream_video_join_result_t *result, void *user_data).

SDK Configuration