AWS.IVS reference

BatchStartViewerSessionRevocation

Source: src/AWS/IVS/BatchStartViewerSessionRevocation.ts

Runtime binding for ivs:BatchStartViewerSessionRevocation.

Starts revoking viewer sessions for up to 20 channel-ARN/viewer-ID pairs in one call — the multi-channel form of StartViewerSessionRevocation (e.g. kicking a banned viewer off every channel they are watching). Per-pair failures are reported in the response’s errors array rather than failing the whole call. The operation spans many channels, so it is account-scoped. Provide the implementation with Effect.provide(AWS.IVS.BatchStartViewerSessionRevocationHttp).

BatchStartViewerSessionRevocation: Revoking Viewer Sessions

// init — bind the account-level operation
const revokeViewerSessions =
  yield* AWS.IVS.BatchStartViewerSessionRevocation();

// runtime
const { errors } = yield* revokeViewerSessions({
  viewerSessions: [
    { channelArn: channelA, viewerId: "banned-viewer" },
    { channelArn: channelB, viewerId: "banned-viewer" },
  ],
});

Channel

Source: src/AWS/IVS/Channel.ts

An Amazon IVS (Interactive Video Service) channel for low-latency live video streaming.

A channel stores configuration for broadcasting live streams: broadcast software sends video to the channel’s ingestEndpoint (authenticated with a StreamKey) and viewers watch via the channel’s playbackUrl.

Channel: Creating Channels

Basic Channel

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

const channel = yield* IVS.Channel("LiveChannel");

Basic Low-Cost Channel

const channel = yield* IVS.Channel("LiveChannel", {
  type: "BASIC",
  latencyMode: "NORMAL",
});

Channel: Private Channels

const channel = yield* IVS.Channel("PrivateChannel", {
  authorized: true,
});

Channel: Streaming

const channel = yield* IVS.Channel("LiveChannel");
const streamKey = yield* IVS.StreamKey("LiveKey", {
  channelArn: channel.channelArn,
});
// broadcast to rtmps://{channel.ingestEndpoint}:443/app/ with streamKey.value

GetStream

Source: src/AWS/IVS/GetStream.ts

Runtime binding for ivs:GetStream.

Reads the bound Channel’s active (live) stream — state, health, viewer count, and playback URL. Fails with the typed ChannelNotBroadcasting tag when the channel is not live. The channel ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.IVS.GetStreamHttp).

GetStream: Monitoring Live Streams

// init — bind the operation to the channel
const getStream = yield* AWS.IVS.GetStream(channel);

// runtime
const live = yield* getStream().pipe(
  Effect.map(({ stream }) => ({ live: true, viewers: stream?.viewerCount })),
  Effect.catchTag("ChannelNotBroadcasting", () =>
    Effect.succeed({ live: false, viewers: 0 }),
  ),
);

GetStreamSession

Source: src/AWS/IVS/GetStreamSession.ts

Runtime binding for ivs:GetStreamSession.

Reads the metadata of a specific stream session on the bound Channel — ingest configuration, recording details, and the session’s truncated event log. Omit streamId to read the most recent session. The channel ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.IVS.GetStreamSessionHttp).

GetStreamSession: Monitoring Live Streams

// init — bind the operation to the channel
const getStreamSession = yield* AWS.IVS.GetStreamSession(channel);

// runtime
const { streamSession } = yield* getStreamSession({});
yield* Effect.log(`codec: ${streamSession?.ingestConfiguration?.video?.codec}`);

InsertAdBreak

Source: src/AWS/IVS/InsertAdBreak.ts

Runtime binding for ivs:InsertAdBreak.

Triggers a server-side ad break of the requested duration in the bound Channel’s active stream (the channel must have an ad configuration attached). Fails with the typed ChannelNotBroadcasting tag when the channel is not live. The channel ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.IVS.InsertAdBreakHttp).

InsertAdBreak: Inserting Ad Breaks

// init — bind the operation to the channel
const insertAdBreak = yield* AWS.IVS.InsertAdBreak(channel);

// runtime
const { adBreakId } = yield* insertAdBreak({ durationSeconds: 30 });

ListStreams

Source: src/AWS/IVS/ListStreams.ts

Runtime binding for ivs:ListStreams.

Enumerates the account’s live streams in the current region, optionally filtered by stream health. This is an account-level operation — no channel is bound, and the grant is on *. Provide the implementation with Effect.provide(AWS.IVS.ListStreamsHttp).

ListStreams: Monitoring Live Streams

// init — account-level, no resource to bind
const listStreams = yield* AWS.IVS.ListStreams();

// runtime
const { streams } = yield* listStreams();
yield* Effect.log(`${streams.length} live streams`);

ListStreamSessions

Source: src/AWS/IVS/ListStreamSessions.ts

Runtime binding for ivs:ListStreamSessions.

Enumerates current and previous broadcast sessions on the bound Channel (most recent first). The channel ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.IVS.ListStreamSessionsHttp).

ListStreamSessions: Monitoring Live Streams

// init — bind the operation to the channel
const listStreamSessions = yield* AWS.IVS.ListStreamSessions(channel);

// runtime
const { streamSessions } = yield* listStreamSessions({ maxResults: 10 });
yield* Effect.log(`sessions: ${streamSessions.length}`);

PlaybackKeyPair

Source: src/AWS/IVS/PlaybackKeyPair.ts

An Amazon IVS playback key pair for private channels.

