Using the Wowza Streaming Engine REST API

Justin Miller:

Hi, I’m Justin Miller from Wowza Media Systems. And we’re here with Tim Dougherty. Tim, how’s it going?

Tim Dougherty:

Hey, Justin. Doing good!

Justin Miller:

Well, today we are going to talk about APIs, specifically the REST API for Wowza Streaming Engine. Now, Tim, I know this is an important topic for us. We don’t often get into the weeds like this, where we take a deep dive into Wowza Streaming Engine and kind of look under the hood and figure out some of the more important aspects. All right, I’m going to call them more important aspects. Not sure if you feel that way, but quite honestly, one of the greatest things about Wowza Streaming Engine is our ability to control it via the REST API. And it’s one of the things we talk about the least.

Tim Dougherty:

That’s right. It’s the ability to bolt a whole other application onto a streaming server, and Wowza can take all these commands and do a variety of functions in the background so that someone like me, who’s not a developer, or someone who is a developer can get a little more advanced, but not have to write their own deep level streaming applications. So it’s a really cool way to control Wowza Streaming Engine.

One thing that I’ve noticed around some of the senior engineers and integrators with Wowza is they really like to brag about not having to use the manager, which is the graphic user interface. I think it’s a great tool for people that are learning Wowza Streaming Engine, but what we’re doing today, effectively would give you the ability to remotely send commands to Wowza Streaming Engine without using the manager at all. So it’s kind of an advanced way, and to say we’re in the weeds is accurate. And I’m in the weeds. Again, I’m not a developer, but I love to hook things up together. So you’ll kind of see how just anybody can come in, take a look at the API and get Wowza to do stuff for them. So that’s kind of my approach, Justin.

Justin Miller:

I think it’s great because I know that other companies are using us on their backend, they can create their own user interfaces that are simpler, and can make sure that their clients can achieve the things that they need to do using engine to start and stop streams. Just some of the basic level stuff that’s, or even more so maybe there’s more detailed stuff. Because honestly, I don’t know a lot about our API and all its capabilities. And while I know we’re going to be showing some of this just on a more basic level, we’re not creating GUI interfaces here. We’re just going to be doing it from a terminal so people can see it at the most simplistic level of executing a command, but I know that things can start at that point and then become like graphic user interfaces specific to a company that might brand it under their own name.

Tim Dougherty:

Definitely. Yeah, and that’s that’s the whole idea, is to get in and just demonstrate very simple using CURL commands that Wowza’s REST API is available and it’s something that you can hopefully take advantage of. And to note on using a GUI, this is Wowza Streaming Engine Manager. Most Wowza users are very familiar with this. This actually is a application that uses the very REST API that we’re talking about today. So right now you see the developers APIs and SDKs page. We’ve got a variety of information there. I want to focus in on Wowza Streaming Engine. So I’m going to actually click on that. And this is intended as an orientation, kind of a starting point for people that want to use this API, and we try to make it really cool. We got an overview which talks about authentication, which is an important aspect, setting up your Wowza server properly on the right port, using the right type of authentication digest, or no authentication if you feel safe and you’re behind a firewall.

We’re not going to get lost in that world of actually setting up the API today. This is intended to be a little more brief. We were just going to go through a couple examples. So if you want to learn how to set it up, you have this overview, there’s a few examples here and then there’s the actual reference to the whole REST API. So I want to, if it’s all right with you, Justin, I want to go through a couple examples here that I think are real-world applicable. If just browsing the store here, you can see that there are a few articles. I see SMIL jump off the page. I see statistics jump off the page. Again, these point to some common API commands. For example, people like to see how many users are connected to a server or how hard a server is working. There’s a variety of statistics you can pull for.

Today, I want to go in and I want to create a stream file because a stream file is used to connect to an RTSP camera, like an IP camera. So I’m going to create a stream file that goes to an RTSP stream. I’m going to connect that stream file using the API. So I create it, the next command is to connect it. So it basically tells Wowza, hey, IP camera, I’m going to stream from you now. And it pulls the stream in. Then I’m going to turn a recorder on that stream that I just created, we’ll record it for 30 seconds or a minute or so, stop the recording and then stop the stream. So just a few API commands. And I think you’ll see just in this process, a real simple way to digest the example and then test it. You got to modify it and then test it and see how it works. So Justin, that’s kind of my approach. What do you think?

Justin Miller:

Yeah, that sounds great. I definitely have a question for you right now, though.

Tim Dougherty:

