Wowza Video API Session 3: Advanced Workflows

 

Now that you’re a bit more acquainted with using Wowza Video after API Session 1 and Session 2, it’s time to dive into more advanced workflows. Watch the video above or read the transcript below to learn more about making changes to your live stream, setting it on a schedule, creating loops, and striking a balance between reducing latency and the risk of buffering.

NOTE: You can access and download the Postman file for this session here.

   

Making Changes to Your Stream

Barry Owen: Hey again, everybody. This is Barry Owen with Wowza and I’m here with Rose Power again.

Rose Power: Hello everyone.

Barry Owen: We are going to start with session three of our Wowza API video tutorials. Today, we’ll cover a bit more of an advanced workflow, including some things you can do to tune your live streams and transcoders via the API.

As always, building on the previous sessions, we’re going to start with a new live stream so we know we’re in a good state. I’m going to go ahead and create this live stream. Make note of the name for now. Once you’ve created a live stream, if you need to make changes to it — you don’t necessarily have to delete it and start over. You can update the live stream you’ve created. What we’re going to do here is we’re just going to show a very simple update.

In this case, we’re changing the name, tweaking the buffer size, adding a description, and turning off the stream smoother. The other values you see that are actually the defaults. We’re not really changing those, but they’re in there. We’re going to go ahead and send that. And what we’ll get back is the new transcoder payload that’s been completely updated. What you can see here is the name has, in fact, changed. You can trust me and double check my work that all these others have changed too.

That’s just an easy way to make a change if you created a transcoder and realize, “Oh shoot, I named that my transcoder. I wanted to name it Rose’s transcoder.” It’s easy to change. Now, as far as the behavior of the live stream, there’s kind of two different parts. You can change the behavior of the transcoder like we did here. We are just changing some properties there. You can make tons of changes and adjust all kinds of stuff within there if you want to. There’s also the changer of the output, so how is the HLS output generated? What are some of the parameters of that? And that’s what we’re going to look at next.

 

 

HLS Chunk Size

Barry Owen: One of the things here that we’re going to look at is the HLS chunk size.

By default in Wowza, the HLS chunk size is six seconds, which for most applications is perfectly fine and it follows Apple’s recommendation for the optimum chunk size. However, that will create 20 to 30 seconds of latency in your final output. If you’re looking for lower latency, you can certainly do that. You can change your chunk size to any value really. The only caveat is your chunk size can’t go below your key frame interval. If your key frame interval is one second, you could do one second chunk size. If it’s two seconds, you can do two second chunk sizes.

Rose Power: I have a question.

Barry Owen: Yes.

Rose Power: In the previous step for update transcoder, I thought I saw in the JSON response for a low latency, you had “false.” If I’m new to this and I wanted to lower this chunk size, would I also need to change that setting to “true?”

Barry Owen: Ideally you would to get the cleanest setup. What that does is it alters some internal buffering in the transcoder and the packager that if you are really looking to drive the latency down as low as practical — I want to say practical and not possible, and I’ll tell you why in a second — but yes, that’s a good idea to set that to “true.”

Rose Power: Okay.

Barry Owen: So there are trade offs, right? I could drive this latency down to one second per chunk, assuming my key frame interval and GOP size is one second, but you’re risking player buffering at this point. You’ll need to experiment this with a solid network connection. For your player clients, two seconds will work, but if you’re starting to see a bunch of buffering and things like that, you might want to up this size a little bit to make sure that your viewers are getting the best experience they can. Everything’s a trade off, right? Nothing’s free. To drive the latency down, sometimes you’re going to sacrifice some experience, if not, everybody’s on a great network connection,

Rose Power: Right? You have to find a sweet spot.

 

Balancing Latency and Buffer Risk

Barry Owen: The other thing you can do, this is kind of a nice feature is you can increase the playlist size. In this case, the reason to do that is because let’s say you want to basically enable the HLS to have a DVR functionality from within your player. In order to do that, the HLS playlist needs to be longer so you can actually seek back a certain amount. Otherwise, it’s only going to be three chunks long and we just changed it to two seconds, so you’d have a six second DVR window. That’s not super exciting for someone. In this case, we’re going to change it to 3,600 seconds. Now you have an hour’s worth of scrolling you could do on a live stream. And again, that’s a real simple change and we’ll just go ahead and send it so you can see it in action. And yes, indeed it returned that, okay, cool. I set the playlist to an hour.

Something else you can do, and this is a little bit more advanced, but if you have an RTMP stream coming in and that RTMP stream has data events in it, and you want those data events to come through and persist out into the final HLS output as ID three tags, you can enable this property (enable metadata). It’s advantageous to have timed metadata markers in your HLS output stream. This could be useful for things like advertising, or you could use it to do synchronization between an application that’s on the page with your player and things. One of the examples we built was kind of a version of an HQ trivia app. We used the metadata in the stream to trigger when we would show questions and things like that and make sure they were in synchronization with the video.

For an advanced exercise that we’re not going to go through here today, we have a document that shows you how you can actually inject metadata into a running transcoder without it having to be in the RTMP stream. That basically involves grabbing a URL that allows you to push that metadata in the transcoder directly. We have a document on that, which we won’t go into today because it’s a little bit involved, but just so you’re aware it’s possible.

Lastly, for this section for how you can alter the HLS output and the packaging behavior is the ability to easily add encryption. What this will do is AES 128 and encrypt the actual data chunks of this stream as they’re created. The way this works is you have a shared key that your player can fetch and that the packager uses to encrypt the same. As part of what this is, you need to include a value for the player to go get this key to decrypt the chunks.

