IVS Linux Broadcast SDK (C) 1.49.0
Loading...
Searching...
No Matches
aws_ivs_realtime.h File Reference

Public C API for the IVS Linux Broadcast SDK. More...

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <aws_ivs_realtime_errors.h>

Go to the source code of this file.

Data Structures

struct  aws_ivs_realtime_subtitle_cue
struct  aws_ivs_realtime_participant_info
struct  aws_ivs_realtime_stage_event_callbacks
struct  aws_ivs_realtime_stage_strategy_callbacks

Macros

#define AWS_IVS_REALTIME_VERSION_MAJOR   1
#define AWS_IVS_REALTIME_VERSION_MINOR   49
#define AWS_IVS_REALTIME_VERSION_PATCH   0
#define AWS_IVS_REALTIME_VERSION_STRING   "1.49.0"
#define AWS_IVS_REALTIME_API
#define AWS_IVS_REALTIME_NODISCARD

Typedefs

typedef uint32_t aws_ivs_realtime_stream_type
typedef struct aws_ivs_realtime_audio_source aws_ivs_realtime_audio_source
typedef struct aws_ivs_realtime_channel_transcriber aws_ivs_realtime_channel_transcriber
typedef struct aws_ivs_realtime_local_subtitle_stream aws_ivs_realtime_local_subtitle_stream
typedef struct aws_ivs_realtime_stage aws_ivs_realtime_stage
typedef struct aws_ivs_realtime_publish_streams aws_ivs_realtime_publish_streams
typedef struct aws_ivs_realtime_stage_strategy aws_ivs_realtime_stage_strategy
typedef struct aws_ivs_realtime_stage_stream aws_ivs_realtime_stage_stream
typedef void(*) aws_ivs_realtime_cue_sent_cb(const aws_ivs_realtime_error *error, void *user_data)
 Reports what became of the one cue passed to the aws_ivs_realtime_local_subtitle_stream_send_cue call this callback was given to. A null error means the cue reached the transport, which is as far as delivery can be observed: the channel carries no acknowledgement, so this does not say a subscriber received the cue. Delivered on the same serialized thread as the strategy and every stage event callback. Since outcomes are reported asynchronously, this may be invoked after the local participant stops publishing the stream, including after the stream is reported removed through the stage event callbacks. Keep whatever the callback touches valid until the stream is destroyed.
typedef void(*) aws_ivs_realtime_audio_cb(const uint8_t *data, size_t data_size, size_t num_frames, size_t bytes_per_sample, size_t num_channels, uint32_t samples_per_sec, int64_t timestamp_ms, void *user_data)
 Receives interleaved mixed PCM from subscribed remote participants. Call aws_ivs_realtime_stage_set_audio_callback before aws_ivs_realtime_stage_join to register this callback. The SDK invokes it on a dedicated real-time audio thread, separate from the event callback thread. Keep the callback lock-free and return promptly. The buffer is read-only.
typedef void(*) aws_ivs_realtime_connection_state_changed_cb(aws_ivs_realtime_connection_state state, const aws_ivs_realtime_error *error, void *user_data)
 The Stage connection state changed.
typedef void(*) aws_ivs_realtime_participant_joined_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)
 A participant joined the Stage.
typedef void(*) aws_ivs_realtime_participant_left_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)
 A participant left the Stage or stopped publishing.
typedef void(*) aws_ivs_realtime_participant_metadata_updated_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)
 A participant's metadata changed (user_id or attributes). The participant snapshot is a new value sharing participant_id and is_local with the prior snapshot.
typedef void(*) aws_ivs_realtime_participant_publish_state_changed_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_publish_state publish_state, void *user_data)
 A participant's publish state changed.
typedef void(*) aws_ivs_realtime_participant_subscribe_state_changed_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_subscribe_state subscribe_state, void *user_data)
 The local participant's subscribe state changed with respect to a remote publisher. Fires only for the local participant's own subscription changes.
typedef void(*) aws_ivs_realtime_streams_added_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_stage_stream *const *streams, size_t streams_count, void *user_data)
 A participant added streams. For a remote participant this is the result of a subscription taking effect. For the local participant these are the streams the strategy asked to publish.
typedef void(*) aws_ivs_realtime_streams_removed_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_stage_stream *const *streams, size_t streams_count, void *user_data)
 A participant removed streams. They could have unpublished, stopped sharing a certain stream type, or left the stage.
typedef void(*) aws_ivs_realtime_streams_muted_changed_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_stage_stream *const *streams, size_t streams_count, void *user_data)
 One or more streams changed mute state.
typedef void(*) aws_ivs_realtime_error_cb(const aws_ivs_realtime_error *error, void *user_data)
 An asynchronous error that does not change the connection state. The Stage stays connected. It may reflect a failed publish, a failed subscribe, or another operation that went wrong while the connection remained up. Errors that do change the connection (for example a disconnect) are delivered through on_connection_state_changed instead, not here.
typedef aws_ivs_realtime_stream_type(*) aws_ivs_realtime_subscription_types_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)
 Ask which stream types to subscribe to from a participant. Return NONE (0) to skip the participant, or AUDIO to receive its audio. Only AUDIO is honored today. Invoked for each remote participant when first seen and whenever aws_ivs_realtime_stage_refresh_strategy is called, provided the local participant is permitted to subscribe. This callback is not invoked for the local participant.
typedef bool(*) aws_ivs_realtime_should_publish_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)
 Ask whether to publish as a participant. Return true to publish, false to stop publishing. Invoked for the local participant on joining and whenever aws_ivs_realtime_stage_refresh_strategy is called, provided the participant token permits publishing. Returning true leads to a streams_to_publish call for the same participant.
typedef void(*) aws_ivs_realtime_streams_to_publish_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_publish_streams *streams, void *user_data)
 Name what to publish as a participant. Invoked after should_publish returns true for the same participant. Call the aws_ivs_realtime_publish_streams_* functions on the collector to name each stream to publish, and leave a stream unnamed to not publish it. If what this callback names changes, call aws_ivs_realtime_stage_refresh_strategy to publish the new answer. The SDK compares what is named against what it is already publishing: naming a stream it already has is a no-op, and leaving one unnamed stops publishing it. should_publish_cb controls whether the participant publishes at all; leaving a stream unnamed here stops that stream, not the participant's publishing state.

Enumerations

