Getting Started with Live Streaming

1

Getting API Key for Live Streaming

The start streaming with Qencode, you need your api_key, which can be found in the List of Projects for live streaming inside your account.

The api_key assigned to each Project allows you easily segment usage and billing based on your preferences, while provide some control over access to the Qencode API. If you want to generate a new API Key, you can do so by creating a Project. You can also recreate an api_key for an existing Project via the UI inside your account.

2

Getting Access Token

Once you have your api_key, use it to generate a session-based access_token, which is used to authenticate all of your subsequent live stream requests.

Here's an example of API request to get access token:

curl -X POST https://api-live.qencode.com/v1/access_token/your_api_key

Response example:

{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyjpYXQiOjE2MjgxNTgyNJMsInN1YiI6MTMwLCJleHAiOjE2MjgyNDQ2NjN9.SxS3zLx2CZbZ9ylTpd25kj9el6_4TqqTWUA9RT2iJ9I"
}

Token returned should be passed in Authorization header to all other live streaming API methods.

3

Creating a Live Stream

Now that you have an access_token, use it with the /v1/live-streams method to create a new live stream.

There is a wide range of parameters that are required that contains all the information you need to start streaming.

4

Choose an Input Protocol for Stream

The way you stream depends on your ingest protocol. Qencode supports RTMP, WebRTC and SRT protocols for live streaming.

RTMP Streaming

To start broadcasting with RTMP, enter the following values into your streaming client or software.

Step 1Server URL

rtmp://rtmp-live.qencode.com/qlive

You can also get this URL /v1/live-streams/<stream_id>/start method and get RTMP Server URL.

...
"server_urls": {
   "rtmp": "rtmp://rtmp-live.qencode.com/qlive",
}
...

Step 2Stream key

There are three ways to get the stream_key for your stream.

• As part of the response when you create a live stream
• When you query stream details /v1/live-streams/<stream_id>/start method and get webrtc server url from its response
• By clicking on a stream on the Stream List page.

If you want to reduce startup time, you can start the encoder in advance using You can also get this URL /v1/live-streams/<stream_id>/start method and get RTMP Server URL.

Otherwise, you can start streaming using your credentials and the system will allocate an encoder automatically.

WebRTC Streaming

For WebRTC input typical setup is the following: client's webpage gets access to a webcam and pushes the stream from it to Qencode. We provide a powerful WebRTC Kit you can use to integrate this feature into your web site. For testing purposes you can use this WebRTC Test page

Step 1Start your WebRTC stream

You should call /v1/live-streams/<stream_id>/start method and get webrtc server url from its response:

...
"server_urls": {
   "rtmp": "rtmp://rtmp-live.qencode.com/qlive",
   "webrtc": "wss://live-df6607d4-8866-4d30-906d-0fed54e58f97.qencode.com:3334/qlive/1234e5b1-dfd7-4daa-8121-bc5c68bbeb37"
}
...

Alternatively you can start stream using Start stream link on the Stream detail page in your Qencode account UI. Available server urls will be shown there as well.

Step 2Push stream to Server URL

To start broadcasting with WebRTC, you need the webrtc value from server_urls along with the stream_key you received in Step 1.

You can start streaming using our WebRTC Test page or any web client that supports WebRTC.

Note: The timeout to receive input for a stream is 120 seconds, so please make sure you call the /v1/live-streams/<stream_id>/start method shortly after the stream is started.

If you are using the test page, make sure you

1. Allow webcam and microphone access. You can verify this if the video is visible on the page.
2. Press Connect button to start pushing the stream to Qencode.
   

SRT Streaming

To set up your client app you need a Server URL for SRT input. This URL also includes stream_key. Server URL for SRT is available after the stream is started. You can start your stream via UI or API. To start a stream in UI click on one of your streams on the stream list page, then press Start stream button in the stream Input section:

You can also start the stream by calling /v1/live-streams/<stream_id>/start method and getting srt server url from its response:

...
"server_urls": {
   "rtmp": "rtmp://rtmp-live.qencode.com/qlive",
   "srt": "srt://live-53801710-8c4e-433e-befb-5571d4843d4f.qencode.com:9999?streamid=1234e5b1-dfd7-4daa-8121-bc5c68bbeb37"
}
...

Specify the SRT Server URL in your streaming client app settings. You can see screenshot of OBS params below:

Ingest timeout for a stream is 120 seconds. Please make sure it's less than 120 seconds passed since you have called /v1/live-streams/<stream_id>/start method when you start pushing the stream to the srt server url.

5

Receiving event callbacks for live stream

You can set up an endpoint on your web server and get webhook notifications each time a stream event occurs, e.g. when stream status is changed. To specify a callback for a stream you need to call /v1/live-streams/<stream_id> method and pass the following data:

{
    "callback_url": "https://yourserver.com/stream-callback-endpoint"
}

After you set up a callback URL for a stream, Qencode will send an http POST request to it each time a stream event occurs. The body of http POST request is stream object data in JSON format.

6

Playing your live stream

Each stream has a unique playback_id value identifying a playback URL.

HLS

For HLS output stream playback URL format will be the following:

https://play-<playback_id>/qhls/qlive/playlist.m3u8

You can use any player supporting ABR streams playback.
Using Qencode Player is described here

7

Stopping your live stream

Stopping a broadcast in your streaming client will bring stream to an Idle status. Renewing broadcast withing a two minutes interval after stopping it will make your stream Live again. If more than two minutes pass after broadcast is stopped or interrupted stream gets Stopped.
Calling /v1/live-streams/<stream_id>/stop method immediately stops a live stream.

Here's an example of API request to stop a stream:

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X POST https://api-live.qencode.com/v1/live-streams/$STREAM_ID/stop

More tutorials