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
<Module>
  <Name>Scissor module</Name>
  <Description>A module for dynamically switching between vod and live stream sources for e.g. ad insertion</Description>
  <Class>com.streamtoolbox.Scissor</Class>
</Module>

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
scissor.default.stream The name of the default/fallback input stream where Scissor can switch back automatically after playing a VOD block live
scissor.default.output.stream 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
scissor.default.stream.startup A boolean true/false value that controls if Scissor should switch to the specified scissor.default.stream on all the output streams true
scissor.default.stream.startup.delay 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
scissor.control.file.watch.period 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
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 scissor.default.output.stream 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 scissor.output.stream 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.