enum  aws_ivs_realtime_connection_state { AWS_IVS_REALTIME_CONNECTION_STATE_DISCONNECTED = 0 , AWS_IVS_REALTIME_CONNECTION_STATE_CONNECTING = 1 , AWS_IVS_REALTIME_CONNECTION_STATE_CONNECTED = 2 }
enum  aws_ivs_realtime_publish_state { AWS_IVS_REALTIME_PUBLISH_STATE_NOT_PUBLISHED = 0 , AWS_IVS_REALTIME_PUBLISH_STATE_ATTEMPTING_PUBLISH = 1 , AWS_IVS_REALTIME_PUBLISH_STATE_PUBLISHED = 2 }
enum  aws_ivs_realtime_subscribe_state { AWS_IVS_REALTIME_SUBSCRIBE_STATE_NOT_SUBSCRIBED = 0 , AWS_IVS_REALTIME_SUBSCRIBE_STATE_ATTEMPTING_SUBSCRIBE = 1 , AWS_IVS_REALTIME_SUBSCRIBE_STATE_SUBSCRIBED = 2 }
enum  { AWS_IVS_REALTIME_STREAM_TYPE_NONE = 0 , AWS_IVS_REALTIME_STREAM_TYPE_AUDIO = 1 , AWS_IVS_REALTIME_STREAM_TYPE_VIDEO = 2 , AWS_IVS_REALTIME_STREAM_TYPE_SUBTITLE = 4 }
enum  aws_ivs_realtime_pcm_format {
  AWS_IVS_REALTIME_PCM_FORMAT_S16_INTERLEAVED = 0 , AWS_IVS_REALTIME_PCM_FORMAT_S16_PLANAR = 1 , AWS_IVS_REALTIME_PCM_FORMAT_F32_INTERLEAVED = 2 , AWS_IVS_REALTIME_PCM_FORMAT_F32_PLANAR = 3 ,
  AWS_IVS_REALTIME_PCM_FORMAT_S32_INTERLEAVED = 4 , AWS_IVS_REALTIME_PCM_FORMAT_S32_PLANAR = 5 , AWS_IVS_REALTIME_PCM_FORMAT_F64_INTERLEAVED = 6 , AWS_IVS_REALTIME_PCM_FORMAT_F64_PLANAR = 7
}

Functions

AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_audio_source_create (uint32_t samples_per_sec, size_t num_channels, aws_ivs_realtime_pcm_format format, aws_ivs_realtime_audio_source **out_audio_source, aws_ivs_realtime_error **out_error)
 Create an audio source. samples_per_sec, num_channels, and format describe every buffer you push to it.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_audio_source_push_buffer (aws_ivs_realtime_audio_source *audio_source, const uint8_t *data, size_t data_size, size_t num_frames, int64_t pts, aws_ivs_realtime_error **out_error)
 Push one buffer of PCM to publish. The SDK copies the buffer before returning. Push in real time, as the audio is produced. The SDK does not pace audio, so it drops audio pushed faster than real time. If no joined Stage is publishing this source, the SDK discards the push. Safe to call from any thread, but push from one thread at a time.
AWS_IVS_REALTIME_API void aws_ivs_realtime_audio_source_destroy (aws_ivs_realtime_audio_source *audio_source)
 Free an audio source handle. Idempotent on null. You can destroy a source that a Stage is publishing; the stream stays published and delivers silence.
AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_channel_transcriber_create (const char *participant_id, aws_ivs_realtime_channel_transcriber **out_channel_transcriber, aws_ivs_realtime_error **out_error)
 Create a channel transcriber for one remote participant. It owns a stage strategy, retrieved with aws_ivs_realtime_channel_transcriber_get_strategy, that you pass to aws_ivs_realtime_stage_create; that strategy subscribes to audio from participant_id and no other remote participant.
AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_channel_transcriber_get_strategy (aws_ivs_realtime_channel_transcriber *channel_transcriber, aws_ivs_realtime_stage_strategy **out_stage_strategy, aws_ivs_realtime_error **out_error)
 Return the stage strategy owned by this transcriber, for passing to aws_ivs_realtime_stage_create.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_channel_transcriber_write_transcription (aws_ivs_realtime_channel_transcriber *channel_transcriber, int64_t start_ms, int64_t end_ms, const char *language_code, const char *text, const char *utterance_id, aws_ivs_realtime_error **out_error)
 Submit a transcription result for delivery to the Stage. Safe to call from any thread. The text is attributed to the remote participant whose audio the Stage is subscribed to, so exactly one such participant must be identifiable.
AWS_IVS_REALTIME_API void aws_ivs_realtime_channel_transcriber_destroy (aws_ivs_realtime_channel_transcriber *channel_transcriber)
 Free a channel transcriber handle. Idempotent on null. Destroy any Stage still using this transcriber's strategy before destroying the transcriber.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_get_version (const char **out_version, aws_ivs_realtime_error **out_error)
 Retrieve the SDK version string, a NUL-terminated UTF-8 string.
AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_local_subtitle_stream_create (aws_ivs_realtime_local_subtitle_stream **out_local_subtitle_stream, aws_ivs_realtime_error **out_error)
 Create a subtitle stream. It publishes nothing until a strategy names it in aws_ivs_realtime_publish_streams.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_local_subtitle_stream_get_stream_id (aws_ivs_realtime_local_subtitle_stream *local_subtitle_stream, const char **out_stream_id, aws_ivs_realtime_error **out_error)
 The stream's identifier, fixed for its lifetime and unique within the Stage. It matches the id on the stage_stream the streams-added event delivers for this stream.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_local_subtitle_stream_send_cue (aws_ivs_realtime_local_subtitle_stream *local_subtitle_stream, const aws_ivs_realtime_subtitle_cue *cue, aws_ivs_realtime_cue_sent_cb callback, void *user_data, aws_ivs_realtime_error **out_error)
 Send one subtitle cue. A synchronous failure does not call callback. A successful return means the SDK accepted the cue for processing, not that it was sent or reached the transport. Everything past that point, success or failure, is reported on callback: the SDK invokes it exactly once and does not retain it afterward. Safe to call from any thread.
AWS_IVS_REALTIME_API void aws_ivs_realtime_local_subtitle_stream_destroy (aws_ivs_realtime_local_subtitle_stream *local_subtitle_stream)
 Free a subtitle stream handle. Idempotent on null. Destroying a stream a Stage is publishing stops that stream; the Stage keeps publishing everything else. Reports every cue this stream still owes an outcome for before returning, so no callback is lost with the handle. Those callbacks run on the same serialized thread as the strategy and every stage event callback, so this must not be called from within a callback.
AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_create (const char *token, aws_ivs_realtime_stage_strategy *stage_strategy, const aws_ivs_realtime_stage_event_callbacks *stage_event_callbacks, aws_ivs_realtime_stage **out_stage, aws_ivs_realtime_error **out_error)
 Create a Stage from a valid IVS Stage participant token. This does not connect to the Stage; call aws_ivs_realtime_stage_join to connect. The strategy and event callbacks remain associated with the Stage until it is destroyed.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_set_audio_callback (aws_ivs_realtime_stage *stage, aws_ivs_realtime_audio_cb callback, void *user_data, aws_ivs_realtime_error **out_error)
 Register the mixed-PCM audio callback. Call this before aws_ivs_realtime_stage_join or after aws_ivs_realtime_stage_leave. The callback persists across leave/join cycles and is cleared by aws_ivs_realtime_stage_destroy. Passing a null callback clears it.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_join (aws_ivs_realtime_stage *stage, aws_ivs_realtime_error **out_error)
 Connect to the Stage associated with the token and begin the callback flow. Connection progress is reported via on_connection_state_changed.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_refresh_strategy (aws_ivs_realtime_stage *stage, aws_ivs_realtime_error **out_error)
 Ask the SDK to re-query the strategy. Every strategy callback is invoked again for the participants it applies to, and subscriptions and published streams are updated to match the new answers. Safe to call from within a callback.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_leave (aws_ivs_realtime_stage *stage, aws_ivs_realtime_error **out_error)
 Leave the Stage. A no-op if not joined. The connection transitions to DISCONNECTED. The handle remains valid and may be re-joined.
