Using the Wowza Streaming Engine DVR Clip Extraction API

Justin Miller:

Hi, I’m Justin Miller and with me is Tim Dougherty. Tim, how’s it going?

Tim Dougherty:

It’s going pretty good, Justin. Thanks for bringing me on today.

Justin Miller:

Well, glad you can be here to talk about DVR Clip Extraction API, which is quite a long name for hopefully something that everybody wants to do.

Tim Dougherty:

Oh, clip extraction is super exciting. A few years ago, we wrote a module that would actually go into a DVR store and create an MP4 file. And we thought it was great. Over a period of time, we were able to get it into the product. So you might hear me call it a module, because it used to be a module. Now it’s actually part of the REST API offering.

Justin Miller:

Awesome. Sounds definitely useful. Now this is specific to when it was a Wowza Streaming Engine, correct?

Tim Dougherty:

Definitely. Yeah. It runs on Wowza Streaming Engine. I’m using version 4.8.5 today. I think it’s been in the product for awhile, but as a general rule, we would recommend using the latest version of Wowza no matter what you’re doing. So, yeah.

Justin Miller:

Okay. Well, why don’t you show us how exactly it would operate then?

Tim Dougherty:

Yeah, let me show you. I’ll share on my screen here my browser, and right here is the technical article that’s the foundation for what we’re doing today. Let’s talk about the use case first. You’re a live broadcaster, maybe you’re doing sports, maybe you’re doing some type of live event, and you would like to maybe pull out parts of the event that you could post on social media or break up into segments. It’s essentially a way to take one big, long event that might be eight hours long, and record an hour of it for a session or record 30 seconds of it for a highlight. Essentially what we’re doing is we’re going into this huge cache of data that our DVR creates, and we’re grabbing chunks of it and combining them together, just a little bit of background on the DVR. It’s something that people are familiar with as consumers, typically with live TV.

You might remember TiVo came out years ago. There’s set top boxes from companies like AT&T TV and Comcast, CenturyLink, and it goes on and on, but you have the ability to go back a minute, or 10 minutes, or half an hour during a live program and see something in the past. So that’s a DVR, N-DVR we call it for network digital video recorder. So we’re manipulating that data today.

Justin Miller:

Okay.

Tim Dougherty:

So anyway, it just kind of in our series on the API, Justin, this is the base article, and I’ll peruse through it here briefly. Then I’m going to actually show you some of these API calls in real time. So first of all, when you set up the DVR, it creates what’s called a store, and a store is actually representative of that DVR recording of that live stream.

This is the command here, and if you were to get this article, we make it freely available on our website of course. If you did a search for Wowza DVR clip extraction, this would probably come up first. This command here get a list of DVR stores, which ultimately will list the DVR stores that you can extract from. You can dive-in and get details on that DVR store. What other examples, you can convert that store, which is what I’ve been talking about. So you go in and you convert a segment of it, like a minute of it, or from 5:00 PM to 5:05 PM. You have the ability to convert. You can do groups of stores, in case you’re using the transcoder, and then there’s a set of custom properties that are available here. So it’s a really powerful tool for converting recordings, for using an archive strategy, or even for going in and getting highlight information.

This is the article right here, essentially the how’s does it. I just would rather just show you how to do it, which is a lot more fun. So, here I’ve got Wowza Streaming Engine running. You can see I’ve got version 4.8.5, and then if I go to my applications, I have an application called Live DVR, and I have an incoming stream called MIB, and you’ll know why it’s called MIB in a second. Just to give you an idea of what’s happening at this point, I’m going to go ahead and play this stream in its live state. Just so you can see the DVR in action, because I do have the DVR configured over here in this option where I have the ability to record up to two hours right now. I could configure it to be unlimited, or I can configure it to be maybe half an hour, two hours is just a nice, safe, small amount of disc space, and there’s some DVR options here and we have our DVR configuration, very well-documented.

I’ve got the DVR turned on and I have this incoming stream. Over here I have THEOplayer set up. I believe this is it over here. So there’s my server address. There’s my application name, Live-DVR. There’s the stream MIB. And then this is the HLS playlist. Then the URL append for the question mark with DVR, that means the player’s going to pull from that DVR storage. When I go to load this stream and play it, I’m going to mute the audio here. So it’s playing the stream, you might see a little bit of jerkiness, because I’ve got a lot going on on my computer right now, but what I want to do is, I’ll just keep playing it here, is to show you that I can go back in time. I can go back 20 minutes. This is a live stream. It’s pseudo-live, so obviously it’s recorded, but see how I can go back and I can enjoy this DVR queue and I can go back and see what I missed. This is essentially the Wowza DVR at work.

That’s the baseline right there. That’s what’s happening here with this stream that’s coming in. So what I would like to do is actually convert this into an MP4. Let me expand my work area a little bit. You should see now my browser, and then I also have Postman running, which is a API client. And you can in fact, let me bring up Postman a little bit, little more in a zoomed in capacity. I have all of the DVR, well I have a handful of DVR API requests already programmed into Postman. So those were the items that I was showing you early in that article.

