Scissor Reference

Installation Guide

  • Copy the downloaded jar file under the lib directory of your Wowza installation
  • Restart Wowza Streaming Engine so that the classloader finds the jar file
  • Add the module to the Application.xml of your Wowza application. You can do this by directly editing this file or by configuring this on the Wowza Manager user interface
  • Configure Scissor with the below list of application properties either by editing the Application.xml or using the web interface
  <Name>Scissor module</Name>
  <Description>A module for dynamically switching between vod and live stream sources for e.g. ad insertion</Description>

When the application in which Scissor is configured starts up, you should see this in the logs:

INFO server comment - Starting Scissor 2016.10.05, licensed to Soundque
INFO server comment - License number: 1
INFO server comment - Time limit is ...s
INFO server comment - Scissor is starting worker thread for application scissor/_definst_
INFO server comment - Default output stream name(s): [mux1, mux2]
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 ...

Reference of Application Properties

Here you can find the reference of all the settings that you can apply to Scissor by editing your Wowza application's Application.xml file. These properties have to go into the <Properties> section of your file.

Property Description Default The name of the default/fallback input stream where Scissor can switch back automatically after playing a VOD block live The name of the default multiplexed output stream, or multiple values separated with commas, but no spaces between. Scissor will start up all these streams when the application is started. mux A boolean true/false value that controls if Scissor should switch to the specified on all the output streams true The delay in milliseconds between application startup and the initial stream switching. If the incoming live sources are not set up before this happens, you might end up getting invalid output (e.g. no video only audio) until the next switch occurs. The default 10s is should be ok. 10000
scissor.control.file The path of the file that is monitored for changes and which controls the multiplexer logic Control file is normally monitored with OS level file system notification hooks. If for some reason this would not work, e.g. the file system (NFS) would not support it, Scissor can fall back to periodic monitoring and this property sets the watch period time in seconds 0

Instruction Syntax

Scissor reads the control file every time it changes. The file is ready line-by-line and lines starting with # are ignored, assumed to be comments. In each line you can provide one instruction that is processed each time the file is changed, so you need always just put the changes in the file and remove old instructions preferably. (If their start time is in the past they'll be just ignored, but lines that refer to "now" for start time are always re-evaluated.

Property Description Examples
start The absolute timestamp of the instruction or relative reference using now+10 2016.10.02 21:10:00,now, now+10
end The absolute timestamp of the instruction end time. This is mutually exclusive with specifying duration 2016.10.02 21:10:00
duration The duration of the inserted content in seconds. Set to -1 for playing the VOD file or live stream to the end. 60
repeat When set to a positive integer value N, it makes the instruction to be repeated every N seconds.
stream The name of the video or live stream where Scissor needs to switch to. For VOD content, please use prefixes mp4: or flv:, all other strings are considered names of live streams. VOD file names are relative to the content folder specified on application level. mp4:sample.mp4,live1
streams A string array that contains the list of streams that Scissor need to iterate over when the specified start time comes. This can be used to insert a block of VOD videos one after the other in a playlist. Please don't specify both stream and streams, just one or the other. "streams":["mp4:ad1.mp4", "mp4:ad2.mp4"]
loop Boolean flag, set to true if you'd like to repeat the VOD video until a further transition occurs. false
skipSeconds The number of seconds to skip over from the beginning of the VOD content. 10
output The name of the output stream where the switch has to happen. If omitted, the will be used. output1
removeRequest This is for cancelling a previously submitted instruction. If you omit this by default and then go back and resubmit the instruction that you'd like to cancel with setting this to true, it will be removed from schedule

Example control file contents

Scissor uses JSON syntax in each line. You can comment out a line with #. All non mp4 prefixed streams are assumed to be live streams.

# Switch to sample.mp4 video in wowza content directory, skip over the first 10 seconds
{"start": "now+10", "stream": "mp4:sample.mp4", "skipSeconds" : 10}

# Switch to a block of 2 ads on both channels football
{"start": "now+1", "streams": ["mp4:ad1.mp4","mp4:ad2.mp4"], output: "football"} 

The right hand side stream name has to match the preconfigured which defaults to myStream.

Initially no input is multiplexed into the output, so you first need to edit the control file to get any output.


Scissor comes with a fully functional REST API that allows easier integration with external services. To enable the REST API, you need to set scissor.ui.enabled to true.

You can set the port on which Scissor listens to requests with the scissor.ui.port paramter. If not set, by default it is 4567.

The REST API has preconfigured CORS filter so that it will respond to CORS preflight requests (OPTIONS) and will allow access from any server. Please note that without SSL enabled in Scissor exposing the REST API to public internet is a security risk.

Property Description Default
scissor.ui.enabled (Since 2018.01.07)Set to true to enable REST API|false
scissor.ui.port (Since 2018.01.07)The port for the UI and the REST API|4567 (Since 2018.01.07)Set to false if you want to allow talking to the API without any authentication. Currently Scissor comes with an optionally configurable HTTP Basic authentication that has to be switched on.|true
scissor.ui.ssl.enabled (Since 2018.01.07) Set to true to enable SSL support in Scissor, see below the details false
scissor.ui.auth.basic (Since 2018.01.07) Enables HTTP Basic authentication on the API. Please note that this is only secure if used in conjuction with SSL. false
scissor.ui.auth.basic.user (Since 2018.01.07) This gives you the ability to define a single user that can use the UI or the REST API additionally to the normal Wowza admin users
scissor.ui.auth.basic.password (Since 2018.01.07) This gives you the ability to define a single user password that can use the UI or the REST API additionally to the normal Wowza admin users

When SSL is enabled, Scissormakes an attempt to find the keystore path and password from the VHost configuration in which the application is running. This means that if you have SSL set up in Wowza for streaming, Scissor should be able to pick up the same configuration automatically.

The logs should show clearly if SSL is used or not:

Started Scissor UI on https://localhost:4567 with SSL enabled


Started Scissor UI on http://localhost:4567 without SSL enabled

will be printed out in the logs on startup.

The REST endpoints are as follows:

POST /scissor/instructions - this accepts the very same JSON instructions that you can pass in via the file based API

GET /scissor/streams/:stream/status - returns the currently active playlist item in the specified output stream. Returns 404 if the stream does not exist and a string "no playlist item is active" if the stream exists, but there is no output switched on that

GET /scissor/streams - returns the list of currently active input streams eligible for switching on an output. The response is an array of objects with a name and thumbnailUrl attributes.

GET /scissor/streams/:stream/thumbnail - returns a png thumbnail image of the specified stream. The size can be controlled with the w and h optional query parameters.