AWS_IVS_REALTIME_API void aws_ivs_realtime_stage_destroy (aws_ivs_realtime_stage *stage)
 Leave if necessary and free the handle. Idempotent on null. Must be called exactly once for each successfully created handle. Must not be called from within a callback.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_publish_streams_set_audio (aws_ivs_realtime_publish_streams *publish_streams, aws_ivs_realtime_audio_source *audio, aws_ivs_realtime_error **out_error)
 Publish audio from this source. Passing null publishes no audio. Calling this more than once replaces the source named by the previous call, so the last call wins.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_publish_streams_add_subtitle_stream (aws_ivs_realtime_publish_streams *publish_streams, aws_ivs_realtime_local_subtitle_stream *subtitle_stream, aws_ivs_realtime_error **out_error)
 Publish subtitle cues from this stream. Naming the same stream twice adds it once. A Stage can publish multiple subtitle streams.
AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_strategy_create (const aws_ivs_realtime_stage_strategy_callbacks *callbacks, aws_ivs_realtime_stage_strategy **out_stage_strategy, aws_ivs_realtime_error **out_error)
 Create a stage strategy backed by application callbacks. Every required callback in the table must be non-null.
AWS_IVS_REALTIME_API void aws_ivs_realtime_stage_strategy_destroy (aws_ivs_realtime_stage_strategy *stage_strategy)
 Free a stage strategy handle. Idempotent on null. Destroy any Stage still using a stage strategy before destroying the stage strategy.
AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_clone (aws_ivs_realtime_stage_stream *source, aws_ivs_realtime_stage_stream **out_stage_stream, aws_ivs_realtime_error **out_error)
 Retain a stream past the callback that delivered it. The result refers to the same stream and keeps answering after that stream ends, which is what makes it safe to hold: getters continue to work and aws_ivs_realtime_stage_stream_set_audio_callback fails. Cloning never fails for a live handle.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_get_stream_id (aws_ivs_realtime_stage_stream *stage_stream, const char **out_stream_id, aws_ivs_realtime_error **out_error)
 The stream's identifier, fixed for its lifetime and unique within the Stage. Two handles name the same stream when their IDs match.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_get_stream_type (aws_ivs_realtime_stage_stream *stage_stream, aws_ivs_realtime_stream_type *out_stream_type, aws_ivs_realtime_error **out_error)
 The kind of content this stream carries. This applies to a published stream and to a subscribed stream. Exactly one bit is set.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_get_is_muted (aws_ivs_realtime_stage_stream *stage_stream, bool *out_is_muted, aws_ivs_realtime_error **out_error)
 Whether the stream is muted on the Stage, meaning no media reaches any subscriber. This is not local playback state. Reading it reports the current value, including for a stream that was already muted when it was first reported, which on_streams_muted_changed does not cover because it fires only on a change.
AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_set_audio_callback (aws_ivs_realtime_stage_stream *stage_stream, aws_ivs_realtime_audio_cb callback, void *user_data, aws_ivs_realtime_error **out_error)
 Register a callback receiving only this stream's audio, before it is mixed with any other participant's. Audio streams only. Passing a null callback clears the registration, and registering again replaces it. Call this on the handle the event delivered; cloning first is unnecessary. The registration belongs to the stream rather than to the handle, so it keeps delivering after the callback returns. Clone only to call into the stream from somewhere else later, such as reading its mute state or clearing the callback from your own code. A registration lasts as long as the stream. Register from on_streams_added, because a stream that ends is reported through on_streams_removed and replaced by a new stream with a new ID that needs its own registration. Every registered stream callback shares one real-time audio thread with each other and with the mixed callback from aws_ivs_realtime_stage_set_audio_callback, so a slow callback delays audio for every participant, not just this one.
AWS_IVS_REALTIME_API void aws_ivs_realtime_stage_stream_destroy (aws_ivs_realtime_stage_stream *stage_stream)
 Release a handle from aws_ivs_realtime_stage_stream_clone. Null is a no-op. Do not pass a handle delivered to an event callback; those are borrowed. Safe to call from any thread including an event callback: it does not block and does not run application code.
AWS_IVS_REALTIME_API void aws_ivs_realtime_error_destroy (aws_ivs_realtime_error *error)
 Free an error returned through an out_error parameter. Idempotent on null. Never pass an error received in a callback; the SDK owns those.

Detailed Description

Public C API for the IVS Linux Broadcast SDK.

All symbols use the aws_ivs_realtime_ prefix (macros/enum members use AWS_IVS_REALTIME_).

Unless a callback says otherwise, SDK functions may be called from SDK callbacks, except aws_ivs_realtime_stage_destroy().

Each function's Errors list names the errors a caller can handle specifically. It is not exhaustive. For any other error, is_fatal says whether the Stage can still be used; code and message identify the failure when reporting it.

Macro Definition Documentation

◆ AWS_IVS_REALTIME_API

#define AWS_IVS_REALTIME_API

Exports a function from the shared library.

◆ AWS_IVS_REALTIME_NODISCARD

#define AWS_IVS_REALTIME_NODISCARD

Marks a function whose result must not be ignored.

◆ AWS_IVS_REALTIME_VERSION_MAJOR

#define AWS_IVS_REALTIME_VERSION_MAJOR   1

Major version of this header.

◆ AWS_IVS_REALTIME_VERSION_MINOR

#define AWS_IVS_REALTIME_VERSION_MINOR   49

Minor version of this header.

◆ AWS_IVS_REALTIME_VERSION_PATCH

#define AWS_IVS_REALTIME_VERSION_PATCH   0

Patch version of this header.

◆ AWS_IVS_REALTIME_VERSION_STRING

#define AWS_IVS_REALTIME_VERSION_STRING   "1.49.0"

Version of this header as a string.

Typedef Documentation

◆ aws_ivs_realtime_audio_cb

typedef void(*) aws_ivs_realtime_audio_cb(const uint8_t *data, size_t data_size, size_t num_frames, size_t bytes_per_sample, size_t num_channels, uint32_t samples_per_sec, int64_t timestamp_ms, void *user_data)

Receives interleaved mixed PCM from subscribed remote participants. Call aws_ivs_realtime_stage_set_audio_callback before aws_ivs_realtime_stage_join to register this callback. The SDK invokes it on a dedicated real-time audio thread, separate from the event callback thread. Keep the callback lock-free and return promptly. The buffer is read-only.