Sure.

Justin Miller:

I’m familiar with in Wowza Streaming Cloud, our service, we do stop in, or rather start and stop streams regularly, but Wowza Streaming Engine is always running because it’s your own service, unless you choose to spin it down, for whatever reason. You had mentioned stopping the stream. And I was curious, are you talking about stopping or are you talking about disconnecting it because it is using our TSP.

Tim Dougherty:

I appreciate the clarification. It’s connecting the stream file and then we’re going to disconnect the stream file. So starting and stopping, it’s kind of just start, connect, stop, disconnect. I’m using those terms interchangeably. I probably should stay a little more on the connect and disconnect side.

Justin Miller:

Because if it was an RTMP stream, we wouldn’t be disconnecting.

Tim Dougherty:

No, if it was an RTMP stream, you actually can go connect to an RTMP stream and you use the MediaCaster Type, Live Repeater, instead of MediaCaster Type, RTP. So you can do the same thing with RTMP as we’re doing with RTSP, because the MediaCaster has the ability to go get the media.

Justin Miller:

Oh, okay.

Tim Dougherty:

But in most cases, an RTMP stream is pushed to Wowza. So you wouldn’t need a stream file to connect and disconnect to it. So yeah, I think a good assumption here is that, in these examples, we’ll be connecting to an RTMP camera, RTSP camera, sorry.

Justin Miller:

Well, you know I love IP cameras, so let’s check this out. I’m excited.

Tim Dougherty:

All right, cool. So I have this tab open. This is the article right here, create and manage stream files. I have it right here. And I’m going to, first of all, create a stream file. So I’m going to scroll down and I’ll be honest with you, I just kind of looked through these articles, like get a list of stream files. I don’t need that. Add a stream file. Oh, that’s what I need. Add a stream file. So I’m really rough and tumble. I’ll just take this code right here and copy it. So this little blurb here, we’ll copy it to the clipboard and then I will switch over to my editor. You should see my editor come up on the stream.

Justin Miller:

Yep.

Tim Dougherty:

I’ve done this previously, so I wanted to be ready for our session today. But if I paste that, that’s under connect, sorry, there’s create a stream file. So there’s my code that’s already been modified, and then I just pasted this. So you can see when you’re pulling stuff from the example, it’s going to local host, that’s if Wowza was running on my local machine, which it isn’t, and then it has some generic information here. Now down here, the command that I modified, I entered the IP address of the server, which is an adjacent server on my desk here. I confirm the application, which is Live. And then I created a name for the stream file called Drone Live. And then I put the actual RTSP link to that stream. So I’m going to copy this and I’m going to go over to my text, or excuse me, my terminal. So you should see the terminal I’m going to paste it and I hit enter. You can see very quickly that it says success, true, message. So, it’s basically Wowza saying the stream is working.

So, because I want the cause and effect, I’m actually going to go back over to Wowza Streaming Engine Manager, and I’m going to go to applications, and Live, and incoming streams. You can see that the stream file has been created. I was getting ahead of myself. So you can see the Drone Live stream that I just created with this information is here. If I switch back to my editor, you can see there’s the IP address for the RTSP and there’s the name, I just created that. You can see it, of course, right here. So that’s kind of a cool cause and effect.

Now the next thing I want to do is connect the stream. So I’ve added the stream file. The update would be if I needed to change the IP address or some properties in there, I’m just going to skip that for now, it’s too advanced, and not much fun. I just want to connect the stream file. So again, I’m going to take this and copy it, go back over to my editor. This is where I was earlier, connect a stream file and I paste it. So again, here we are in the editor and we’re trying to determine, all right, I just pasted this from the example, but I need this to work in my server. So these are default things, the accept and the content header, so those are generic. They’re pretty much the same for every API call, but these URLs are very loaded. There’s a lot of information here.

So again, I’ve got to have the correct IP address, which used to be local hosts, which I know is right. And then in most states, defaultServer, defaultVHost can stay the same as the example. But live, in case you’re using a non-default application, like Tim’s awesome stream, or Justin’s Naturescapes, you can have your application name and then you also have to make sure that the stream name itself is correct. So, Drone Live is the actual stream name and one thing that’s kind of interesting is when you disconnect, you don’t have to include the .stream in there. You just include the DroneLive, and that’s implied in the example. So anyway, talking too much here. I’m going to go ahead and connect this stream. Copy.

Justin Miller:

No, good information to know that that entire URL is necessary.

Tim Dougherty:

Oh, very definitely. So I’m going to paste it in as a CURL command here in the terminal. So now you can see that it says publish stream successfully started. Which is good news, right? So we’ll go back to Chrome.

Justin Miller:

I just went off to success true. That was my notification.

Tim Dougherty:

Success true works as well. It’s a good feeling when you actually have success true with these APIs, because there is a little bit of trialand error. So I’m going to refresh the incoming streams and you can see that the Drone Live stream is now connected. If I click on it, you can see that there’s data coming in and I even have a player over here from THEOplayer, and I can start playing the stream over here. So I’ve actually connected it, which is cool. I’ll just let that play and then, am I going too fast or do you want to record it, too, Justin?

Justin Miller:

No, no. That’s great information here. I was actually kind of surprised that you could use THEOplayer. I’m curious, is that because you’re on a local system right now, correct?

Tim Dougherty:

I am, that’s right and the way I did that is, see this streamlock.net domain?

Justin Miller:

Yes.

Tim Dougherty:

I created a SSL certificate that points to that 10.0.1.9, that local IP, so that I can do HTTPS between my servers locally. I like to use all these cool browser tools and you can’t have HTTP mixed with HTTPS.

Justin Miller:

Right.

Tim Dougherty:

Yeah, that’s kind of the sidebar, but yeah, that’s how we’re doing it.

Justin Miller:

No. Good to know because I think a lot of people have that issue, they’re trying to test using something like THEOplayer and they’re unable to because they’re running it on a local system.

Tim Dougherty:

Yeah. That can be somewhat frustrating, but I do a fair amount of testing and proof of concept with our customers. So when I do that, I really like to have everything secure and for it to look kind of buttoned down, but that’s just me being OCD a little bit. So yeah, that one’s free. Let’s record this stream, Justin. So we’re still working.

Justin Miller:

All right, yeah.

Tim Dougherty:

Yeah. We’re still working through this document on stream files with the API. We’re going to come back and disconnect later, but over here, this other article, which I believe was linked here, which is create and manage stream recorders. So, that’s this article right here and basically what I want to do is create a recorder. So I just clicked on that. It zoomed me down to, let’s see, it looks like the anchor was off a little bit, that’s get a list of recorders, create a recorder. So recorder is Wowza recording a stream. There can be a lot of information involved with it. This is the command right here and it looks kind of intimidating to be honest.

Justin Miller:

A lot of details.

Tim Dougherty:

Yeah and honestly, as just an integrator at face value, when you start seeing all these parameters, it can get really intimidating. Don’t be intimidated by it, it’s really no big deal. You’re sending a URL to your Wowza server. Get in, get your hands dirty and mess with it. So I’m going to copy that text and I’m going to move over to my editor and you can see that I’ve tested this before, so I know that this works. But I want to kind of do a comparison, so I’m going to open up a couple of lines here and paste in that code example.

So this is the code example. There’s local host, live, stream recorder. It’s going to try to record my stream, which doesn’t exist because I have droneLive.stream. So some of the key data points in here are, first of all, the IP address, you want to update that, we’re still using application live. So application slash live and then the stream recorder is named after the stream. I created this earlier, droneLive.stream, and see that capital L, that’ll get you. So it’s drone capital Live.stream. So my URL is good. And there’s a whole bunch of information in here that you can use if you want.

So for example, I’m telling the recorder to be called droneLive.stream. I actually think it would, if it was left blank, like it is in this example up here. Oh, it wasn’t blank. The example has the stream name being inserted as the recorder name. So that one I changed. But there’s a base file name, which I left blank. I think you can change that. Start time, you can experiment with a whole bunch of different settings here. But again, I’m just trying to do a straight demo with everybody. All I did was update the recorder name. I’m going to copy this whole block here.

Justin Miller:

Can you scroll up for one second though, for me?

Tim Dougherty:

Absolutely.

Justin Miller:

So, I can just compare with the other one. Well, I’m just noticing, just like you’re stating, there’s many things that don’t have information put in, like recording start time. But we have like key, start on key frame is true. Move first video frame to zero is false. So it seems like there are quite a number of things that already have specific information placed in. The only thing that I see that you really changed is that recorder name, right?

Tim Dougherty:

Yes. That’s right and, again, I just figured that out on my own. I don’t know if there’s a how to article on what you need to and not need to place in recorder name.

Justin Miller:

I mean, it’s good to know for people that the URL at the top and then that recorder name are probably the only two things you’ll need to change, at least in this initial test.

