Wowza Video API Session 2: Recording, VOD Streams, and Custom Stream Targets
If you’re using Wowza Video to unlock the power of video for your business, you need to know everything you can do with our innovative API! Watch the video above or read the transcript below to learn how to create live streams with recording or VOD streams, as well as how to set custom stream targets and explore what their use cases are.
Table of contents
Creating a Live Stream With Recording and VOD Streams
Barry Owen: Hi, everyone. Barry Owen back again with Rose Power.
Rose Power: Hello, Barry.
Barry Owen: Good to have you, Rose. Today we’re going to do our next session in our Wowza Video API talk and will focus on things a little more advanced, including how you can create live streams with recordings or VOD streams. A recording is an MP4; a VOD stream is an HLS archive. They have different use cases; you may want one, you may want both. And then we’ll talk a little bit about custom stream targets and how you might use those and what those are for.
Let’s jump right in. We’re back in Postman, like we have been previously, and we have a new payload that’s slightly different. We’ve got a couple things here that enable the recording for this live stream, so we’re going to go ahead and create it.
While that’s cooking, we’re going to come back over here (left side of screen). We’re going to refresh our page and notice that we have a brand-new live stream. That one is the one we just created with recording. We’re not going to actually take the time to send anything to this particular transcoder; I’ve done that previously, so we have some recordings saved, and we’re just going to look and see how you can get those and understand what’s going on with the API.
The next thing we’re going to do — and again, I’m not going to start the transcoder this time because we know it exists — but what I am going to do is look and see what recordings I may have. And in this case, I’m getting all of the recordings in my account.
What you’re going to do here is get a list back. In this case, I think I only have two. There are a couple recordings here. It’s going to tell you their original transcoder these recordings were from (and they could be multiple recordings from the same transcoder, or it could be a single recording from many transcoders), but you can differentiate that again by the somewhat all-powerful transcoder ID we’ve talked about before.
You get the state, denoting whether the recording is completed, and you’ll get the name along with other information like the start date, the created date, things like that. If you go into User Interface and you click on the Recordings tab, you’ll see the same thing. So, you’ll see that we have a couple recordings saved over here.
As far as VOD streams go, it’s very similar. You can get the list of VOD streams for a particular account. In this case, I have two as well. They were created on different transcoders, so you’ll see different sessions. And again, if you go over here and you look at VOD streams, you’re going to see the same things over here. You can also get the VOD streams for just a particular transcoder. In this case, we’re going to call this and find there aren’t any. We created a transcoder but we didn’t start it or create any assets, which is why there aren’t any there.
Recorder ID vs. Transcoder ID
Rose Power: There a couple questions for you that I see come up in the community forums a lot. The very first step there, when you clicked on Create a Live Stream with the recording and got a response, does that have the recorder ID and how do I differentiate that from the transcoder ID?
Barry Owen: It does not because the recording hasn’t been created yet.
Rose Power: That makes sense.
Barry Owen: The recordings get created when you stop the transcoder.
Rose Power: I see.
Barry Owen: When we start talking about custom stream targets, we’ll talk about some ways how you can use a custom stream target to effectively create clips so that you don’t have an entire recording, but you can create sections.
Rose Power: Okay. So that ID that I’m seeing, that’s the transcoder ID, just so people are clear on that?
Barry Owen: Yes, this ID here is your transcoder ID.
Rose Power: OK.
Barry Owen: All right. So very quick, very simple, right? So you create your stream. You run, you get your results. In a future session we’ll talk a little bit about one of the new features of Wowza Video, which is the ability to manage these assets within the UI. That’s a tease for the future.
Custom Stream Targets
Barry Owen: Next up: custom stream targets. What might you use a custom stream target for? When you start a live stream in Wowza Video, you obviously get a playback URL that’s delivered to you via CDN. You might also want to send that stream to a social media platform or somewhere else. Maybe you want to send it to an internal endpoint for some reason. Maybe you’re recording it yourself somehow. There are many reasons you might want to have a custom target to various different locations.
One of the other interesting use cases for a custom stream target is you can create a one that can create VOD streams. Effectively by enabling and disabling the target, you can then create little hunks of VOD streams that don’t necessarily have to be the full duration of the live stream. In order to demonstrate that, I’m going to create a new one over here just for fun, and I am going to start it this time. As you can tell, I’m breaking my own rule — I just created three live streams with the exact same name. Don’t do that normally! So, we’re just going to send a start command, and now we’re in a good state.
The reason I wanted this started is because once you attach a stream target to a transcoder, you can’t enable or disable it unless the transcoder’s running. That’s important to note and is easy enough. In this case, what this stream target is set up to do is effectively go to an alternate CDN. In this case, I’m sending another stream out to Akamai in particular, which is one of the CDNs available in Wowza Video.
We’re going to go ahead and create that live stream. And, again, the ID is the most important thing you’re going to get back here because you’ll need to use that in the future for other calls. What you then need to do is attach this stream target to a specific transcoder output. An output of a transcoder is effectively a bit radar rendition. What I’m going to do here is actually call the transcoder and have it tell me what the outputs are. So, you’re going to make this call and you’re going to get back a list of outputs.
And you’ll see that this one is 720p. You’ll see that this one is your pass-through. You get back a whole bunch of different ones (n this case I think there’s five or six). I’m just going to grab the first one. So this ID here, and I’m going to attach my target to that output. Again, that’s reflected in this variable. So I didn’t, I’m not actually copying and pasting. Now what you’ll see is we’ve created an output stream target. We have our custom target associated with our transcoder. Now, when we actually do send a stream, the transcoder itself is going to send outputs not only to the standard playback URLs that would go to the hosted page and the HLS URLC, but it’s also going to send a stream to that secondary stream target. It’s viewable on the playback URL you sent in when you created that target.
Understanding Outputs and Disabling a Stream Target
Rose Power: Barry, when you say outputs, just so I’m clear that I understand, are you talking about different versions of the stream…?
Barry Owen: A transcoder will have multiple outputs. We can actually go look at one: what we’re going to go see here is if you look at your transcoder… Actually, I’m going to cheat and go over here in Transcoders. What you’ll see here is it has a bunch of different outputs, and those are the outputs that we returned in that list we just saw. You can attach a custom stream target to any one of them. In this case, we attached it to this one and you’ll see it reflected here (second output target).
And this custom stream target can, like I said, go out to a social media platform, it can go to an alternate CDN, or it can be just a simple target that does nothing but record. That’s what you would typically use for creating a clip. The way we would do that is in this case, we have our transcoder that’s running. We’re not sending a stream to it, but if we were, when we first created that target and started the transcoder, that target is enabled by default.
If we want to disable that target, it’s pretty simple. We come over and we disable the target. It returns a state that is disabled. So now this particular target, in our example case, is no longer sending data to Akamai. If this was a recording stream target, we’d no longer be recording. That would be a little clip there, and if we wanted to re-enable it, it’s simple. Really interesting use cases. It really makes the Wowza Video platform able to do a bunch of different stuff. And I know we’re kind of running through these fast here, but I would encourage you to grab the Postman config and just play around with it. The API docs will give you a good idea of the various options for stream targets you can create.
Rose Power: I think one of the great uses for those little video clips that you can create is you can repurpose your original stream. You can show little clips of it on social media sites, and it can continue to draw people to your product or your website. Video clips come in handy even after your original event is over.
Barry Owen: For sure. And then, simply now it’s really just tearing stuff down. If for whatever reason you no longer want this stream target associated with the transcoder, it’s easy enough to do, you just remove it. And what you’ll see over here is if I refresh my page again, it’s no longer associated with this transcoder. If you want to clean up after yourself and you don’t need to reuse this stream target anymore — if this was a one-time thing — of course you can simply just delete the target, then it’s gone. And in this case, we’ll go ahead and stop our stream.
And that’s it. So again, what we covered today was how to create a live stream that records either or both MP4s or VOD streams, how you can then get the lists and the state of those recordings and VOD streams, and then a quick overview on some of the uses for custom stream targets and how you add custom stream targets to transcoders via the API.
Finding a Specific Recording
Rose Power: One of the most common questions I get on recordings with the API in the community forums at Wowza is, “If I have multiple recordings, how can I quickly find the one specific recording that I need?” if they didn’t write down their recording ID in the beginning. Do you have any advice on how people can quickly find the one they’re looking for?
Barry Owen: I would use the call that actually ties to a transcoder, a specific transcoder ID (if I had it) so that I’m only going to get the recordings for that transcoder and not every recording that might be in my account. And other than that, I would probably just grab the results and start narrowing it down by either date, range, or something else.
Rose Power: That’s helpful advice. Thank you.
Barry Owen: Right. Well, that’s it for this session. Again, we will be posting the Postman config for you to use, play with. And look forward to seeing you back at the next session. Any other questions, please see us at wowza.com.
Rose Power: Thanks, Barry.