Import the public half of an ECDSA P-384 key pair; sign viewer playback authorization tokens with the private half. Channels created with authorized: true require viewers to present a token signed by an imported key pair.

PlaybackKeyPair: Importing a Key Pair

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

const keyPair = yield* IVS.PlaybackKeyPair("ViewerAuth", {
  publicKeyMaterial: PUBLIC_KEY_PEM, // ECDSA P-384 public key
});
const channel = yield* IVS.Channel("PrivateChannel", {
  authorized: true,
});

PlaybackRestrictionPolicy

Source: src/AWS/IVS/PlaybackRestrictionPolicy.ts

An Amazon IVS playback restriction policy, constraining channel playback by viewer country and/or request origin.

Attach the policy to a channel via the channel’s playbackRestrictionPolicyArn prop. All policy settings are mutable and update in place.

PlaybackRestrictionPolicy: Restricting Playback

Restrict Playback by Country and Origin

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

const policy = yield* IVS.PlaybackRestrictionPolicy("GeoFence", {
  allowedCountries: ["US", "CA"],
  allowedOrigins: ["https://example.com"],
});
const channel = yield* IVS.Channel("LiveChannel", {
  playbackRestrictionPolicyArn: policy.playbackRestrictionPolicyArn,
});

Strict Origin Enforcement

const policy = yield* IVS.PlaybackRestrictionPolicy("StrictFence", {
  allowedCountries: ["US"],
  allowedOrigins: ["https://example.com"],
  enableStrictOriginEnforcement: true,
});

PutMetadata

Source: src/AWS/IVS/PutMetadata.ts

Runtime binding for ivs:PutMetadata.

Inserts timed metadata (max 1 KB) into the bound Channel’s active stream — the payload is embedded in the video and surfaced to players in sync with playback. Fails with the typed ChannelNotBroadcasting tag when the channel is not live. At most 5 requests per second per channel. The channel ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.IVS.PutMetadataHttp).

PutMetadata: Embedding Timed Metadata

// init — bind the operation to the channel
const putMetadata = yield* AWS.IVS.PutMetadata(channel);

// runtime
yield* putMetadata({
  metadata: JSON.stringify({ question: "Who wins?", options: ["A", "B"] }),
});

RecordingConfiguration

Source: src/AWS/IVS/RecordingConfiguration.ts

An Amazon IVS recording configuration, enabling automatic recording of live broadcasts to Amazon S3.

Attach the configuration to a channel via the channel’s recordingConfigurationArn prop; every broadcast on that channel is then archived to the configured bucket. Recording configurations are immutable — any settings change replaces the resource.

RecordingConfiguration: Recording Broadcasts

Record a Channel to S3

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

const archive = yield* AWS.Bucket("StreamArchive");
const recording = yield* IVS.RecordingConfiguration("Recording", {
  destinationConfiguration: { s3: { bucketName: archive.bucketName } },
});
const channel = yield* IVS.Channel("LiveChannel", {
  recordingConfigurationArn: recording.recordingConfigurationArn,
});

Merge Reconnects and Record Thumbnails

const recording = yield* IVS.RecordingConfiguration("Recording", {
  destinationConfiguration: { s3: { bucketName: archive.bucketName } },
  recordingReconnectWindow: "2 minutes",
  thumbnailConfiguration: {
    recordingMode: "INTERVAL",
    targetInterval: "30 seconds",
  },
});

StartViewerSessionRevocation

Source: src/AWS/IVS/StartViewerSessionRevocation.ts

Runtime binding for ivs:StartViewerSessionRevocation.

Starts revoking the viewer session for a given viewer ID on the bound Channel — used with private channels to eject a viewer whose playback authorization token carries that viewerId. Optionally revoke every session at or below a token version. The channel ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.IVS.StartViewerSessionRevocationHttp).

StartViewerSessionRevocation: Revoking Viewer Sessions

// init — bind the operation to the channel
const revokeViewerSession = yield* AWS.IVS.StartViewerSessionRevocation(channel);

// runtime
yield* revokeViewerSession({ viewerId: "user-123" });

StopStream

Source: src/AWS/IVS/StopStream.ts

Runtime binding for ivs:StopStream.

Disconnects the incoming RTMPS broadcast on the bound Channel. Fails with the typed ChannelNotBroadcasting tag when the channel is not live. Many broadcast clients auto-reconnect, so to stop a stream permanently, first delete or rotate the channel’s stream key. The channel ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.IVS.StopStreamHttp).

StopStream: Controlling Live Streams

// init — bind the operation to the channel
const stopStream = yield* AWS.IVS.StopStream(channel);

// runtime
yield* stopStream().pipe(
  Effect.catchTag("ChannelNotBroadcasting", () => Effect.void),
);

StreamKey

Source: src/AWS/IVS/StreamKey.ts

An Amazon IVS stream key — the secret credential broadcast software uses to authenticate against a channel’s ingest endpoint.

IVS allows at most one stream key per channel, and CreateChannel provisions one automatically. This resource therefore manages the channel’s stream key: if the channel already has its auto-created key, the resource takes ownership of it (tagging it with Alchemy’s internal tags) instead of failing the per-channel quota.

StreamKey: Creating Stream Keys

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

const channel = yield* IVS.Channel("LiveChannel");
const streamKey = yield* IVS.StreamKey("LiveKey", {
  channelArn: channel.channelArn,
});