Clamp Reference

Installation Guide

To install Clamp module into your Wowza server, you need to copy the downloaded single clamp-yyyy.mm.dd.jar file into the lib directory of your Wowza installation.

Clamp requires on Wowza Transcoder AddOn, so you need to make sure that your Wowza license includes that. The price of the Clamp licence does not include the Transcoder AddOn license.

Once installed, Clamp is ready to be loaded into any of your Wowza applications. If you want to enable Clamp for a particular application on your server, put the below configuration under that application's conf/myapplication/Application.xml file.

<Module>
  <Name>Clamp module</Name>
  <Description>Dynamic captions on your streams</Description>
  <Class>com.streamtoolbox.Clamp</Class>
</Module>

Clamp needs Java 8. The Java version used by Wowza is logged upon startup. Clamp won't get loaded if you are using Java 6 or 7.

Check installation

When you start Wowza and your application is loaded (e.g. publisher or first player connects), you should see this in the log file:

INFO server comment - Starting application clampexample
INFO server comment - Starting Clamp 2017.07.17, license: Free version
INFO server comment - Using caption source file c:\\clamp.txt
INFO server comment - Clamp Caption Controller thread started

If you see this error message:

Module class not found or could not be loaded. Check [install-dir]/conf/live/Application.xml to be sure all Modules/Module/Class paths are correct: name:Clamp class:com.streamtoolbox.Clamp

That means that you did not copy the jar files to the right place under lib, or Wowza has no read permission on that file.

Reference of Application Properties

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

<?xml version="1.0" encoding="UTF-8"?>
<Root version="1">
 <Application>
  <Name>live</Name>
  ...
  <Properties>
 <Property>
   <Name></Name>
   <Value></Value>
 </Property>
  </Properties>
</Root>

Configuration

