# API Reference

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

## Contents

- [Essential API](#essential-api)
- [Initialization](#initialization)
- [Join and leave](#join-and-leave)
- [Error handling](#error-handling)
- [Types](#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:

1. **Initialize** – `stream_video_init()`
2. **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.
3. **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
4. **Leave call** – `stream_video_leave_call(client)`
5. **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.

```c
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.

```c
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.

```c
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.

```c
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.

```c
const char* stream_video_error_to_string(stream_video_error_t error);
```

### stream_video_error_t

```c
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:

```c
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)`.

---

For the most recent version of this documentation, visit [https://getstream.io/video/docs/esp32/guides/api-reference/](https://getstream.io/video/docs/esp32/guides/api-reference/).