Tim Dougherty:

That’s correct and I want to emphasize, Justin, it’s really important to not be intimidated by this, to make mistakes, use a system that’s not in production, and just kind of go through the struggle of figuring all this out. Because you’re right, some of this stuff is pre-populated and that’s probably based on best practices. So in my case, again, I just want this thing to work, so I just want to be able to start that recording. I’m going to take this big block of text, which seems excessive, and just real quick, I’m going to switch over to Chrome for a minute. I want to show you something. If I go back out to my incoming streams and refresh it, I could press that red button to start recording. So it’s in a non-recording state, switch over to terminal. Let me clear the screen for you.

Justin Miller:

But it’s good to see that we have that GUI interface. You can see we’ve already created this, basically, using the same system for the manager and here you are now showing how to do it with the API.

Tim Dougherty:

That’s exactly correct. So I’m going to press enter, and it says, to your point earlier, success true. That’s a good feeling. Recorder created and if I switched back to Chrome and hit refresh, you can see that the recorder is created. Probably can’t see this too good in the screen recording, but it’s actually telling you the directory where it’s actually being recorded. So now we’re recording the stream, which is exciting, right?

Justin Miller:

Recording in progress is definitely the good status, right? That’s what we want to know.

Tim Dougherty:

That’s right. That’s the good status, so once you start a recording, what’s the next logical step? Justin, what do you think?

Justin Miller:

I think it would be, well, I would say stop the recording. You might be doing pause the recording. I’m not sure, now that you’re asking.

Tim Dougherty:

Well, I’m not going to get that detailed, but the API and the live recording component in Wowza, you can split the recording segment and the recording. If you look up the article on how to record streams with Wowza Streaming Engine, there’s a nice set of options.

Justin Miller:

Okay, but that being said, as we’re talking about it here, you can see them directly through our own manager that we have it. We have the stop. You have the split, right. That line with the three dots on it?

Tim Dougherty:

Yeah. This is the Manager version of it. So the file name, the path, these are all configurable in that API.

Justin Miller:

Okay.

Tim Dougherty:

Segmentation.

Justin Miller:

I was specifically looking for, if you can escape out of this for a second, for Drone Live that you created. If you look under actions, I mean, we have the big black box for stop. And then right next to it…

Tim Dougherty:

Oh, that’s right. Yes.

Justin Miller:

… I assume you have that split recording. So all the API calls you’re talking about, you can see that we have the capability here. Therefore, we must have an API call available for it.

Tim Dougherty:

That’s an excellent observation. I’m glad that came up. Pretty much everything you see in the Wowza Manager can be duplicated with the API. Towards the end I’ll go over this briefly, but this is the list of API commands in its raw form and there’s a lot there.

Justin Miller:

Right and to your point, when you went in and brought up that other window, you were showing that these are changes that can be made through Manager, but you could also make them through the API.

Tim Dougherty:

Definitely. But I’m going to step back in. I’m just a regular guy, I tried to learn this API. I want to stop it and I don’t know how. I know I have a cool button in my GUI, but I want to be able to do it through a CRON job, or I want my application to be able to send a webhook. So I’m going to go back to this manage recorders and I’m like, okay, create a recorder, split a recording. Oh, that’s kind of a cool thing, but I don’t really need that right now. Oh, stop recording. We have a winner right here. So again, I’m just going to copy that block of text, go back to my editor, and I already set one up before, but again, it’s that same dance, right? Where you make sure the IP is updated and I’ve got the application name and then the stream recorder was called droneLive.stream.

So I was a little bit mistaken earlier, I think I said disconnect, when I was talking about when you start a recording, you only have to have… Oh, no, I’ve got that right. Just scratch that from the record, everybody. Sometimes you’ll see in the example, that it’s referring to a .stream file, and sometimes you’ll see that it’s just referring to the name of the stream file. So just be sensitive to that in the example. If the example you’re dealing with a stream file doesn’t include the .stream example, then you don’t have to put it in there. Pardon the confusion. So to stop recording a live stream, I’ve got local host, I’m going to switch it from, instead of my stream will be droneLive.stream, and this should stop the recording. So I’m going to grab this, go back over to my terminal and I’ll clear the terminal and we’ll paste it in. You can see that it’s exactly what I had in the text file. Recording stopped.

If I go over to Chrome, you should see that the recording, which was previously in this state, has stopped. So I’ve successfully connected the stream file, recorded the stream file, stopped the recording. So I’m kind of struggling through it, Justin.

