Ensure the target channel has an active stream (GetStream returns LIVE status) before sending metadata.
Call the IVS PutMetadata API (POST to /PutMetadata) with the channelArn and a metadata string payload (max 1 KB per call).
The metadata is time-synchronized by IVS to the video frames so all viewers receive it at the same playback moment regardless of their individual latency.
On the player side, listen for timed metadata events using the IVS Player SDK's onTimedMetadata callback; the SDK surfaces the metadata string when the corresponding video frame is rendered.
If your use case needs more than 5 PutMetadata calls per second per channel, batch multiple events into a single JSON payload within the 1 KB limit.
Use IAM policies to restrict PutMetadata to authorized backend services; the API requires the ivs:PutMetadata permission.
Known gotchas
PutMetadata is rate-limited to 5 requests per second per channel and 155 requests per second per account; batch data to stay within these limits.
Timed metadata is only synchronized in LL-HLS playback via the IVS Player SDK; raw HLS players without the SDK will not expose metadata events correctly.
Metadata that arrives during a stream outage or reconnect window may be dropped; design for at-most-once delivery semantics.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp