|
IVS Linux Broadcast SDK (C) 1.49.0
|
Public C API for the IVS Linux Broadcast SDK. More...
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. | |
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. | |
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.
| #define AWS_IVS_REALTIME_API |
Exports a function from the shared library.
| #define AWS_IVS_REALTIME_NODISCARD |
Marks a function whose result must not be ignored.
| #define AWS_IVS_REALTIME_VERSION_MAJOR 1 |
Major version of this header.
| #define AWS_IVS_REALTIME_VERSION_MINOR 49 |
Minor version of this header.
| #define AWS_IVS_REALTIME_VERSION_PATCH 0 |
Patch version of this header.
| #define AWS_IVS_REALTIME_VERSION_STRING "1.49.0" |
Version of this header as a string.
| 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.
| data | Interleaved 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_size | Size of data in bytes. |
| num_frames | Number of frames; each frame has one sample per channel. |
| bytes_per_sample | 2 for S16, 4 for Float32. |
| num_channels | 1 for mono, 2 for stereo. |
| samples_per_sec | Sample rate in Hz, e.g. 48000. |
| timestamp_ms | Presentation timestamp in milliseconds, monotonically increasing from the start of audio playout. |
| user_data | Application pointer supplied when registering the callback. |
| typedef struct aws_ivs_realtime_audio_source 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().
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().
| 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.
| state | The new connection state. |
| error | The error that caused the transition, or null for an expected transition. Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| error | Why 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_data | Application pointer supplied when registering the callback. |
| 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.
| error | The asynchronous error. This callback is not invoked with a null error. Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
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().
| typedef void(*) aws_ivs_realtime_participant_joined_cb(const aws_ivs_realtime_participant_info *participant, void *user_data) |
A participant joined the Stage.
| participant | Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| participant | Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| participant | Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| participant | Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| participant | The publishing participant the local participant's subscription changed for. Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
| typedef struct aws_ivs_realtime_publish_streams 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.
| 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.
| participant | The participant in question. Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
| typedef struct aws_ivs_realtime_stage 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().
| typedef struct aws_ivs_realtime_stage_strategy 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().
| typedef struct aws_ivs_realtime_stage_stream 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().
| 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.
| 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.
| participant | Valid only until this callback returns; copy it to retain it. |
| streams | The added streams. Clone one to use it after this callback returns. Valid only until this callback returns; copy it to retain it. |
| streams_count | Number of entries in streams. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| participant | Valid only until this callback returns; copy it to retain it. |
| streams | The streams whose mute state changed. Valid only until this callback returns; copy it to retain it. |
| streams_count | Number of entries in streams. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| participant | Valid only until this callback returns; copy it to retain it. |
| streams | The removed streams. Retained clones stay valid but become inert. Valid only until this callback returns; copy it to retain it. |
| streams_count | Number of entries in streams. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| participant | The participant the streams will be published as. Valid only until this callback returns; copy it to retain it. |
| streams | The collector to name the streams in. Owned by the SDK and valid only until this callback returns; do not store or destroy it. |
| user_data | Application pointer supplied when registering the callback. |
| 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.
| participant | The participant in question. Valid only until this callback returns; copy it to retain it. |
| user_data | Application pointer supplied when registering the callback. |
| anonymous enum |
Sample format of raw PCM. Interleaved formats store each frame's channels together; planar formats store one whole channel after another.
| 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.
| samples_per_sec | Sample rate in Hz of pushed audio, for example 48000. Must be between 8000 and 96000. |
| num_channels | Channel count of pushed audio. 1 for mono, 2 for stereo. |
| format | Sample format of pushed audio. |
| out_audio_source | On success, receives an application-owned audio_source handle; release it with aws_ivs_realtime_audio_source_destroy(). Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| audio_source | Owned by the application and released by this call; null is a no-op. |
| 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.
| audio_source | The application keeps ownership. |
| data | PCM samples in the source's format, where data_size == num_frames * num_channels * bytes-per-sample of that format. |
| data_size | Size of data in bytes. |
| num_frames | Number of frames; each frame has one sample per channel. |
| pts | Presentation 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_error | Null, 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. |
| 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.
| participant_id | The remote participant to subscribe to and transcribe. Must be non-empty. Used only for this call; the SDK copies anything it retains. |
| out_channel_transcriber | On success, receives an application-owned channel_transcriber handle; release it with aws_ivs_realtime_channel_transcriber_destroy(). Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| channel_transcriber | Owned by the application and released by this call; null is a no-op. |
| 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.
| channel_transcriber | The application keeps ownership. |
| out_stage_strategy | On 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_error | Null, 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. |
| 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.
| channel_transcriber | The application keeps ownership. |
| start_ms | Start timestamp of the text, in milliseconds, on the same timeline as the audio callback's timestamp_ms parameter. |
| end_ms | End timestamp of the text, in milliseconds, on the same timeline as start_ms. Must be greater than start_ms. |
| language_code | A 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. |
| text | UTF-8 transcription text. Used only for this call; the SDK copies anything it retains. |
| utterance_id | Caller-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_error | Null, 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. |
| 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.
| error | The error to free. |
| 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.
| out_version | On success, receives an SDK-owned string pointer that remains valid until the library is unloaded. Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| out_local_subtitle_stream | On success, receives an application-owned local_subtitle_stream handle; release it with aws_ivs_realtime_local_subtitle_stream_destroy(). Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| local_subtitle_stream | Owned by the application and released by this call; null is a no-op. |
| 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.
| local_subtitle_stream | The application keeps ownership. |
| out_stream_id | On success, receives an SDK-owned string pointer that remains valid until the owning local_subtitle_stream is destroyed. Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| local_subtitle_stream | The application keeps ownership. |
| cue | The cue to send. Used only for this call; the SDK copies anything it retains. |
| callback | The 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_data | The SDK stores this pointer and passes it back to callbacks without reading or freeing it. |
| out_error | Null, 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. |
| 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.
| publish_streams | The SDK keeps ownership; do not destroy it. |
| subtitle_stream | The subtitle stream to publish. The application keeps ownership. |
| out_error | Null, 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. |
| 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.
| publish_streams | The SDK keeps ownership; do not destroy it. |
| audio | The audio source to publish, or null to publish no audio. The application keeps ownership. |
| out_error | Null, 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. |
| 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.
| token | NUL-terminated UTF-8 participant token. Used only for this call; the SDK copies anything it retains. |
| stage_strategy | The strategy deciding what this Stage subscribes to and publishes. The application keeps ownership. |
| stage_event_callbacks | Event callback table. Null disables event callbacks. Used only for this call; the SDK copies anything it retains. |
| out_stage | On success, receives an application-owned stage handle; release it with aws_ivs_realtime_stage_destroy(). Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| stage | Owned by the application and released by this call; null is a no-op. |
| 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.
| stage | The application keeps ownership. |
| out_error | Null, 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. |
| 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.
| stage | The application keeps ownership. |
| out_error | Null, 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. |
| 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.
| stage | The application keeps ownership. |
| out_error | Null, 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. |
| 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.
| stage | The application keeps ownership. |
| callback | The 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_data | The SDK stores this pointer and passes it back to callbacks without reading or freeing it. |
| out_error | Null, 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. |
| 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.
| callbacks | The questions this strategy answers. Every required callback must be supplied. Used only for this call; the SDK copies anything it retains. |
| out_stage_strategy | On success, receives an application-owned stage_strategy handle; release it with aws_ivs_realtime_stage_strategy_destroy(). Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| stage_strategy | Owned by the application and released by this call; null is a no-op. |
| 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.
| source | The stream to retain, as delivered to a Stage event callback. The application keeps ownership. |
| out_stage_stream | On success, receives an application-owned stage_stream handle; release it with aws_ivs_realtime_stage_stream_destroy(). Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| stage_stream | Owned by the application and released by this call; null is a no-op. |
| 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.
| stage_stream | The application keeps ownership. |
| out_is_muted | On success, receives the value. Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| stage_stream | The application keeps ownership. |
| out_stream_id | On success, receives an SDK-owned string pointer that remains valid until the owning stage_stream is destroyed. Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| stage_stream | The application keeps ownership. |
| out_stream_type | On success, receives the value. Left unchanged on failure. |
| out_error | Null, 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. |
| 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.
| stage_stream | The application keeps ownership. |
| callback | The 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_data | The SDK stores this pointer and passes it back to callbacks without reading or freeing it. |
| out_error | Null, 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. |