Justin Miller:

No, you’re doing great. I’m learning a lot while you’re doing it.

Tim Dougherty:

So let’s do the final thing. Let’s disconnect that stream. So we’ll go back to the managing stream files article. Disconnect a stream file. Okay? So we’ll do what I’ve been doing the whole time. Copy it. Compare it. Oh, that’s not right. I did something wrong. Copy that block, paste that block. There it is. So, IP address, right? We’ve got that loaded. Application.

Justin Miller:

We’re still seeing the same screen. I don’t think you’ve switched screens from the…

Tim Dougherty:

Oh, sorry about that.

Justin Miller:

No problem.

Tim Dougherty:

There we go. There we go. Thanks for catching me up. So I just pasted this from the code example and then this is my updated version. So I’ve got the IP address updated, and then I’ve got the application name updated and then the droneLive.stream. So it looks like this API call is clean and again, do this in a text editor because if you’re doing it in the terminal, it gets really messy. So I’ll switch over to terminal, I won’t forget this time and again, we’re going to go to that IP.

Justin Miller:

I noticed what you were talking about here, where it showed credence.stream to let you know that you needed that .stream at the end.

Tim Dougherty:

Exactly. It’s a true working example. I’ve just seen a couple of commands where I don’t know if it’s disconnecting the stream, no, it wouldn’t be disconnecting, where one of them… it doesn’t, you don’t have to have the .stream file, but the other ones you do. So it could be developer A did this one and developer B did this one. Just be mindful of that nuance. So I’m going to hit enter here, publish stream successfully stopped. That means it’s disconnected from the IP camera and we can go back to Chrome.

And just because I really liked the cause and effect, you can see that the stream has gone and we’ve gone through that particular cycle. So how am I doing Justin? Are you getting a good idea? A little bit of an idea?

Justin Miller:

Yeah, absolutely.

Tim Dougherty:

Okay, cool and again, I wanted to be transparent. When I’m working with the API, I like to just scroll through these documents and I like to test the example code and I like to try things myself. If you’re a more advanced developer and you’re more experienced with API programming, we have quite a variety of options with Wowza Streaming Engine. What we’ve been doing today was under the applications section where you can go through and for example, if I scroll down here, I’m looking at the URLs, I’m looking for the stream files, like see this right here, retrieve a list of stream files. If I just type in my live application and I hit try it out, you can actually interact with the API in the swagger documentation here.

So you saw how easy that was, right? If I want to add a stream file, I can do it right here in this example where, app named Live. I might be getting a little bit into the weeds here, but you can actually define it right here. So let me do this really quick. See if I can get this right, so I created a bogus URL and then the name of it would be Tim’s camera, and I’ll hit try it out. It didn’t work. We don’t have time in this demo, but basically what I’m showing you is that you can go through and interact with the API here in the deeper documentation and as you can see, with me kind of mumbling along here, it’s kind of fun to see all the different settings you can get ahold of.

Justin Miller:

No, absolutely. There’s a lot of you can certainly test out to verify it works and of course, I think one of the main things that you said right at the beginning, when you were talking about testing it is, “Don’t test it on the production system.” You really should have this somewhere where you can just try these things out, a little sandbox mode, as it were, to just verify what you can and can’t achieve. I get really excited when I see things like this, because I think of it just from the perspective of say, building an app. You want things to be controlled from your phone these days and being able to do so requires something like the REST API.

Tim Dougherty:

Oh, definitely. Just to kind of just dive off of your, use a production server versus a dev server, dev versus production. To set up the API, you have to create authentication schemes. You have to enable the documentation server. In those documents that I was referring to earlier in Chrome, there’s somewhat of a setup step here when you get the API working. So you have to open up ports, you have to kind of go through an iteration of just getting the API available. I think it’s well-documented, but we didn’t go through those steps in this demo. So just wanted to call that out, Justin.

Justin Miller:

Right, and definitely appreciate it. And thank you for joining me and talking about the REST API, Tim, definitely appreciate it. For those people, once again, who want to know more about some of our other options, not just for Wowza Streaming Engine, but for some of our other products, definitely, this is a great place to go. If you scroll up to Developer APIs and SDKs, they’re under wowza.com/docs, this is the best place to start. And definitely, as we said, take a deeper dive into our products. All right. Thanks again, Tim. And I hope everyone has a great day.

Tim Dougherty:

Thank you, Justin.

Justin Miller:

Take care, bye now.