Wowza Video API Session 1: Live Streaming Basics
Wowza Video is a one-stop integrated video solution that enables companies to harness the power of live streaming and VOD. If your organization aims to incorporate video into its business-critical applications, Wowza Video’s versatile API coverage can help you enhance your products and services with the power of streaming technology. Watch the video above or read the full transcript below learn how to set up a basic live stream:
Table of contents
Getting Started With Tokens
Barry Owen: Hey everyone. Barry on here today, I’m here with Rose Power. Hi Rose.
Rose Power: Hi, Barry.
Barry Owen: Today, we’re going to do a first in a series of sessions on the Wowza video API. The Wowza Video API is a great tool for those looking to integrate video into a platform or an application.
To get started, the first thing you’re going to need to do to access the API is create a Wowza Video account. From your account, you’re going to need to get a token. The authorization token, the way we’re doing it now is called a JWT. To get one of those, you go into your Wowza Video account, click on your account settings, and you’re going to click on this token management URL. I already have it open here, so I’m just going to flip over that page and this takes you to the wowza.com portal and allows you to create and manage tokens.
There are a couple different kinds of tokens: personal tokens and system tokens. The biggest difference is that system tokens allow you to assign different roles and scope things. I’ve already created one; it’s only going to show it to you once, so make sure you copy it and keep it in a safe place.
We’re going to go ahead and populate Postman over here with our token. I’ve created a variable here; you’ll see it’s called the token and I’ve added my token value to it. That’s going to allow me to come over and run all these calls. So, to get started, this first session is going to be a very basic live stream workflow. There are a couple different options, but we’ll cover what do you need to get up and running and actually send a live stream into the Wowza Video platform and be able to view it.
NOTE: To use in Postman, first import the file below into your postman environment as a new collection, then a global environment variable must be added for the API auth token. To do this in Postman, go to Environments, then choose Globals. Add a variable named auth_token of type default and add the token value you got from your Wowza Video account at token management.
Creating a Live Stream
The first thing we’re going to do — I’m going to clean up over here so you can see what’s happening in the UI as we progress — is create a live stream. We have here a few basic parameters, so we’re going to use the defaults for most of this. We’re setting up a few things here; I wanted to make sure we got a 1080P stream set up. I picked a location and then I picked RTMP as my ingest. So, if I was using like a commercial encoder or something like OBS Studio, RTMP is typically the way you do that.
One of the things Postman is great at is being able to save parts of the responses’ variables. It makes your life a lot easier when you’re doing subsequent calls, leveraging the same thing. In this case, one of the most important things you can save out is your transcoder ID that you’ve created.
We’re going to go ahead and send this. Now, we’ve created a new live stream. Every live stream you create, of course, will have a unique ID. You give it a name and it gives you some information about it — basically reflecting what you asked for above. In this case, some of the most important information you’ll get back is this source connection information, which is how you connect your encoder to the livestream.
There are two different options here, so we’re going to look at the other one real quick. The biggest difference between these two create calls is this here (highlights bottom row of code). This is what’s called the stream source. A stream source has two purposes: the most important one is it allows you to ingest your stream into a location physically closest to wherever your encoder is. So, when you send a stream to that stream source URL, Wowza Video is going to figure out the best place to ingest that stream from and route it to your transcoder for you. Another benefit of using a stream source is the transcoder will auto-start when it sees data if you’re not using a stream source — there are reasons to use them or not to use them depending on your workflow. However, if you’re not using a stream source, you’re going to need to actually start the live stream yourself, which is something we can easily do with this call here.
So let’s go ahead and send it. I’m going to refresh my page and we’ll see that we have a new stream available. In this case, it’s creatively called Wowza Video API Demo Live Stream, and you can see that it is, in fact, starting. So we go over here, we can actually check the transcoder status with a call. Again, we are passing our transcoder ID here, and we can see that it shows us it has in fact started. It has an uptime ID, which you can use to query some statistics and it gives you the IP address should you need it.
Finding Information About Your Live Stream
There are a couple of other things you can do once you’ve created your livestream. When we created this livestream by default, we created a hosted player page and we can go and get some information about that by using this call. In this case, we can get the embed code of the player, the hosted page URL of the player, and the playback URL. This gives us everything we would need to be able to play this stream back. Any questions so far, Rose?
Rose Power: I’m following along. I’m curious about what type of information you can obtain from the player data here as far as the outgoing video bit rate. Would you find that information here, or is that going to be in the next step when we talk about the transcoder usage?
Barry Owen: When you look at some of the analytical stuff — which is our next little block here we’re going to talk about — that’s where you’re going to start seeing information about incoming information into the transcoder, how long the transcoder has been running, and viewer data from the transcoder (which can come either from the player or from the CDN itself).
Rose Power: Okay.
Barry Owen: That’s a good segue, so let’s jump right into that. Now that your transcoder is up and running — we’re not sending a stream to it, but presuming you’re going to send a stream — you can get some information about it. For example, how long it’s been running, or is it outputting any data (in our case it’s not because we’re not sending a stream in)? It’ll also tell you how many people are currently viewing, how long the aggregate viewers, and the average as well. So things you can use, and again, you can see all this stuff in the UI, but for these analytics calls, it’s often very, very useful to get the data back in this JSON format via an API. You can pull this into your own analytics program, or you can use this as part of your stream monitoring if you have a way to react to things and you can continue to pull the API for this data.
Rose Power: Barry, is one of the reasons it’s important to pull this data because sometimes advertisers you work with for your stream would like to see this viewer data?
Barry Owen: Oh, for sure. And obviously you can get the data and we’ll go highlight some of the viewer data here. You’ll see that this one, the transcoder usage call has very basic stuff. What you’ll see here is if you’re going to go get the live viewer data is it’s over time. You have a sampling rate and you can see changes over the course of your stream, which is really useful for not only analysis, but for things like a graphing viewers and things like that. And you can match that to your content like you search for advertisers to see, “Hey, we lost people after seven minutes. All of a sudden people started going away. What happened?” Things like that.
And again, you can see this in the user interface as well. You have over here (left side of screen), you have your stream health, which of course isn’t showing anything because we’re not sending any data in, but it allows you to monitor to see if there’s any problems. Some of the analytics we’re talking about show up on this Get Live Stream Usage Summary page. Between the viewer data, the livestream usage summary, and more, those are all used to populate screens like this. And while you can certainly use this in the Wowza Video UI, you can pull this into your own application, or maybe you have an Elasticsearch or Kibana stack that you’re working with and you want to do your own visualizations. You have that freedom and capability to do that by the ability to extract this data in real time from the video platform.
Important Information to Monitor
Rose Power: Got you. So the transcoder usage is something you should pay attention to, to make sure the stream is working privately and the viewers have a good experience. The viewer data is also important, but the transcoder usage can enable you to quickly troubleshoot should you have a problem?
Barry Owen: Yeah. There’s two things you’re typically going to want to look at: the performance of your streaming platform and your stream itself. Is my data coming in, is my frame rate stable, is my inbound bit rate stable, are things working well? That really gives you the quality of experience that you expect from end to end to see, to make sure your users are seeing the best stream possible. The other stuff you want is more viewer analytics: how many people viewed it? When were they viewing it? Where were they viewing it from? How long did they view it? And those are the things that help you judge the effectiveness of your content and your viewership. We provide both.
Ending a Live Stream
So, that’s a quick overview of how you get some of the data back. Then, now that we’ve started a stream and have some information about it, we can go ahead and stop our event and tear things down. So we’re going to go ahead and we’re going to Stop Live Stream. So you get back a response saying, yes, in fact that worked it stopped. We’re not going to delete it, but you certainly can delete it if you don’t want to reuse this live stream in the future.
One of the other calls that has proven to be quite useful for people is, “Hey, can I get a list of all my live streams? How many live streams have I created? When did I create them and when were they last changed?” This allows you to really just monitor your account and know what’s going on. Obviously if you want to get more information about a particular one, you can pull that via the ID and make another API call and get all the details.
Rose Power: I think it’s important to point out here that you may not be able to find the specific stream you’re looking for by the stream name. You want to look for it by this transcoder ID. Is that correct, Barry?
Barry Owen: Yeah. So we don’t necessarily safeguard you from creating all your live streams with the same name. Obviously, I wouldn’t recommend you do that, but you certainly could name everything “My Live Stream.” So it’s important to persist those transcoder IDs within your application somewhere so that you know what you’re dealing with. If I were writing an application where I’m creating a video platform, I would definitely be persisting my transcoder IDs and probably some other information about them within my own database to use further in the API.
Rose Power: Very important, thank you.
Barry Owen: And that is it for your basic livestream workflow. Please join us for sessions in the future. We’ll get into a lot more details on the full extent of the API. And if you have any further questions, you can visit us at wowza.com.