Parameters
dataInterleaved PCM samples. The companion byte count satisfies data_size == num_frames * num_channels * bytes_per_sample, and total_samples == num_frames * num_channels. Valid only until this callback returns; copy it to retain it.
data_sizeSize of data in bytes.
num_framesNumber of frames; each frame has one sample per channel.
bytes_per_sample2 for S16, 4 for Float32.
num_channels1 for mono, 2 for stereo.
samples_per_secSample rate in Hz, e.g. 48000.
timestamp_msPresentation timestamp in milliseconds, monotonically increasing from the start of audio playout.
user_dataApplication pointer supplied when registering the callback.
Note
Do not call SDK functions from this callback.

◆ aws_ivs_realtime_audio_source

Opaque handle for an audio source. An application uses it to publish its own audio. Create an audio source, name it in the aws_ivs_realtime_publish_streams that the strategy's streams_to_publish callback receives, then push PCM to it with aws_ivs_realtime_audio_source_push_buffer. Application-owned handle; release it with aws_ivs_realtime_audio_source_destroy().

◆ aws_ivs_realtime_channel_transcriber

Opaque handle to a channel transcriber. A channel transcriber owns a stage strategy that makes it easy to subscribe to audio from one remote participant, and it accepts transcription results to deliver to the Stage. Create one, pass its strategy (from aws_ivs_realtime_channel_transcriber_get_strategy) to aws_ivs_realtime_stage_create, then submit results with aws_ivs_realtime_channel_transcriber_write_transcription. Application-owned handle; release it with aws_ivs_realtime_channel_transcriber_destroy().

◆ aws_ivs_realtime_connection_state_changed_cb

typedef void(*) aws_ivs_realtime_connection_state_changed_cb(aws_ivs_realtime_connection_state state, const aws_ivs_realtime_error *error, void *user_data)

The Stage connection state changed.

Parameters
stateThe new connection state.
errorThe error that caused the transition, or null for an expected transition. Valid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_cue_sent_cb

typedef void(*) aws_ivs_realtime_cue_sent_cb(const aws_ivs_realtime_error *error, void *user_data)

Reports what became of the one cue passed to the aws_ivs_realtime_local_subtitle_stream_send_cue call this callback was given to. A null error means the cue reached the transport, which is as far as delivery can be observed: the channel carries no acknowledgement, so this does not say a subscriber received the cue. Delivered on the same serialized thread as the strategy and every stage event callback. Since outcomes are reported asynchronously, this may be invoked after the local participant stops publishing the stream, including after the stream is reported removed through the stage event callbacks. Keep whatever the callback touches valid until the stream is destroyed.

Parameters
errorWhy the cue was not sent, for example that it exceeded the size limit, that it was refused by the rate limit, or that the participant is not publishing. Null when the cue reached the transport. Valid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_error_cb

typedef void(*) aws_ivs_realtime_error_cb(const aws_ivs_realtime_error *error, void *user_data)

An asynchronous error that does not change the connection state. The Stage stays connected. It may reflect a failed publish, a failed subscribe, or another operation that went wrong while the connection remained up. Errors that do change the connection (for example a disconnect) are delivered through on_connection_state_changed instead, not here.

Parameters
errorThe asynchronous error. This callback is not invoked with a null error. Valid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_local_subtitle_stream

Opaque handle to a local subtitle stream. An application uses it to author subtitle cues for either itself, or for another participant in the stage. Create a subtitle stream. Name it with aws_ivs_realtime_publish_streams_add_subtitle_stream in the streams_to_publish strategy callback. Then send cues with aws_ivs_realtime_local_subtitle_stream_send_cue. A subtitle stream carries no media, so a Stage can publish any number of them at once, and publishing one does not make the participant an audio or video publisher. Application- owned handle; release it with aws_ivs_realtime_local_subtitle_stream_destroy().

◆ aws_ivs_realtime_participant_joined_cb

typedef void(*) aws_ivs_realtime_participant_joined_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)

A participant joined the Stage.

Parameters
participantValid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_participant_left_cb

typedef void(*) aws_ivs_realtime_participant_left_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)

A participant left the Stage or stopped publishing.

Parameters
participantValid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_participant_metadata_updated_cb

typedef void(*) aws_ivs_realtime_participant_metadata_updated_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)

A participant's metadata changed (user_id or attributes). The participant snapshot is a new value sharing participant_id and is_local with the prior snapshot.

Parameters
participantValid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_participant_publish_state_changed_cb

typedef void(*) aws_ivs_realtime_participant_publish_state_changed_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_publish_state publish_state, void *user_data)

A participant's publish state changed.

Parameters
participantValid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_participant_subscribe_state_changed_cb

typedef void(*) aws_ivs_realtime_participant_subscribe_state_changed_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_subscribe_state subscribe_state, void *user_data)

The local participant's subscribe state changed with respect to a remote publisher. Fires only for the local participant's own subscription changes.

Parameters
participantThe publishing participant the local participant's subscription changed for. Valid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_publish_streams

The set of streams a Stage publishes. The SDK provides one to the streams_to_publish strategy callback, and it is valid only for the duration of that callback, so do not store it. A Stage publishes at most one audio source, and any number of subtitle streams.

◆ aws_ivs_realtime_should_publish_cb

typedef bool(*) aws_ivs_realtime_should_publish_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)

Ask whether to publish as a participant. Return true to publish, false to stop publishing. Invoked for the local participant on joining and whenever aws_ivs_realtime_stage_refresh_strategy is called, provided the participant token permits publishing. Returning true leads to a streams_to_publish call for the same participant.

Parameters
participantThe participant in question. Valid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.
Returns
A bool value.

◆ aws_ivs_realtime_stage

Opaque handle to a Stage instance. Do not use the same Stage handle concurrently from multiple application threads. Application-owned handle; release it with aws_ivs_realtime_stage_destroy().

◆ aws_ivs_realtime_stage_strategy

Opaque handle to a stage strategy. The stage strategy is the decision engine associated with a Stage. It is how the Stage asks the host application what actions to take. If the host application wants to change their answer to a question, they can call aws_ivs_realtime_stage_refresh_strategy on the Stage. Application-owned handle; release it with aws_ivs_realtime_stage_strategy_destroy().

◆ aws_ivs_realtime_stage_stream

A single stream of one type, belonging to one participant. Stage events deliver borrowed handles, valid only for the callback that receives them; use aws_ivs_realtime_stage_stream_clone to keep one longer. Compare streams by stream ID rather than by handle pointer, because a clone is a different pointer to the same stream. Do not use one handle concurrently from multiple application threads. Application-owned handle; release it with aws_ivs_realtime_stage_stream_destroy().

◆ aws_ivs_realtime_stream_type

typedef uint32_t aws_ivs_realtime_stream_type

Bitmask of stream types. Each stream, published or subscribed, reports exactly one bit. A strategy returns the set of stream types it wants to subscribe to.

◆ aws_ivs_realtime_streams_added_cb

typedef void(*) aws_ivs_realtime_streams_added_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_stage_stream *const *streams, size_t streams_count, void *user_data)

A participant added streams. For a remote participant this is the result of a subscription taking effect. For the local participant these are the streams the strategy asked to publish.