What you’ll want to have, of course, is logic within your player and that URL so that you authenticate those users and make they have access to be able to decrypt those chunks. It’s not as all-encompassing as DVR; there aren’t a bunch of specific roles and properties and permissions and things like that, but for certain use cases, it’s enough and that capability is available.

We also have the ability to do DRM within Wowza Video. At this point, it requires you to bring your own DRM account. We’re not going to go into that today, but if you do need full on DRM, that is in fact available.

Rose Power: That’s what I was going to ask you, because I know that you said it’s very easy to set it up in the API call, but before you can do that step, you have to actually set up a DRM account with the provider that you’ll be using, correct?

Barry Owen: You do. Fortunately, the configuration is really straightforward. You can configure it via the API, or you can configure it via the user interface. I didn’t show it because I don’t have a DRM account to show you. So that kind of wraps up the somewhat simple things you can do as far as updating, modifying tuning, tweaking a live stream once you’ve created it.

 

 

Loop Until Live

Barry Owen: Next, we’re going to talk about a cool little application that I know Rose gets lots of questions about, and it’s really useful for scenarios where you either have a live stream running and you want to put up a slate or something like that will play — it could play anything, right? I mean, you could be playing advertising. You could be playing just any kind of pre-roll until your live stream is available. We call that loop until live.

Basically, what that does is it allows you to specify a file. Again, this file can be any MP4 file. You want to make sure that the file itself is encoded the same way your video source is. If you’re sending a 1080P stream as your live video, you want your filler file to be a 1080P stream — ideally with the same encoding parameters, as far as key frame interval and things like that. The bitrate can be different, that doesn’t matter as much.

So, we’ve created our live stream. Again, this is a modification of an existing live stream. We’re going to go ahead and send that — uh oh — I’ve got an error. I discovered that I was trying to send the wrong command when I needed to send a post, I think I was sending a PATCH. So, it didn’t work, but now it’s all squared away. Now, we’re going to send this, and this will configure our transcoder to loop the file when either previous to the source arriving, or if the source goes away.

One of the other options you can do for this file is if it’s shorter, or if you’re just trying to loop a slate — there’s no reason to have an hour-long slate — you can have a short file and set it to repeat. We’ll go in here and just set a property of the loop until live. That allows me to make that file repeat for as long as necessary until the source file arrives.

Rose Power: So, Barry, when you said you could use loop until live — this API call — if the stream goes away, you mean if something happens with the encoder, your stream drops, it will switch over to this MP4 file? Then when the encoder comes back, it switches back to the live stream?

Barry Owen: Absolutely. And there’s a configurable timeout for that. Sometimes your encoder may be struggling with reconnecting and disconnecting. You don’t want to constantly flip loop until live in. Let’s say your content encoder goes away for 10 seconds; you can have it so it kicks the slate in and could be technical difficulty or whatever you want to say there. And then when the livestream comes back, it will resume.

Rose Power: Cool.

 

Scheduling Live Streams

Barry Owen: One other feature that we want to look at here is super useful, which is the ability to start and stop live streams on a schedule. What you can do is create a schedule, and what the schedule requires is a few things. You can have start-only schedules, start-stop schedules, or you can have a stop schedule. Then they can kind of run all at different times. What I have here is a combined one that will actually start something and stop it after a certain duration.

And all that’s really required in here is the transcoder ID. So, the transcoder ID or the livestream ID, you put that in there and create the schedule. In this case, my schedule’s going to run every weekday (though my schedule for this example might not make a lot of sense because I have it running for multiple days), but it’s basically going to start and stop the transcoder. I have it set up to start the start and start the transcoder every 14 days, so let’s change it. We’ll change it to the 15^th and have it start at zero. Now, it’s going to run every weekday for 15 minutes.

So, we’re going to go ahead and create the schedule. Gives you success, shows the schedule, shows the data you sent and by default, the schedule is enabled. That’s important to know: once you schedule, once you do this, it’s going. Of course, you can disable the schedule. That’s fairly easy to do. You just call disable, which tells you it’s been disabled, or re-enable it. Now it’s enabled again. Off course, if you don’t want it anymore, you can delete it. It’s also possible to update the schedule. Once you’ve created the schedule, if you actually want to modify it without recreating it, you certainly can. I find it’s usually easy for schedules that are fairly lightweight, I just delete them and restart them.

Rose Power: I was going to ask you about that because there are people that have regularly scheduled streams every single week and they need to just go in and embed the new stream, their most recent video. So, you’re saying they have an option — would that be a PATCH request?

Barry Owen: Yeah, you could do a PATCH request basically at this same end point here and just change the transcoder ID.That would actually apply this schedule you’ve already created, but modify it to work with a different transcoder.

Rose Power: Okay. So you could go this way or you could do it the way you said. It’s just easy enough to create a new one if you want, but you have the choice.

Barry Owen: Yeah. It’s up to you. It’s kind of how you prefer to manage them and keep track of them and things like that. And of course, once you’ve created these, you can certainly go see them in the UI. So we’ll go look at this one real quick and we’ll send this one again since I deleted it. If you go over here in the UI, so you’ll see my schedule’s been created and it runs every weekday for 15 minutes.

Rose Power: Great.

Barry Owen: Cool. Well, that’s it for this session of our talks. I hope you find these methods useful for you to kind of fine tune your workflows and add some cool new features. We’ll see you back for the next session in a few days.