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
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 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.

REST API

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 and set scissor.rest.api.authentication to false in order to allow external access to the API without valid session cookie that you can obtain by logging in via the UI. (The UI is not released to public yet, so basically you can't login now.)

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 the endpoints don't have authentication yet so you need to make sure that they are only accessible from your intranet and not public. This will be addressed in upcoming releases.

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.

Send a new instruction to Clamp. The response is an integer number that identifies the instruction.