Parameters
participantValid only until this callback returns; copy it to retain it.
streamsThe added streams. Clone one to use it after this callback returns. Valid only until this callback returns; copy it to retain it.
streams_countNumber of entries in streams.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_streams_muted_changed_cb

typedef void(*) aws_ivs_realtime_streams_muted_changed_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_stage_stream *const *streams, size_t streams_count, void *user_data)

One or more streams changed mute state.

Parameters
participantValid only until this callback returns; copy it to retain it.
streamsThe streams whose mute state changed. Valid only until this callback returns; copy it to retain it.
streams_countNumber of entries in streams.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_streams_removed_cb

typedef void(*) aws_ivs_realtime_streams_removed_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_stage_stream *const *streams, size_t streams_count, void *user_data)

A participant removed streams. They could have unpublished, stopped sharing a certain stream type, or left the stage.

Parameters
participantValid only until this callback returns; copy it to retain it.
streamsThe removed streams. Retained clones stay valid but become inert. Valid only until this callback returns; copy it to retain it.
streams_countNumber of entries in streams.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_streams_to_publish_cb

typedef void(*) aws_ivs_realtime_streams_to_publish_cb(const aws_ivs_realtime_participant_info *participant, aws_ivs_realtime_publish_streams *streams, void *user_data)

Name what to publish as a participant. Invoked after should_publish returns true for the same participant. Call the aws_ivs_realtime_publish_streams_* functions on the collector to name each stream to publish, and leave a stream unnamed to not publish it. If what this callback names changes, call aws_ivs_realtime_stage_refresh_strategy to publish the new answer. The SDK compares what is named against what it is already publishing: naming a stream it already has is a no-op, and leaving one unnamed stops publishing it. should_publish_cb controls whether the participant publishes at all; leaving a stream unnamed here stops that stream, not the participant's publishing state.

Parameters
participantThe participant the streams will be published as. Valid only until this callback returns; copy it to retain it.
streamsThe collector to name the streams in. Owned by the SDK and valid only until this callback returns; do not store or destroy it.
user_dataApplication pointer supplied when registering the callback.

◆ aws_ivs_realtime_subscription_types_cb

typedef aws_ivs_realtime_stream_type(*) aws_ivs_realtime_subscription_types_cb(const aws_ivs_realtime_participant_info *participant, void *user_data)

Ask which stream types to subscribe to from a participant. Return NONE (0) to skip the participant, or AUDIO to receive its audio. Only AUDIO is honored today. Invoked for each remote participant when first seen and whenever aws_ivs_realtime_stage_refresh_strategy is called, provided the local participant is permitted to subscribe. This callback is not invoked for the local participant.

Parameters
participantThe participant in question. Valid only until this callback returns; copy it to retain it.
user_dataApplication pointer supplied when registering the callback.
Returns
Bitmask of stream types. Each stream, published or subscribed, reports exactly one bit. A strategy returns the set of stream types it wants to subscribe to.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
AWS_IVS_REALTIME_STREAM_TYPE_NONE 

The empty set. No stream reports this.

AWS_IVS_REALTIME_STREAM_TYPE_AUDIO 

Audio (bit 0).

AWS_IVS_REALTIME_STREAM_TYPE_VIDEO 

Video (bit 1).

AWS_IVS_REALTIME_STREAM_TYPE_SUBTITLE 

Subtitles (bit 2).

◆ aws_ivs_realtime_connection_state

Connection state of a Stage.

Enumerator
AWS_IVS_REALTIME_CONNECTION_STATE_DISCONNECTED 

Not connected to a Stage.

AWS_IVS_REALTIME_CONNECTION_STATE_CONNECTING 

Establishing a connection.

AWS_IVS_REALTIME_CONNECTION_STATE_CONNECTED 

Connected.

◆ aws_ivs_realtime_pcm_format

Sample format of raw PCM. Interleaved formats store each frame's channels together; planar formats store one whole channel after another.

Enumerator
AWS_IVS_REALTIME_PCM_FORMAT_S16_INTERLEAVED 

Signed 16-bit integer, interleaved.

AWS_IVS_REALTIME_PCM_FORMAT_S16_PLANAR 

Signed 16-bit integer, planar.

AWS_IVS_REALTIME_PCM_FORMAT_F32_INTERLEAVED 

32-bit float, interleaved.

AWS_IVS_REALTIME_PCM_FORMAT_F32_PLANAR 

32-bit float, planar.

AWS_IVS_REALTIME_PCM_FORMAT_S32_INTERLEAVED 

Signed 32-bit integer, interleaved.

AWS_IVS_REALTIME_PCM_FORMAT_S32_PLANAR 

Signed 32-bit integer, planar.

AWS_IVS_REALTIME_PCM_FORMAT_F64_INTERLEAVED 

64-bit float, interleaved.

AWS_IVS_REALTIME_PCM_FORMAT_F64_PLANAR 

64-bit float, planar.

◆ aws_ivs_realtime_publish_state

Publish state of a participant.

Enumerator
AWS_IVS_REALTIME_PUBLISH_STATE_NOT_PUBLISHED 

Not publishing and not attempting to.

AWS_IVS_REALTIME_PUBLISH_STATE_ATTEMPTING_PUBLISH 

Attempting to publish.

AWS_IVS_REALTIME_PUBLISH_STATE_PUBLISHED 

Publishing.

◆ aws_ivs_realtime_subscribe_state

The local participant's subscribe state with respect to a remote publisher.

Enumerator
AWS_IVS_REALTIME_SUBSCRIBE_STATE_NOT_SUBSCRIBED 

Not subscribed.

AWS_IVS_REALTIME_SUBSCRIBE_STATE_ATTEMPTING_SUBSCRIBE 

Establishing a subscription.

AWS_IVS_REALTIME_SUBSCRIBE_STATE_SUBSCRIBED 

Subscribed.

Function Documentation

◆ aws_ivs_realtime_audio_source_create()

AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_audio_source_create ( uint32_t samples_per_sec,
size_t num_channels,
aws_ivs_realtime_pcm_format format,
aws_ivs_realtime_audio_source ** out_audio_source,
aws_ivs_realtime_error ** out_error )

Create an audio source. samples_per_sec, num_channels, and format describe every buffer you push to it.

Parameters
samples_per_secSample rate in Hz of pushed audio, for example 48000. Must be between 8000 and 96000.
num_channelsChannel count of pushed audio. 1 for mono, 2 for stereo.
formatSample format of pushed audio.
out_audio_sourceOn success, receives an application-owned audio_source handle; release it with aws_ivs_realtime_audio_source_destroy(). Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_audio_source is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when samples_per_sec is outside 8000-96000.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when num_channels is not 1 or 2.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when format is not a pcm_format value.

◆ aws_ivs_realtime_audio_source_destroy()

AWS_IVS_REALTIME_API void aws_ivs_realtime_audio_source_destroy ( aws_ivs_realtime_audio_source * audio_source)

Free an audio source handle. Idempotent on null. You can destroy a source that a Stage is publishing; the stream stays published and delivers silence.