Property Description Default
clamp.caption.source The name of the logical caption source, which will provide the caption data. Possible values are: file (Don't put the file path here, just the word file) file
clamp.calibrate If switched on, the module will render a grid of coordinates and font size examples over the video output, below any additional caption. This can be used to test the module working and to position the overlay accurately. true
clamp.calibrate.inverse Works if calibration is on. It inverts the grid color, which is by default black, but if invertion is on, it is white. false
clamp.encode.source This switches between applying the overlays on each output separately after transcoding them or applying the overlays on the incoming source stream once and then transcoding the result into the outgoing streams. The difference is that for example if you have multiple size outputs, the relative size of a caption will be different on each stream if you go with the default false setting. false
clamp.loop.sleep.millis The sleep time of the thread that is responsible for managing waiting and active instructions. This determines the minimum resolution of start and end times, so if you want more precise timing (e.g. animation), lower this value to around 20 100
clamp.image.cache (Since 2017.02.19) The directory on the file system that is used for storing images that are downloaded when instructions refer to HTTP urls. The default java.io.tempdir VM property that is in turn defaults to the OS tempdir

File Caption Source Configuration

Property Description Default
clamp.caption.source.file This property should be the name of the file that is expected to contain caption instructions.
clamp.caption.source.file.encoding (Since 2017.07.17) The caption source file is by default assumed to be the Wowza JVM's default charset that is either specified by the -Dfile.encoding startup switch, or is taken from the operating system. It is utf8 by default on Unix based systems. This switch allows you to override that E.g. utf8, utf16, cp1252
clamp.caption.source.file.watch.period By default the file is watched using an OS level file monitoring hook. In some cases, like if the file is on NFS, this hook does not work. In this case you can set this property above zero, which will enable a periodic file re-read every N milliseconds. If set to 0, then Clamp will use the OS hook only. 0

File caption source is the simplest way to feed caption instructions to Clamp. All you need to do is creating a text file and put one caption instruction per line. The file should be readable by the Wowza server.

An example caption file is as follows (the structure itself is described in section Caption Instruction):

# This is a comment.
# Empty lines are simply ignored. This should be two lines below.
{start: "2015.03.03 15:15:30.000", duration: 10, text: "Hello Clamp", position: {x: 10, y: 50}, style: {font:"Broadway",size:40,style:"bolditalic",color: "green"}}
{start: "2015.01.03 15:15:45.000", duration: 60, text: "Can you see this?", position: {x: 10, y: 50}, style:{font:"Broadway",size:40,style:"bolditalic",color: "green"}}

The file is parsed upon Clamp startup and an OS level watch is registered, so whenever you edit the file, it is reprocessed immediately. Modified and new instructions are pushed into the caption queue sorted by ther start times. Instructions that already have been enqueued are not taken out of the queue.

The file is assumed to be encoded using the default file encoding of the JVM which runs Wowza. That means it is assumed to be UTF-8 on Linux machines and ISO-8859 on Windows machines. This can be changed by using -Dfile.encoding property of the JVM.

Lines starting with # are ignored, just as empty lines. Each line needs to contain exactly one caption instruction in JSON format or in direct format. The lines should not contain line breaks, even if your browser puts line breaks in the example above.

Direct format means that you can put captions directly into the file, without any JSON. In this case the caption will be shown with default formatting in the default position, which is white text in the upper left corner. This is useful for testing / demonstration purposes.

Caption Instruction

Clamp works off a queue of so called caption instructions. Each instruction is a structure of the following attributes:

Property Description Default
text The displayed text itself. Either this, the clock or the image attribute must be set. E.g. Hello Clamp
clock If specified, the caption will display a clock instead of static text or image. The value has to be the pattern, using the pattern specification of the Java SimpleDateFormat class E.g. yyyy.MM.dd HH:mm:ss
countDown If specified, the caption becomes a counter going down from this number one by one down to zero
start The start time when the caption instruction needs to become active. The expected format is: yyyy.MM.dd HH:mm:ss.SSS or yyyy.MM.dd HH:mm:ss or now+10. Either this or relativeStartTime has to be present. E.g. 2014.11.05 22:58:59.002
end The endtime when the caption instruction needs to go away. The expected format is: yyyy.MM.dd HH:mm:ss.SSS. Optional, you can use duration instead. If neither end nor duration is specified, a default duration of 15s is assumed. E.g. 2014.11.05 22:59:59.002
duration The duration in seconds for which the instruction needs to be active. 15
position The position is a structure itself, containing two mandatory properties, x and y, which are the horizontal and vertical coordinates of the caption measured from the top left corner of the video. Optional, by default it is 5,5. Sizes less than 1.0 are interpreted as percentages of the width and height, so positioning to the center vertically can be achieved by setting y to 0.5. It can also contain an optional anchor attribute, which can specify which corner is being positioned. Possible anchor values are: top-left, top-right, top-center, bottom-left, bottom-right, bottom-center, center-center. The default anchor is top-left. Position can contain an optional z parameter which is the z-index. This determines the rendering order of overlays. {x: 5, y: 5, z: 1, anchor: "center-center"}
style The styling of the caption is a structure itself, the attributes are described in the below table Default is SansSerif font, white color, bold, 12px size. Example: {font:"Broadway",size:40,style:"bolditalic",color: "green"}
opacity The opacity of the text or image. 0 means invisible, 100 means opaque. Integer value. 100
image The image to be displayed. Either this or the text, the clock attribute must be set. Supported image formats are: jpg,bmp,png,gif. Animated gif files are also supported, in which case the animation is repeated in an endless loop.
relativeStartTime The start time of the instruction after the point in time defined by the relativeTo specification. Either this or start has to be present. Starting from version 2017.02.19 Clamp supports URLs when specifying an image overlay, e.g. image: "http://mywebsite.com/image.png". Base64 encoded images are also supported, e.g. image: "data:image/png;base64,iVBORw0KGgoA...."
relativeTo This can be used to specify the point in the playlist to which the start time is interpreted or alernatively to show the instruction only on the specified stream. Example: {scheduleStream: "stream01", schedulePlaylistItem: "streetview.mp4"}
transitionIn The transition specification for showing the instruction. Current transitions are: fade,scroll,ticker
transitionOut The transition specification for hiding the instruction. Current transitions are: fade,scroll

Caption Style Attributes

Property Description Default
font The system name of the font, or the family of the font Default: SansSerif, examples: Serif,Verdana,Helvetica
size The size of the font in points 12
style The font variant, e.g. plain,bold,italic,bolditalic bold
color The color of the font. You can use all the standard CSS color names (e.g. red, lightgreen), or specify the RGB values using the #RRGGBB hexadecimal notation. white

Caption instructions need can be specified in JSON format in case of file based caption source.

Caption Shadow Attributes

Since 2017.02.19 Clamp supports adding shadow effect to overlays. Both text and image instructions can have shadow rendered:

{start: "now", duration: 15, text: "Text with shadow", position: {x: 50, y: 50}, style: {font:"Verdana",size:50,style:"bold",color: "yellow"}, shadow: { offsetX: 10, offsetY: 5, opacity: 0.4, radius: 9}}
Property Description Default
offsetX The horizontal offset of the shadow 2
offsetY The vertical offset of the shadow 2
opacity The opacity of the shadow 0.8
radius The radius of the shadow 3

Transition Specification

Property Description Default
type Values: fade,scroll,ticker
duration The duration of the transition. This is substracted from the total duration of the instruction, so to show a text for 3 seconds, with 1-1 seconds of fade in and out, you need to specify 5 second duration on the top level 0.0
speed The speed of the transition, which only applies if the type is ticker. In that case you can choose between specifying duration or speed.
delay In case of the ticker effect, this specifies the duration in seconds that is inserted before the text scrolls in again from the right side

Ticker Effect Example

Ticker effect is that the specified text is scrolled continuously in a loop from the right to the left for 60 secs 10 secs after it is picked up by Clamp. When the full text goes out on the left, it starts again from the right. This goes until the specified duration passes, then the ticker disappears. The x position does not matter in this case, the y value sets the vertical position. By using values less than 1, you can specify it by percentage.

{start: "now+10", duration: 60, text: "This is really breaking news here", position: {x: 0.5, y: 0.3}, style: {font:"Verdana",size:60,style:"bold",color: "green"}, transitionIn: {type:"ticker", speed: 5, delay: 2}}

The text speed can be controlled by the speed attribute of the transitionIn. You can also specify duration alternatively, in that case the speed is calculated so that the text passes by exactly in the specified duration. Be careful, there is a top level duration as well, which specified the duration of the whole ticker itself! You can insert pause between two tickers by using the delay parameter.

Scroll Effect Example

The below example means: 10 seconds after saving the instruction file, the Hello World! comes in from the right, it will take 3 seconds for it to go to the center of the sceen horizontally (x=0.5). Then it will stay there for 4 seconds (= total duration - transition in - transition out) and go out in 3 seconds to the left.

{start: "now+10", duration: 10, text: "Hello World!", position: {x: 0.5, y: 0.3, anchor: "center-center"}, style: {font:"Verdana",size:60,style:"bold",color: "blue"}, transitionIn: {type:"scroll", duration: 3}, transitionOut: {type:"scroll", duration: 3}}

A message that is only visible only on the "football0" stream but not on the "basketball0" stream:

{ start: "now+1", 
 text:"This is only for football fans and not basketball fans",  
 style: {"font":"SansSerif","color":"red","style":"bold","size":34},
 position: {"x":0.5,"y":0.5,"z":0,"anchor":"center-center"}, duration:20,
 relativeTo: { scheduleStream: "football0"}
}

REST API

Starting from version 2016.10.20 Clamp comes with a fully functional REST API that allows easier integration with external services. To enable the REST API, you need to set clamp.ui.enabled to true and set clamp.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 Clamp listens to requests with the clamp.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.

Property Description Default
clamp.ui.enabled Set to true to enable REST API and UI false
clamp.ui.port The port for the UI and the REST API 4567
clamp.rest.api.authentication Set to false if you want to talk to the API true

The REST endpoints are as follows:

POST /clamp/instructions

{"start": "now+50", text:"Hello There",
   "style": {"font":"SansSerif","color":"#000000","style":"bold","size": 24 },
   "position": {"x":0.5,"y":0.5,"z":0,"anchor":"top-left"}, "duration": 120.0 } 

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

GET /clamp/instructions/active

Returns the list of all active, ie. on-screen instructions

GET /clamp/instructions/waiting

Returns the list of all waiting, ie. not on screen yet instructions

GET /clamp/instructions/12345

Get a concrete instruction by id

DELETE /clamp/instructions

Remove all instructions immediately

DELETE /clamp/instructions/12345

Delete a concrete instruction by id

GET /clamp/whoami

Returns the name of the currently logged in user.

POST /clamp/instructions/12345

Changes an already exising instruction with a known identifier overwriting it's attributes. This can be used for editing an instruction without annoying flickering.

POST /clamp/instructions/batch

This call can be used to add multiple instructions, delete multiple instructions and edit multiple existing instrutions in one single atomic operation.

{
 10: {"text": "Edit an existing instruction with known id 10. If not found, then it is created, so just use ID = 1, 2, 3.. to add new ones "},
 20: null /*This is to remove instruction ID 20 */
}

Examples