For example, if I want to fetch the DVR recordings, I can send that command. It’s checking my Wowza server, and it tells me that there’s a DVR called MIB. That’s the only one that’s in there right now. That means I’ve got a DVR store called MIB. Well, I want to learn a little bit more about it. In Postman, it’s really cool, you can actually set the variables. So I’m going to set the variable to mib.zero. Then I’m going to drill down a little bit, this is another command called fetch a DVR recording, so this kind of lists all of the DVR recordings, and then this just fetches one DVR recording. I’m going to run that. Come on. Little bit delayed. And again, I’ve got so many things capturing on my computer, so I have to be patient.

This is the DVR store called MIB and it’s going to give me a whole bunch of information. In particular, it gives me the start time, it gives me the end time and the duration, and these are in milliseconds, and then this is an epoch time. Again, that’s getting into more detail than we want to get into on this call, but I can see that I have this DVR available to capture.

Justin Miller:

Awesome. I’m assuming one reason why you want to use Postman for something like this is because it formats the output like we’re seeing here.

Tim Dougherty:

It does. It’s great.

For some of these more complicated DVR requests, like I’ll go back over to my browser. I kind of scrolled over earlier, sometimes there’s a lot of parameters, a lot of payload in some of these, and these can all be run from the command line, but I like to do it in Postman, because it keeps them organized and I’m not necessarily here to promote Postman, but it has been a great tool.

So let me just cut to the chase. Let me do a DVR conversion here. This is my combined screen, I have Postman in the upper- right. I’ve got my browser over here in the left, and then on the bottom, you can see that I’ve got a FTP client that’s connected to my server. Now that I’ve got this DVR recording here, I’m just going to convert a DVR recording based on duration. I’m not going to get too crazy with it. The first thing I want to do is expire DVR conversions. That’s just a housekeeping thing that you want to do before you run any DVR conversion workflows. It just clears the memory of anything that may already be working, then I’m going to convert a DVR store based on duration.

What I have here is the command up here in the put, this is a put command that I got from that article I showed earlier over here. In fact, it’s probably sitting here. Convert a DVR story, this is the actual command I’m using, but then there are also some parameters on here. So there’s a start time and an end time and then there’s also an output location in this particular API command. I need to make sure I have an actual proper start time and a proper end time. I’m going to go back to the fetch DVR recording, and I’m going to scroll down to where it says the start. The start time is right here, so that’s 160, this is a big, long, epoch time. So I’m just going to grab that number and paste it in here.

Justin Miller:

Justin Miller:

So that’s including the year and…

Tim Dougherty:

Yeah, let me paste it in here. If I go over to an epoch time or yeah, I think epoch time converter will do it, and I already have one up on my browser. I’m trying to click to it, but it my computer’s not being very responsive. So I just grabbed that number.

Timestamp to human dates, so that’s October 14th at 7:19 PM Greenwich Mean Time. So that’s basically it’s starting at that time, over here, and then the end time, I’m going to adjust that to where it’s just a little bit later. So these three digits are, I basically ignore these. And then there’s this 3193. So I’ve got 3193, I’m going to make this like 3260. So that’s 193 seconds to 260 seconds. It’s going to create a file called, I’m just going to make it… This one’s called one minute post. So I’ll just hit send the command. It’s sending the request to Wowza, and that says conversion started. I can fetch that DVR recording again. Get a status on it. If I scroll down, I can see the conversion status is stopped, which means it’s essentially completed and then if I go over here on the bottom to my FTP directory and refresh that, there’s the file.

Now I have a file called one minute post that I just created. I’ll jump over to my player and I was testing it earlier, I’m just going to erase that five, load the stream, hit play, and you can see that I’ve got a one minute and seven second file that I’m playing. You noticed earlier, it was this big, long DVR store and it’s playing back the file right now. Now it’s having a little bit of a hard time. My computer is under an incredible amount of load today.

Justin Miller:

No, I completely understand trying to do all these things and running Wowza Streaming Engine on your computer, it’s a lot for it to handle.

Tim Dougherty:

Really busy. Yeah, but I do think it illustrates what’s going on. You can see that the file size here is 3.9 megabytes. It’s just a short one minute file. Then it’s really a Chrome browser I’m asking it to play multiple instances of THEOplayer, and I’ve got a lot going on, but that’s just kind of the long and short example of how the DVR queue works. I know it’s kind of you’re over here in Postman, and it’s sometimes these API requests can be fairly dry, but at the same time, very powerful. If you wanted to convert a recording, you just go in here, you can enter in your wall clock time literally, and say, “We’ve been recording all day. I want to grab a clip from two o’clock to 2:45, because that session was highlighted in our program.” You can do that, and as soon as it’s converted, which in many cases only takes seconds, it’s available for a VOD playback application. So it’s pretty cool.

Justin Miller:

Awesome. Yeah.

Tim Dougherty:

Yeah.

Justin Miller:

Well thank you for showing us, for sure. For those interested in checking out this and trying it yourself, please do go to that documentation. And Tim, if you want to bring that up once again, just so we can see it, but I’ll also put the URL down there and for those who don’t want to use Postman, certainly you can choose to use the cURL commands that we have available. There’s just a easy copy button right on the page I believe, if we want to scroll down and just take a look at that. But as Tim is pointing out, Postman is definitely a great way to go to be able to see all the information formatted properly after you use a get or put command to send it through. So thank you once again, Tim. Glad to have you.

Tim Dougherty:

My pleasure. Just glad to be here, Justin.

Justin Miller:

Everyone, thanks for watching.

Tim Dougherty:

Thank you.