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 2018.11.04, Free version
INFO server comment - License number: 1
INFO server comment - No time limit
INFO server comment - Scissor is starting worker thread for application scissor/_definst_
INFO server comment - Default output stream name(s): [mux]
INFO server comment - Default stream name is live
INFO server comment - Scissor worker thread is running in scissor
- - - - -
INFO server comment - Setting up basic authentication on the REST API
INFO server comment - Using REST API username xxxxxx and ***** password
- - - - -
INFO server comment - Started Scissor UI on http://localhost:4567 without SSL enabled

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. You can also use the Streaming Engine Manager UI to create these.

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
scissor.playlist.notify.url (Since 2018.09.01) If set, this URL receives a HTTP POST message containing the details of the item every time there is a transition in the playlists compiled by Scissor

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

Related articles

The REST API is documented using Opan API 3.0 specs. This allows using Swagger to explore the API and documentation, as well as generating client stubs in a range of different client languages. Click here to navigate to the Swagger UI of Scissor. The UI is available with and without SSL to help testing against non-SSL Scissor setups from browser without violating the browsers SSL policies.

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.

Scissor REST API allows you to dynamically define and play out new Wowza playlists without handcrafting streamschedule.smil files. The playlists can be edited and deleted any time and you can also skip to the next item if needed. You can mix static vod files and live streams in the same playlist.

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|false
scissor.ui.port (Since 2018.01.07) The port for the UI and the REST API 4567
scissor.rest.api.authentication (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, Scissor makes 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

or

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

will be printed out in the logs on startup.

The REST API is documented using Opan API 3.0 specs. This allows using Swagger to explore the API and documentation, as well as generating client stubs in a range of different client languages.

Click here to navigate to the Swagger UI of Scissor. The UI is available with and without SSL to help testing against non-SSL Scissor setups from browser without violating the browsers SSL policies.