2. Encoders Setup

Encoders.xml

Each encoder to be recognised by your system should have an entry in encoders.xml file. You specify the name, version, unique guid and most importantly a set of encoding parameters that will be used to encode your videos. If at any time this file changes during queue processing, the queue will use parameters loaded at the start of queue service and restart will be required. There are three types: video encoders,image resizers and thumbnail creators identified by tags <encoder>, <image> and <thumbs>.

Common attributes of video encoders and thumbnail creators:

 guid - identifier of this encoder
 type - currently only "ffmpeg_0612" is supported for video and thumbnails, "PIL" for image
 width
 height - size of destination video or picture
 outputType - output format. For video encoders it can be avi,mp4,flv, etc. , for thumbnail creators it should be 'png' or 'jpg'
 extraparams - set of additional parameters that will be passed to encoding tool

Video encoder attributes:

 vcodec - video codec - for example "libx264", "flv" or "wmv2"
 acodec - audio codec - for example "aac"
 bitrate - bitrate of destination video. Should also specify unit. For example "2000k"
 audiobitrate - bitrate of destination audio track
 fps - framerate of destination video
 watermarkFile - image file to use as watermark. The file should be uploaded to 'etc' subdirectory
 watermarkStore, watermarkAssetItem, watermarkAssetItemType - asset to use as watermark source. It can be used instead of watermarkFile
 watermarkStart - when (in seconds) watermark should start. Usable only with multi-frame watermarks
 watermarkX
 watermarkY - where the watermark should be placed on output video

Thumbnail creator attributes:

 thCount - how many thumbnails should be created. Interval between thumbnails will be calculated from length of input video and number of thumbnails
 thInterval - new thumbnail will be created every x seconds. This option should not be used together with thCount
 borderWidth - width of the border to be drawn on thumbnail. Use 0 to disable
 borderColor
 borderRadius - radius of rounded corners. Set to 0 to disable
 backgroundColor - used only in case of rounded  borders
 square - if set to "1" thumbnail will be cropped to square

Image resizer attributes:

 watermarkFile - image file to use as watermark. The file should be uploaded to 'etc' subdirectory
 watermarkStore, watermarkAssetItem, watermarkAssetItemType - asset to use as watermark source. It can be used instead of watermarkFile
 watermarkX
 watermarkY - where the watermark should be placed on output video. Can be specified in px or %. If unit is not specified then px is assumed.
 watermarkAnchor - which point of watermark is used as anchor. This parameter is two characters long, each character can be 0,1 or 2. 0 means top or left, 1 means center, 2 is right or bottom. For example "02" means left bottom corner.
 borderWidth - width of the border to be drawn on thumbnail. Use 0 to disable
 borderColor
 borderRadius - radius of rounded corners. Set to 0 to disable
 backgroundColor - used only in case of rounded  borders
 square - if set to "1" thumbnail will be cropped to square
 quality - compression quality in 0-100 range

<?xml version="1.0" ?>
<encoders>
        <encoder acodec="libmp3lame" audiobitrate="64000" bitrate="800000" extraparams="" fps="25" guid="mp4encoder" height="600" outputType="flv" type="ffmpeg_0612" vcodec="flv" version="2.15" width="800" watermarkFile="watermark.1.png" watermarkX="30" watermarkY="30"/>
        <encoder  guid="thencoder" height="200" width="800" outputType="jpg" type="ffmpeg_0612"  version="2.15" thCount="6"/>
        <encoder guid="C53F833BB2D6416380C1ABF051D43ED6" params="-vcodec copy -vbsf h264_mp4toannexb -an" type="ffmpeg_0612" version="2.16"/>
        <thumbs type="ffmpeg_0612" version="2.15" width="200" height="150" guid="th1" outputType="png" thCount="2" borderWidth="2" borderRadius="15" />
        <image type="PIL" version="2.15" width="800" height="700" guid="img2" outputType="png" thCount="2" borderWidth="2" borderRadius="15" backgroundColor="red" square="1" quality="20" watermarkFile="watermark.1.png" borderColor="blue" />

</encoders>

Privacy/Scope: encoders.xml live in your own private network only. Settings are not automatically shared between users. We preload few basics to get you started.

Encoder Watermarks

Watermark can be single image file that is applied for whole duration of the video or it can be animation consisting of many frames. In first case it can be provided using watermarkFile or watermarkSource/AssetItem/AssetItemType attributes. Animated watermark can be only provided as multiframe asset. This kind of asset contains number of ordered frames, each one png or jpg image named <assetuid>;_<frame number>.<extension> . Frame numbers start with 00000 and are always 5 digits long. First frame will be used for time since video start to watermarkStart, last frame will be used after animation finishes until end of the video. This can be used to show static watermark before or after animation.

AssetItemType should be specified as "multi:<ext>:<framerate>" for example "multi:png:10". There is one restriction on framerate (maybe it will be removed later) - any value higher than framerate of source video will be silently reduced making animation slower than intended.

Remember: Watermark is set on encoder not on each asset. Once you define an encoder you only have to specify its GUID when processing files. This is very useful.

Encoder Management

Encoder list can be queried and modified using encoders.py. List of commands:

 types - returns list of installed encoder types (plugins). When creating new encoder it is required to use one of types returned by this call. 

Example return:

<?xml version="1.0" ?>
<EncoderTypes>
     <tencoderType name="ffmpeg_0612"/>
</EncoderTypes>

 list - returns contents of Encoders.xml file (see above for format)
 remove <guid> - removes one of defined encoders
 create - adds new encoders to the list. Its definition is provided as XML on standard input. If guid is not provided, random one will be generated.

This commands returns guid of new encoder.