Parameters
audio_sourceOwned by the application and released by this call; null is a no-op.
Note
Do not call this concurrently with any other function on the same handle.

◆ aws_ivs_realtime_audio_source_push_buffer()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_audio_source_push_buffer ( aws_ivs_realtime_audio_source * audio_source,
const uint8_t * data,
size_t data_size,
size_t num_frames,
int64_t pts,
aws_ivs_realtime_error ** out_error )

Push one buffer of PCM to publish. The SDK copies the buffer before returning. Push in real time, as the audio is produced. The SDK does not pace audio, so it drops audio pushed faster than real time. If no joined Stage is publishing this source, the SDK discards the push. Safe to call from any thread, but push from one thread at a time.

Parameters
audio_sourceThe application keeps ownership.
dataPCM samples in the source's format, where data_size == num_frames * num_channels * bytes-per-sample of that format.
data_sizeSize of data in bytes.
num_framesNumber of frames; each frame has one sample per channel.
ptsPresentation timestamp of the buffer's first frame, counted in frames at samples_per_sec. The origin is arbitrary; the first push sets it. Contiguous audio advances pts by num_frames per push. A jump in pts creates a gap, and the SDK fills that gap with silence.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when audio_source is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when data is null.
  • AWS_IVS_REALTIME_ERROR_CODE_AUDIO_SOURCE_BUFFER_SIZE_MISMATCH when data_size is not num_frames * num_channels * bytes-per-sample of the source's format.

◆ aws_ivs_realtime_channel_transcriber_create()

AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_channel_transcriber_create ( const char * participant_id,
aws_ivs_realtime_channel_transcriber ** out_channel_transcriber,
aws_ivs_realtime_error ** out_error )

Create a channel transcriber for one remote participant. It owns a stage strategy, retrieved with aws_ivs_realtime_channel_transcriber_get_strategy, that you pass to aws_ivs_realtime_stage_create; that strategy subscribes to audio from participant_id and no other remote participant.

Parameters
participant_idThe remote participant to subscribe to and transcribe. Must be non-empty. Used only for this call; the SDK copies anything it retains.
out_channel_transcriberOn success, receives an application-owned channel_transcriber handle; release it with aws_ivs_realtime_channel_transcriber_destroy(). Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when participant_id is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_channel_transcriber is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when participant_id is empty.

◆ aws_ivs_realtime_channel_transcriber_destroy()

AWS_IVS_REALTIME_API void aws_ivs_realtime_channel_transcriber_destroy ( aws_ivs_realtime_channel_transcriber * channel_transcriber)

Free a channel transcriber handle. Idempotent on null. Destroy any Stage still using this transcriber's strategy before destroying the transcriber.

Parameters
channel_transcriberOwned by the application and released by this call; null is a no-op.
Note
Do not call this concurrently with any other function on the same handle.

◆ aws_ivs_realtime_channel_transcriber_get_strategy()

AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_channel_transcriber_get_strategy ( aws_ivs_realtime_channel_transcriber * channel_transcriber,
aws_ivs_realtime_stage_strategy ** out_stage_strategy,
aws_ivs_realtime_error ** out_error )

Return the stage strategy owned by this transcriber, for passing to aws_ivs_realtime_stage_create.

Parameters
channel_transcriberThe application keeps ownership.
out_stage_strategyOn success, receives a stage_strategy handle owned by the channel_transcriber; do not destroy it. It stays valid until the channel_transcriber is destroyed. Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when channel_transcriber is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_stage_strategy is null.

◆ aws_ivs_realtime_channel_transcriber_write_transcription()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_channel_transcriber_write_transcription ( aws_ivs_realtime_channel_transcriber * channel_transcriber,
int64_t start_ms,
int64_t end_ms,
const char * language_code,
const char * text,
const char * utterance_id,
aws_ivs_realtime_error ** out_error )

Submit a transcription result for delivery to the Stage. Safe to call from any thread. The text is attributed to the remote participant whose audio the Stage is subscribed to, so exactly one such participant must be identifiable.

Parameters
channel_transcriberThe application keeps ownership.
start_msStart timestamp of the text, in milliseconds, on the same timeline as the audio callback's timestamp_ms parameter.
end_msEnd timestamp of the text, in milliseconds, on the same timeline as start_ms. Must be greater than start_ms.
language_codeA language identifier for the transcript, opaque to the SDK: it is carried through to the receiver unmodified and unvalidated, so any non-empty scheme both ends agree on works. Do not assume BCP-47, ISO 639-1, or ISO 639-2; pick a scheme with the receiver. Used only for this call; the SDK copies anything it retains.
textUTF-8 transcription text. Used only for this call; the SDK copies anything it retains.
utterance_idCaller-assigned identifier aggregating the partials of one utterance across writes, so a receiver can de- duplicate partials for the same utterance even as start_ms shifts between them. Null is treated the same as an empty string. When empty, the SDK uses start_ms as the ID. Avoid IDs that reset or repeat, such as a per- connection sequence number. If a transcription service assigns each result the next number starting from 0, and a network drop makes your app reconnect, the new connection also starts counting from 0. The receiver then sees the same ID twice for two different utterances. Used only for this call; the SDK copies anything it retains.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when channel_transcriber is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when language_code is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when text is null.
  • AWS_IVS_REALTIME_ERROR_CODE_CHANNEL_TRANSCRIBER_NOT_ATTACHED when this transcriber's strategy has not yet been passed to a Stage.
  • AWS_IVS_REALTIME_ERROR_CODE_CHANNEL_TRANSCRIPTION_INVALID_TIME_RANGE when end_ms is not greater than start_ms.
  • AWS_IVS_REALTIME_ERROR_CODE_CHANNEL_TRANSCRIPTION_NO_PARTICIPANT when no participant has subscribed audio to attribute the text to.
  • AWS_IVS_REALTIME_ERROR_CODE_CHANNEL_TRANSCRIPTION_STALE when start_ms lags the live audio position by more than 60 seconds.
  • AWS_IVS_REALTIME_ERROR_CODE_CHANNEL_TRANSCRIPTION_CAPTURE_TIME_UNAVAILABLE when delivery timing could not be established for the participant's audio stream.

◆ aws_ivs_realtime_error_destroy()

AWS_IVS_REALTIME_API void aws_ivs_realtime_error_destroy ( aws_ivs_realtime_error * error)

Free an error returned through an out_error parameter. Idempotent on null. Never pass an error received in a callback; the SDK owns those.

Parameters
errorThe error to free.

◆ aws_ivs_realtime_get_version()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_get_version ( const char ** out_version,
aws_ivs_realtime_error ** out_error )

Retrieve the SDK version string, a NUL-terminated UTF-8 string.

Parameters
out_versionOn success, receives an SDK-owned string pointer that remains valid until the library is unloaded. Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
A bool value.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_version is null.

◆ aws_ivs_realtime_local_subtitle_stream_create()

AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_local_subtitle_stream_create ( aws_ivs_realtime_local_subtitle_stream ** out_local_subtitle_stream,
aws_ivs_realtime_error ** out_error )

