Step-by-step Scissor Setup Guide

This article covers the steps you need to make in order to install Scissor on your Wowza Streaming EngineĀ®. Although this is not as simple as running an installer and pressing Next, Next, Finish on a wizard screen, it is not rocket science. Once installed, Scissor will allow you to set up one or multiple live streams in your application and switch between live and vod contents by a predefined schedule or ad-hoc. You can use this for ad insertion for example.

Prerequisites

  • Have Wowza Streaming Engine installed on your server up and runnig
  • Have access to the Engine Manager with access to advanced settings (see the attached screenshot)

Download Scissor jar file

Wrench ships as a single .jar file named as scissor-yyyy.mm.dd.jar that you can download from here and then you need to copy it into the lib directory of your Wowza installation. On Windows systems this is typically at C:\Program Files\WowzaStreamingEngine\lib and on Linux installations this is at /usr/local/WowzaStreamingEngine/lib.

You need to restart the whole Streaming Engine using the restart button on the right hand side that is visible when you choose "Server Setup" so that the new jar files are loaded.

Create your streaming application

You need to create your own streaming application using the Manager interface, create a new Live (single server or origin) application which I'll call "scissorexample".

Click on the "+ Application" button on the left menu

Give a name to your application

Switch on Scissor module

Select your brand new application and navigate to the Modules tab. (If you don't see this tab then you don't have the "access to advanced settings", so scroll back up a bit to see what is that)

Click on the Edit button and then on the "+ Add Module..." button and fill in the form with the below data

Restart the application as suggested by the popup message.

Start your application

It might sound a bit weird, but when you restart the application, technically the modules are not started until the first client connects (player or encoder). So at this point Scissori s configured and is sleeping. One of the simplest ways to trigger the application start is invoking a URL like this from your browser:

http://localhost:1935/scissorexample/boot/playlist.m3u8

You might need to edit the hostname and the port to match your system and it only works if you have HTTP streaming enabled. Otherwise you can push your stream from your encoder or use the test players to trigger the application.

Once triggered, you should see something like this in your wowzastreamingengine_access.log file. (You can inspect the log file using the Engine Manager)

INFO server comment - Starting Scissor 2016.10.05, licensed to Free version
INFO server comment - License number: 1
INFO server comment - Time limit is 1800s
INFO server comment - Scissor is starting worker thread for application scissorexample/_definst_
INFO server comment - Default output stream name(s): [mux]
INFO server comment - Default stream name is camera
INFO server comment - Reprocessing file w:\scissor\scissor.txt
INFO server comment - Started watching file w:\scissor\scissor.txt
INFO server comment - Scissor worker thread is running in scissor
INFO server comment - Scissor end time is Wed Oct 05 13:40:37 CEST 2016
INFO server comment - Adding instruction from line 2 into the queue Instruction [start=null, end=null, stream=mp4:sample.mp4, streams=null, loop=false, duration=0.0, skipSeconds=0, output=mux3, removeRequest=false]
INFO server comment - Immediately switching to mp4:sample.mp4
INFO server comment - Starting up a new output stream mux3
INFO application app-start _definst_ scissorexample/_definst_
INFO session connect-pending 127.0.0.1 -
INFO session connect 127.0.0.1 -
INFO stream create - -
INFO stream publish mux3 -
INFO server comment - Adding mp4:sample.mp4 into a playlist.
INFO server comment - Stream.switch[scissorexample/_definst_/mux]: index: 0 name:mp4:sample.mp4 start:0 length:-1

This is how you can inspect the access log on the web interface

This is what you should see if Wrench was set up correctly

Configuring Scissor

Wowza applications usually keep their config as properties within the Application.xml file that sits under the conf/[applicationName] directory in your Wowza installation. If you are familiar with editing xml files, you can edit that directly, but there is also a way to do that via the Engine Manager interface.

Navigate to the Properties tab of your scissorexample application.

Click on the "Custom" button in the Quick links section and then click on the Edit button to add a custom property to your application, and then "Add Custom Property..". Fill in the form as you see below:

An example typical property set that you might want to add is as follows. (For the list of all options please check the reference docs.

Property Value Comment
scissor.control.file w:\scissor\scissor.txt The file that controls the streams
scissor.default.stream myStream The name of the live stream where Scissor switched back after vod inserts
scissor.default.output.stream myChannel The name of the output stream which is generated by Scissor

Create the control file

Please make sure that the control file that you have specified in scissor.control.file actually exists. It can be empty in the beginning.

Restart the application

After configuring Scissor, you must restart the application so that it picks up the new settings

Try it out

After restart Scissor will create the myChannel output stream that you have specified. It will be black and empty, however by default it will make an attempt to switch to myStream if it exists. You can push your live stream now and start controlling the output by editing the control file, scissor.txt in the above example:

Scissor treats the control file as a way to communicate changes to it. Every time you edit the file and save it, Scissor gets a notification from the OS instantly and iterates over each line, skipping the

# commented out lines.

Every line should be either a comment or a valid JSON object which has a strict structure defined in the reference docs. The below is some examples to try out:

# In 5 seconds after saving the file, play the bunny video in the default output stream`myChannel`
{ start: "now+5", stream: "mp4:sample.mp4" }

Save the file and watch it happen. Next time you edit the file, make sure that this line is either commented out or removed, because otherwise this will happen again. Of course you can specify start date with exact timestamp:

# Switch to a different live stream called football at an exact date and time
{ start: "2016.10.05 23:06:10", stream: "football" }

In this case next time this instruction will be practically ignored if the time is already past.

Scissor can do much more, but the above should give you an idea how to start using it. With this control file generated upfront you can create an advertisement schedule in your live stream, you can achieve ad-hoc ad-insertion into your stream or just fill in any gaps in the event with your own animation.