Broadcasting to an Amazon IVS Real-Time Stream with WHIP from OBS

Until recently, broadcasting to an Amazon Interactive Video Service (Amazon IVS) real-time stage required developers to utilize one of our Broadcast SDKs (web and mobile). Behind the scenes, the SDKs abstract all of the logic required to initialize a peer connection and broadcast the user's video to the stage. This makes it easier for developers who want to integrate real-time streaming in their applications, but also limits the options for the end users who will ultimately be broadcasting to that stage to only web and mobile based client software. The addition of support for any WHIP-compatible encoder opens the door for additional options for media publish to a real-time stage.

WHIP??

Bit of a weird name for a protocol, I'll admit 🤷🏻‍♂️. But, I'm not in charge of naming things (which is probably a good thing). WHIP stands for WebRTC-HTTP Ingest Protocol which is an IETF protocol that standardizes the process of the one-time exchange of Session Description Protocol (SDP) offers and answers using HTTP POST requests.

💡 Not Down With SDP? Check out 'What is the Session Description Protocol (SDP)?' on WebRTC for the Curious.

As you may have guessed from the name, the WHIP protocol refers to ingest (AKA 'broadcasting' or 'publishing') only. There's a separate protocol called WHEP that deals with egress (AKA 'viewing' or 'subscribing'). If you're struggling with insomnia 🥱, feel free to read the entire IETF draft for WHIP or WHEP.

Broadcasting to an Amazon IVS Stage with OBS

OBS is widely-used because of it's advanced production features like scene transitions, overlays, easy screen sharing, audio mixing and more. To broadcast to an Amazon IVS stage from OBS, the user will need at least OBS version 30 and a stage participant token. These tokens usually have an expiration time of 12 hours (the default), but this can be extended up to 14 days.

To try it out, generate a stage participant token via an AWS SDK, the AWS CLI, or the Amazon IVS management console and head into the 'Settings' dialog in OBS.

In the 'Stream' tab, choose 'WHIP' as the 'Service', enter https://global.whip.live-video.net as the 'Server' and paste a valid stage participant token as the 'Bearer Token'.

Note: OBS will warn you that WHIP broadcasting requires Opus audio encoding. This is expected, so select 'Yes' to continue.

Next, head to the 'Output' tab and make sure that the 'Output Mode' is 'Advanced'.

For the best performance, make sure your 'Bitrate' is at or below 2500 Kbps, use a 'Keyframe Interval' of 1s or 2s, set 'CPU Usage Preset' to ultrafast and 'Tune' to zerolatency.

Now exit from the 'Settings' dialog and click 'Start Streaming' and you'll be broadcasting to the stage.

Refer to the docs on OBS and WHIP Support for more info.

Broadcasting to an Amazon IVS Stage with GStreamer

If you're a fan of the open source multimedia framework GStreamer, you can take advantage of WHIP support as well. Here's a simple pipeline that could be used to publish a webcam and microphone to a stage. This pipeline is specific to MacOS, but can be adapted to any supported OS. Make sure to obtain and set a participant token into IVS_STAGE_TOKEN (or include a raw token instead).

gst-launch-1.0 </span>

  avfvideosrc device-index=0 </span>

  ! videoconvert </span>

  ! x264enc tune=zerolatency bitrate=2500 speed-preset=ultrafast </span>

  ! rtph264pay </span>

  ! 'application/x-rtp,media=video,encoding-name=H264,payload=97,clock-rate=90000,width=1280,height=720,framerate=30/1' </span>

  ! whip.sink_0 autoaudiosrc wave=4 </span>

  ! audioconvert </span>

  ! opusenc </span>

  ! rtpopuspay </span>

  ! 'application/x-rtp,media=audio,encoding-name=OPUS,payload=96,clock-rate=48000,encoding-params=(string)2' </span>

  ! whip.sink_1 </span>

  whipsink </span>

  name=whip </span>

  auth-token=$IVS_STAGE_TOKEN </span>

  whip-endpoint=https://global.whip.live-video.net/

Summary

In this post, we learned how to publish to an Amazon IVS real-time stage via WHIP-compatible encoders. This support opens up many possibilities for real-time streaming with Amazon IVS. Refer to the Amazon IVS Real-Time User Guide page on OBS and WHIP Support for further details. If you have any questions or ideas for possible use-cases drop a comment below!

Comments

[Matthew]

Thank you Todd for this great article.

Following the instructions detailed in the post I've been able to broadcast video to an Amazon IVS real-time stage using WHIP with OBS, Gstreamer and JavaScript in the browser.

For my use case, I only want to broadcast audio. When I try to publish an audio-only stream, by following the same steps and simply omitting the video part from the configurations, I get a 400 Bad Request response from the live-video.net/publish endpoint, with the body: {"code":2001,"message":"failed to create publisher session"}.

Is this a limitation of WHIP or IVS, and is there a workaround?

[Todd Sharp]

Let me check on this and get back to you!

[Matthew]

Thanks Todd.

I've forked the amazon-ivs-stage-recorder example repo and made some changes to demonstrate this issue: github.com/mattvick/amazon-ivs-sta...

The README.md file explains how to run the code to see the error response, and how adding a video codec and transceiver remedies the issue.

Let me know if you have any questions, or maybe you can see from the code that I'm doing something wrong.

[Todd Sharp]

Very helpful, thank you. As a workaround, did you try adding a video track? It doesn't have to send any frames.

[Matthew]

Thanks, that's a good idea. And I can confirm that adding a video track removes the error.

I know there is a big difference in pricing between IVS video and audio. Will adding a video track cause the stage time to be billed as video rather than audio?

[Todd Sharp]

I think if you just pass an (empty) video track in the SDP negotiation, you'll be OK. You won't need to send blank video frames, I think the issue only lies in the SDP negotiation.

[mentoRisen]

This is amazing, but I couldn't make it work. I did all configuration of OBS and whatever I do I still get "Failed to Connect: Could not access the specified channel or stream key...". In OBS logs I can see Connect failed: HTTP endpoint returned response code 404.
So I tried GStreamer and I end up in similar spot. GStreamer cannot connect to IVS and error that I get is Unexpected response: 404 - {"code":2011,"message":"action ID not found"}. There is nothing in documentation about error 2011 nor action ID.
I ran out of ideas what can I try to fix it so any suggestions would be very appreciable.

[Todd Sharp]

It sounds like you were trying to broadcast to a low-latency channel as opposed to a real-time stage. Can you confirm that you were using a stage, and not a channel? If so, double check the ingest endpoint and the token.

[Lukas Zemcak]

Thanks for reply. Actually no, we were trying to use real-time and all of our configuration and libraries was ok. Problem was on our AWS account settings. On brand new AWS account everything worked perfect. We contacted AWS team and reason was that we had simulcast enabled on our real-time stages. AWS support confirmed that we cannot use WHIP and simulcast on same stages. After they disabled simulcast WHIP works. They are working on some solution to this, but this issue should occur only if you have simulcast enabled for real-time streaming stages.

[Todd Sharp]

Ahh, interesting. Thanks for letting me know, I was not aware of this.