Create a subtitle stream. It publishes nothing until a strategy names it in aws_ivs_realtime_publish_streams.

Parameters
out_local_subtitle_streamOn success, receives an application-owned local_subtitle_stream handle; release it with aws_ivs_realtime_local_subtitle_stream_destroy(). Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_local_subtitle_stream is null.

◆ aws_ivs_realtime_local_subtitle_stream_destroy()

AWS_IVS_REALTIME_API void aws_ivs_realtime_local_subtitle_stream_destroy ( aws_ivs_realtime_local_subtitle_stream * local_subtitle_stream)

Free a subtitle stream handle. Idempotent on null. Destroying a stream a Stage is publishing stops that stream; the Stage keeps publishing everything else. Reports every cue this stream still owes an outcome for before returning, so no callback is lost with the handle. Those callbacks run on the same serialized thread as the strategy and every stage event callback, so this must not be called from within a callback.

Parameters
local_subtitle_streamOwned by the application and released by this call; null is a no-op.
Note
Do not call this concurrently with any other function on the same handle.

◆ aws_ivs_realtime_local_subtitle_stream_get_stream_id()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_local_subtitle_stream_get_stream_id ( aws_ivs_realtime_local_subtitle_stream * local_subtitle_stream,
const char ** out_stream_id,
aws_ivs_realtime_error ** out_error )

The stream's identifier, fixed for its lifetime and unique within the Stage. It matches the id on the stage_stream the streams-added event delivers for this stream.

Parameters
local_subtitle_streamThe application keeps ownership.
out_stream_idOn success, receives an SDK-owned string pointer that remains valid until the owning local_subtitle_stream is destroyed. Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when local_subtitle_stream is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_stream_id is null.

◆ aws_ivs_realtime_local_subtitle_stream_send_cue()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_local_subtitle_stream_send_cue ( aws_ivs_realtime_local_subtitle_stream * local_subtitle_stream,
const aws_ivs_realtime_subtitle_cue * cue,
aws_ivs_realtime_cue_sent_cb callback,
void * user_data,
aws_ivs_realtime_error ** out_error )

Send one subtitle cue. A synchronous failure does not call callback. A successful return means the SDK accepted the cue for processing, not that it was sent or reached the transport. Everything past that point, success or failure, is reported on callback: the SDK invokes it exactly once and does not retain it afterward. Safe to call from any thread.

Parameters
local_subtitle_streamThe application keeps ownership.
cueThe cue to send. Used only for this call; the SDK copies anything it retains.
callbackThe callback receiving this cue's outcome, or null to send without one. The application must keep this callback valid until it is cleared or the owning handle is destroyed.
user_dataThe SDK stores this pointer and passes it back to callbacks without reading or freeing it.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when local_subtitle_stream is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when cue is null.
  • AWS_IVS_REALTIME_ERROR_CODE_SUBTITLE_STREAM_NOT_PUBLISHING when the local participant is not publishing this stream, either because it is not publishing at all or because the strategy does not name this stream in aws_ivs_realtime_publish_streams.

◆ aws_ivs_realtime_publish_streams_add_subtitle_stream()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_publish_streams_add_subtitle_stream ( aws_ivs_realtime_publish_streams * publish_streams,
aws_ivs_realtime_local_subtitle_stream * subtitle_stream,
aws_ivs_realtime_error ** out_error )

Publish subtitle cues from this stream. Naming the same stream twice adds it once. A Stage can publish multiple subtitle streams.

Parameters
publish_streamsThe SDK keeps ownership; do not destroy it.
subtitle_streamThe subtitle stream to publish. The application keeps ownership.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when publish_streams is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when subtitle_stream is null.

◆ aws_ivs_realtime_publish_streams_set_audio()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_publish_streams_set_audio ( aws_ivs_realtime_publish_streams * publish_streams,
aws_ivs_realtime_audio_source * audio,
aws_ivs_realtime_error ** out_error )

Publish audio from this source. Passing null publishes no audio. Calling this more than once replaces the source named by the previous call, so the last call wins.

Parameters
publish_streamsThe SDK keeps ownership; do not destroy it.
audioThe audio source to publish, or null to publish no audio. The application keeps ownership.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when publish_streams is null.

◆ aws_ivs_realtime_stage_create()

AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_create ( const char * token,
aws_ivs_realtime_stage_strategy * stage_strategy,
const aws_ivs_realtime_stage_event_callbacks * stage_event_callbacks,
aws_ivs_realtime_stage ** out_stage,
aws_ivs_realtime_error ** out_error )

Create a Stage from a valid IVS Stage participant token. This does not connect to the Stage; call aws_ivs_realtime_stage_join to connect. The strategy and event callbacks remain associated with the Stage until it is destroyed.

Parameters
tokenNUL-terminated UTF-8 participant token. Used only for this call; the SDK copies anything it retains.
stage_strategyThe strategy deciding what this Stage subscribes to and publishes. The application keeps ownership.
stage_event_callbacksEvent callback table. Null disables event callbacks. Used only for this call; the SDK copies anything it retains.
out_stageOn success, receives an application-owned stage handle; release it with aws_ivs_realtime_stage_destroy(). Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when token is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage_strategy is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_stage is null.

◆ aws_ivs_realtime_stage_destroy()

AWS_IVS_REALTIME_API void aws_ivs_realtime_stage_destroy ( aws_ivs_realtime_stage * stage)

Leave if necessary and free the handle. Idempotent on null. Must be called exactly once for each successfully created handle. Must not be called from within a callback.

Parameters
stageOwned by the application and released by this call; null is a no-op.
Note
Do not call this concurrently with any other function on the same handle.

◆ aws_ivs_realtime_stage_join()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_join ( aws_ivs_realtime_stage * stage,
aws_ivs_realtime_error ** out_error )

Connect to the Stage associated with the token and begin the callback flow. Connection progress is reported via on_connection_state_changed.

Parameters
stageThe application keeps ownership.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage is null.
  • AWS_IVS_REALTIME_ERROR_CODE_STAGE_INVALID_TOKEN when the token cannot be parsed.
  • AWS_IVS_REALTIME_ERROR_CODE_STAGE_EXPIRED_TOKEN when the token has expired.

◆ aws_ivs_realtime_stage_leave()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_leave ( aws_ivs_realtime_stage * stage,
aws_ivs_realtime_error ** out_error )

Leave the Stage. A no-op if not joined. The connection transitions to DISCONNECTED. The handle remains valid and may be re-joined.

Parameters
stageThe application keeps ownership.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage is null.

◆ aws_ivs_realtime_stage_refresh_strategy()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_refresh_strategy ( aws_ivs_realtime_stage * stage,
aws_ivs_realtime_error ** out_error )

Ask the SDK to re-query the strategy. Every strategy callback is invoked again for the participants it applies to, and subscriptions and published streams are updated to match the new answers. Safe to call from within a callback.

Parameters
stageThe application keeps ownership.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage is null.

