AWS.IVSRealtime reference

CreateParticipantToken

Source: src/AWS/IVSRealtime/CreateParticipantToken.ts

Mint a participant token that an end user presents to join the bound stage — the effectful call made from a deployed Lambda or Task. The capabilities field grants PUBLISH and/or SUBSCRIBE to the token holder; attributes attaches profile data (display name, avatar, …) that is visible to other participants. The returned token is sensitive and surfaces as a Redacted value.

CreateParticipantToken: Minting Participant Tokens

Provide the CreateParticipantTokenHttp implementation layer on the Function effect, bind the stage in the init phase, then call the returned client at runtime. The binding grants ivs:CreateParticipantToken on the stage and injects its ARN automatically.

// init
const stage = yield* IVSRealtime.Stage("VideoRoom");
const createParticipantToken = yield* IVSRealtime.CreateParticipantToken(stage);

return {
  fetch: Effect.gen(function* () {
    // runtime
    const { participantToken } = yield* createParticipantToken({
      userId: "user-123",
      capabilities: ["PUBLISH", "SUBSCRIBE"],
      duration: "30 minutes",
      attributes: { displayName: "Sam" },
    });
    return HttpServerResponse.json({
      token:
        participantToken?.token !== undefined
          ? Redacted.value(participantToken.token)
          : undefined,
      participantId: participantToken?.participantId,
    });
  }),
};
// on the Function effect:
// .pipe(Effect.provide(IVSRealtime.CreateParticipantTokenHttp))

DisconnectParticipant

Source: src/AWS/IVSRealtime/DisconnectParticipant.ts

Forcibly disconnect a participant from the bound stage — the moderation call made from a deployed Lambda or Task. If the participant is publishing via an ingest configuration, its stageArn attachment is also cleared.

DisconnectParticipant: Moderating Participants

// init
const disconnectParticipant = yield* IVSRealtime.DisconnectParticipant(stage);

// runtime
yield* disconnectParticipant({
  participantId: "abcDEF123",
  reason: "moderated",
});

GetComposition

Source: src/AWS/IVSRealtime/GetComposition.ts

Read a composition’s detail — state, layout, destinations, and per destination progress. Compositions are addressed by the server-generated ARN returned by StartComposition.

GetComposition: Compositing a Stage

// init
const getComposition = yield* IVSRealtime.GetComposition();

// runtime
const { composition } = yield* getComposition({ arn: compositionArn });
// composition.state → "ACTIVE" | "STOPPED" | "FAILED" | …

GetParticipant

Source: src/AWS/IVSRealtime/GetParticipant.ts

Read a participant’s detail (state, join time, attributes, publish state, recording state, connection metadata) for a session of the bound stage.

GetParticipant: Inspecting Participants

// init
const getParticipant = yield* IVSRealtime.GetParticipant(stage);

// runtime
const { participant } = yield* getParticipant({
  sessionId: "st-a1b2c3d4e5f6",
  participantId: "abcDEF123",
});

GetStageSession

Source: src/AWS/IVSRealtime/GetStageSession.ts

Read a session of the bound stage — its start time and, once the last participant leaves, its end time.

GetStageSession: Inspecting Stage Sessions

// init
const getStageSession = yield* IVSRealtime.GetStageSession(stage);

// runtime
const { stageSession } = yield* getStageSession({
  sessionId: "st-a1b2c3d4e5f6",
});

ListCompositions

Source: src/AWS/IVSRealtime/ListCompositions.ts

List the account’s compositions in the current region, optionally filtered by stage or encoder configuration.

ListCompositions: Compositing a Stage

// init
const listCompositions = yield* IVSRealtime.ListCompositions();

// runtime
const { compositions } = yield* listCompositions();

ListParticipantEvents

Source: src/AWS/IVSRealtime/ListParticipantEvents.ts

List the events (joined, left, publish started/stopped, errors) recorded for a participant during a session of the bound stage.

ListParticipantEvents: Inspecting Participants

// init
const listParticipantEvents = yield* IVSRealtime.ListParticipantEvents(stage);

// runtime
const { events } = yield* listParticipantEvents({
  sessionId: "st-a1b2c3d4e5f6",
  participantId: "abcDEF123",
});

ListParticipantReplicas

Source: src/AWS/IVSRealtime/ListParticipantReplicas.ts

List the replicas of a participant of the bound (source) stage — the destination stages a participant’s media is replicated to and each replica’s state.

ListParticipantReplicas: Replicating Participants

// init
const listParticipantReplicas = yield* IVSRealtime.ListParticipantReplicas(stage);

// runtime
const { replicas } = yield* listParticipantReplicas({
  participantId: "abcDEF123",
});

ListParticipants

Source: src/AWS/IVSRealtime/ListParticipants.ts

List all participants in a session of the bound stage, optionally filtered by user id, publish state, connection state, or recording state.

ListParticipants: Inspecting Participants

// init
const listParticipants = yield* IVSRealtime.ListParticipants(stage);

// runtime
const { participants } = yield* listParticipants({
  sessionId: "st-a1b2c3d4e5f6",
  filterByPublished: true,
});

ListStageSessions

Source: src/AWS/IVSRealtime/ListStageSessions.ts

List all sessions (current and past) of the bound stage, most recent first.

ListStageSessions: Inspecting Stage Sessions

// init
const listStageSessions = yield* IVSRealtime.ListStageSessions(stage);

// runtime
const { stageSessions } = yield* listStageSessions();

Stage

Source: src/AWS/IVSRealtime/Stage.ts

An Amazon IVS Real-Time stage — a virtual space where participants exchange audio and video in real time (sub-300ms latency).

Participants join a stage with participant tokens minted at runtime via CreateParticipantToken; publishers can also ingest via the stage’s WHIP/RTMP endpoints.

Stage: Creating Stages

Basic Stage

import * as IVSRealtime from "alchemy/AWS/IVSRealtime";

const stage = yield* IVSRealtime.Stage("VideoRoom");

Named Stage with Tags

const stage = yield* IVSRealtime.Stage("VideoRoom", {
  stageName: "my-video-room",
  tags: { team: "media" },
});

StartComposition

Source: src/AWS/IVSRealtime/StartComposition.ts

Start a server-side composition of the bound stage — IVS mixes the stage’s participants into a single video according to the layout and delivers it to the given destinations (an IVS low-latency channel and/or an S3 storage configuration).

StartComposition: Compositing a Stage

// init
const startComposition = yield* IVSRealtime.StartComposition(stage);

// runtime
const { composition } = yield* startComposition({
  destinations: [{ channel: { channelArn } }],
  layout: { grid: { videoAspectRatio: "VIDEO" } },
});

StartParticipantReplication

Source: src/AWS/IVSRealtime/StartParticipantReplication.ts

Replicate a participant’s media from the bound source stage into the bound destination stage — e.g. to bring a guest publisher into a second room without a re-publish.

StartParticipantReplication: Replicating Participants

// init — bound to (source, destination)
const startParticipantReplication =
  yield* IVSRealtime.StartParticipantReplication(mainStage, overflowStage);

// runtime
yield* startParticipantReplication({
  participantId: "abcDEF123",
  reconnectWindow: "30 seconds",
});

StopComposition

Source: src/AWS/IVSRealtime/StopComposition.ts

Stop and delete a composition — any broadcast to the composition’s destinations ends. Compositions are addressed by the server-generated ARN returned by StartComposition.

StopComposition: Compositing a Stage

// init
const stopComposition = yield* IVSRealtime.StopComposition();

// runtime
yield* stopComposition({ arn: compositionArn });

StopParticipantReplication

Source: src/AWS/IVSRealtime/StopParticipantReplication.ts

Stop replicating a participant’s media from the bound source stage into the bound destination stage.

StopParticipantReplication: Replicating Participants

// init — bound to (source, destination)
const stopParticipantReplication =
  yield* IVSRealtime.StopParticipantReplication(mainStage, overflowStage);

// runtime
yield* stopParticipantReplication({ participantId: "abcDEF123" });