◆ aws_ivs_realtime_stage_set_audio_callback()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_set_audio_callback ( aws_ivs_realtime_stage * stage,
aws_ivs_realtime_audio_cb callback,
void * user_data,
aws_ivs_realtime_error ** out_error )

Register the mixed-PCM audio callback. Call this before aws_ivs_realtime_stage_join or after aws_ivs_realtime_stage_leave. The callback persists across leave/join cycles and is cleared by aws_ivs_realtime_stage_destroy. Passing a null callback clears it.

Parameters
stageThe application keeps ownership.
callbackThe mixed-PCM callback, or null to clear. The application must keep this callback valid until it is cleared or the owning handle is destroyed.
user_dataThe SDK stores this pointer and passes it back to callbacks without reading or freeing it.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage is null.
  • AWS_IVS_REALTIME_ERROR_CODE_STAGE_SET_AUDIO_CALLBACK_WHILE_JOINED when the Stage is joined.

◆ aws_ivs_realtime_stage_strategy_create()

AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_strategy_create ( const aws_ivs_realtime_stage_strategy_callbacks * callbacks,
aws_ivs_realtime_stage_strategy ** out_stage_strategy,
aws_ivs_realtime_error ** out_error )

Create a stage strategy backed by application callbacks. Every required callback in the table must be non-null.

Parameters
callbacksThe questions this strategy answers. Every required callback must be supplied. Used only for this call; the SDK copies anything it retains.
out_stage_strategyOn success, receives an application-owned stage_strategy handle; release it with aws_ivs_realtime_stage_strategy_destroy(). Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when callbacks is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_stage_strategy is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when callbacks->size is 0.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when a required callback in the table is null.

◆ aws_ivs_realtime_stage_strategy_destroy()

AWS_IVS_REALTIME_API void aws_ivs_realtime_stage_strategy_destroy ( aws_ivs_realtime_stage_strategy * stage_strategy)

Free a stage strategy handle. Idempotent on null. Destroy any Stage still using a stage strategy before destroying the stage strategy.

Parameters
stage_strategyOwned by the application and released by this call; null is a no-op.
Note
Do not call this concurrently with any other function on the same handle.

◆ aws_ivs_realtime_stage_stream_clone()

AWS_IVS_REALTIME_NODISCARD AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_clone ( aws_ivs_realtime_stage_stream * source,
aws_ivs_realtime_stage_stream ** out_stage_stream,
aws_ivs_realtime_error ** out_error )

Retain a stream past the callback that delivered it. The result refers to the same stream and keeps answering after that stream ends, which is what makes it safe to hold: getters continue to work and aws_ivs_realtime_stage_stream_set_audio_callback fails. Cloning never fails for a live handle.

Parameters
sourceThe stream to retain, as delivered to a Stage event callback. The application keeps ownership.
out_stage_streamOn success, receives an application-owned stage_stream handle; release it with aws_ivs_realtime_stage_stream_destroy(). Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when source is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_stage_stream is null.

◆ aws_ivs_realtime_stage_stream_destroy()

AWS_IVS_REALTIME_API void aws_ivs_realtime_stage_stream_destroy ( aws_ivs_realtime_stage_stream * stage_stream)

Release a handle from aws_ivs_realtime_stage_stream_clone. Null is a no-op. Do not pass a handle delivered to an event callback; those are borrowed. Safe to call from any thread including an event callback: it does not block and does not run application code.

Parameters
stage_streamOwned by the application and released by this call; null is a no-op.
Note
Do not call this concurrently with any other function on the same handle.

◆ aws_ivs_realtime_stage_stream_get_is_muted()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_get_is_muted ( aws_ivs_realtime_stage_stream * stage_stream,
bool * out_is_muted,
aws_ivs_realtime_error ** out_error )

Whether the stream is muted on the Stage, meaning no media reaches any subscriber. This is not local playback state. Reading it reports the current value, including for a stream that was already muted when it was first reported, which on_streams_muted_changed does not cover because it fires only on a change.

Parameters
stage_streamThe application keeps ownership.
out_is_mutedOn success, receives the value. Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage_stream is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_is_muted is null.

◆ aws_ivs_realtime_stage_stream_get_stream_id()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_get_stream_id ( aws_ivs_realtime_stage_stream * stage_stream,
const char ** out_stream_id,
aws_ivs_realtime_error ** out_error )

The stream's identifier, fixed for its lifetime and unique within the Stage. Two handles name the same stream when their IDs match.

Parameters
stage_streamThe application keeps ownership.
out_stream_idOn success, receives an SDK-owned string pointer that remains valid until the owning stage_stream is destroyed. Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage_stream is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_stream_id is null.

◆ aws_ivs_realtime_stage_stream_get_stream_type()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_get_stream_type ( aws_ivs_realtime_stage_stream * stage_stream,
aws_ivs_realtime_stream_type * out_stream_type,
aws_ivs_realtime_error ** out_error )

The kind of content this stream carries. This applies to a published stream and to a subscribed stream. Exactly one bit is set.

Parameters
stage_streamThe application keeps ownership.
out_stream_typeOn success, receives the value. Left unchanged on failure.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage_stream is null.
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when out_stream_type is null.

◆ aws_ivs_realtime_stage_stream_set_audio_callback()

AWS_IVS_REALTIME_API bool aws_ivs_realtime_stage_stream_set_audio_callback ( aws_ivs_realtime_stage_stream * stage_stream,
aws_ivs_realtime_audio_cb callback,
void * user_data,
aws_ivs_realtime_error ** out_error )

Register a callback receiving only this stream's audio, before it is mixed with any other participant's. Audio streams only. Passing a null callback clears the registration, and registering again replaces it. Call this on the handle the event delivered; cloning first is unnecessary. The registration belongs to the stream rather than to the handle, so it keeps delivering after the callback returns. Clone only to call into the stream from somewhere else later, such as reading its mute state or clearing the callback from your own code. A registration lasts as long as the stream. Register from on_streams_added, because a stream that ends is reported through on_streams_removed and replaced by a new stream with a new ID that needs its own registration. Every registered stream callback shares one real-time audio thread with each other and with the mixed callback from aws_ivs_realtime_stage_set_audio_callback, so a slow callback delays audio for every participant, not just this one.

Parameters
stage_streamThe application keeps ownership.
callbackThe callback receiving this stream's audio, or null to clear. The application must keep this callback valid until it is cleared or the owning handle is destroyed.
user_dataThe SDK stores this pointer and passes it back to callbacks without reading or freeing it.
out_errorNull, or the address of a null aws_ivs_realtime_error*. On failure, receives an application-owned error; release it with aws_ivs_realtime_error_destroy(). Left unchanged on success.
Returns
true on success; false on failure, with the error in out_error when it is non-null.
Errors (not exhaustive)
  • AWS_IVS_REALTIME_ERROR_CODE_INVALID_ARGUMENT when stage_stream is null.
  • AWS_IVS_REALTIME_ERROR_CODE_STAGE_STREAM_NOT_AUDIO when the stream is not an audio stream.
  • AWS_IVS_REALTIME_ERROR_CODE_STAGE_STREAM_ENDED when the stream has ended.