Documentation version 0.4

Documentation for version 0.3 may be found here.



ffencoderd is a daemon that wraps the usage of ffmpeg providing a simple SOAP API to control video encoding jobs. ffencoderd is focused on any video conversion to flash video format although any format accepted by ffmpeg can be used. ffencoderd is divided into two main parts an http server which provides methods to add/retrieve files and request the SOAP api. And a second part the encoder daemon which converts the video. Each part is runned in background as a daemon process.



Install should be quite straight forward, just by unpackaging and executing the main program file ffencoderd should run. Just be sure to meet all REQUIREMENTS found below. There are some scripts in the doc folder of the package which should help in the deployment.

Download latest version,

mv ffencoderd-varsion.tar.gz /path/to/install/;cd /path/to/install/

tar -xzvf ffencoderd-version.tar.gz or unzip

Edit ffencoderd.conf to meet your system or alternatively create a new config file with needed parameters and pass it with '-c' argument to ffencoderd

Set permissions to defined paths/files in the config file (output.file,video.input.dir,process.dir,video.output.dir,thumbnail.output.dir, log.dir, pid.dir) set to any you want as long as the user executing ffencoderd has read/write privileges.

chmod 644 /path/to/output/dir /video/input/dir /process/dir /video/output/dir /thumbnail/output/dir /log/dir /pid/dir

ffencoderd runs under the same user and group that executed it. So beware to not run it with root.

/path/to/install/ -c /path/to/config/file.conf

Or run the main program file, it will look for a config file name ffencoderd.conf in the same folder.


Just type '-h' to get possible arguments that can be setted. Optionally you can use the init script provided in the doc folder, before you'll need to setup the FFENCODERD and PIDFILE environment variables or put ffencoderd in the default paths that the scripts looks for. Be carfeul PIDFILE must point to the location of the pidfile which is setted in the conf file.

For more information about the configuraion file see the Configuration File section.

Once installed and running ( if http config parameter is set to true ) should be possible to access a main page at the address and port defined in the config file, with your web browser. Example http://localhost:8080/ This will show the main page letting you know ffencoderd is succesfully running and gives you some information about it. See the HTTP Server section.

Otherwise if you don't want to run ffencoderd HTTP server just set the http config parameter to false, then you may just save your processes in XML in the process.dir directory defined through the config file. This XML processes definition must validate against the DTD definition of ffencoderd. The DTD schema may be found in the ./doc directory or in the main site.

A typical XML process will look like

<ffencoderd> <process id="0"> <file>filename</file> <profile>SomeExistentProfile</profile>
<parameter name="someName">someValue</parameter>
<parameter name="someName2">someValue2</parameter>
</process> </ffencoderd>

Just create a file and save it in the process.dir, call it somthing.xml. ffencoderd will parse the file and convert filename with default ffmpeg parameters saving the converted file in the video.output.dir directory. ffencoderd SOAP service gots methods to create this files programatically through SOAP, refer to SOAP section.

Environment variables

Thesea are the environment variables used by the init script provided in the ./doc folder.


The location of the main file program


The location of the pidfile created by the ffencoderd daemon, this must be the same as defined in the config file.


This variable is optional, you may set any arguments you wish to pass to the start program at init. See Command Line Arguments section for more detail.

Supported OS

Currently only *UNIX like systems are supported. ffencoderd was developed using an Fedora Core 6 kernel 2.6.18-1.2798.fc6 and perl, v5.8.8 built for i386-linux-thread-multi. Please report on succesful builds on other systems.




Tested with FFmpeg version SVN-r8876, Copyright (c) 2000-2007 Fabrice Bellard, et al.


Tested with perl, v5.8.8 built for i386-linux-thread-multi.


ffencoderd depends on a few cpan perl libraries and ffmpeg. Please refer to ffmpeg official site for howto install ffmpeg in your system.

SOAP::Lite (Soap::Transport::HTTP)

These are libraries that can all be found at CPAN, so just install them the way you want. Here is an example of how to install them

cpan IPC::ShareLite Config::General SOAP::Lite XML::DOM XML::Simple Pod::WSDL Pod::Xhtml HTML::Template

Beware that you may need root privileges to install them this way. Look at cpan site to install them locally without need to have superprivileges.

Configuration File


The default configuration filename is ffencoderd.conf which should be located at the same folder of the main program file. This is just a plain text field with some key value pairs to define config values. Any changes in the file will need ffencoderd restart. Next is some explanation about.


Start an http server with different services, otherwise only encoding daemon will be started. Possible values are true or false


The host address for the http server, this is an IP or hostname that should resolve to the machine in which ffencoderd is running.


The port which the http should listen to for incoming connections. This is any port you like, even though normally we will use an http standard port such as 80 if no other web server are running on the same machine. If not take any port you like.


The number of children the http server should create at start to listen for incoming connections, this number should depend on your system. Don't put a too high number here as it could collapse your system. Example : 10


This is the number of requests each child will attend before dying and respawning. Leave it in a high number as 100 or modify if you know what you are doing.


The location of ffmpeg in your filesystem. Example : /usr/bin/ffmpeg


This is the file where ffencoderd puts the information about the encoded files, in xml format. It must be a full path with filename, you may put it wherever you want as long as the the ffencoderd has write/read access.


This is the path to the folder where ffencoderd looks for new file processes, is just a writable folder where ffencoderd will look and/or put some xml files to configure video conversion processes. ffencoderd will scan this directory every delay seconds for *.xml process definitions, these are XML files that validate the DTD schema given with ffencoderd and that you may found at ffencoderd main's site. If the http server is not activated or if you prefer to interact directly with the daemon you may save any xml file with process definitions in this directory. The daemon will parse and delete them after finishing defined processes.


This is the path to a writeable folder where ffencoderd will output converted videos.


This is the path to a writeable folder where ffencoderd will look for videos to encode.

Set this option to show recent news from the project in the main page of the server, possible values are true or false. The news are fetched from .


This parameter defines if internal log messages should be logged, possible values are true or false.


This is the filename for the log file. Example ffencoderd.log


This is the path to a writeable folder where the logs will be putted in. Example /path/to/install/logs


This is the path to a writeable folder where the pidfile will be saved to. Example /var/run/ Remark that last slash is needed.


This is the url of the DTD file that will be added to all output.file control files created by ffencoderd. Normally this shouldn't be needed to be modified. There's always an updated DTD version at ffencoderd site

Some more explanations may be found in the example config file found in the doc folder.

Profiles file


The profiles are the way to set up how the ffmpeg command will be made up, these are defined in a file found in the data directory named profiles.xml. A profile definition has the following elements


The profile's name, used to reference it.


The extension used by this profile as is produced by the conersion command.


The mount point where the resources converted with this profile will be accessible.


Media type to be used in this mount point.

There are also some elements that define the parameters that can be defined through the SOAP API, these parameters are divided into two types, the parameters that define the resource to be converted and the parameters that define the converted resource, infile and outfile parameters. Each can have multiple parameter definition and both types are optional, although only infile can really be optional as if there aren't any outfile parameters defined the conversion command won't do anything at all. The parameters are defined with next elements :


The argument used for the ffmpeg command, ex: -f


The name for this parameter, this will be the name to use to define it through the SOAP api, this name has to be unique over infile and outfile parameters.


The default value for this parameter, this element is optional, if it isn't defined the parameter will only be defined if the user defines it through the SOAP API.

To see some examples, see the profiles file in the data directory.

Command Line Arguments


There are several arguments that may be defined when calling ffencoderd. These are


Shows a help message with all the possible arguments.


Shows version number and copyright information.

-c <configfile>

Sets the config file to be used. Use an absolute path to config file. Example /path/to/config/file.conf

-d <delay>

Sets the delay in seconds to scan for processes. Example 40

-m <xmlfile>

Sets the path where the output file will be putted in. Example /path/to/output/file.xml

-p <dirname>

Sets the path where to look for processes definitions. Example /path/to/processes/dir

-l <logfile>

Sets the path to the file where to write log messages. Example /path/to/log/file.log

--ffmpeg-output|-fo <ffmpegoutputfile>

Sets the path to the file where to write ffmpeg encoding output, mainly for debugging purposes. Example /path/to/file.log

HTTP Server


The HTTP Server of ffencoderd has some paths that may be accesed to interact with ffencoderd, next are the explanations for all of them.

Root path /

This path will serve the main information screen of ffencoderd with some information about the program. You got this documentation, a SOAP API reference and a monitor to surveil the ffencoderd server.

Soap proxy /soap

This path is the SOAP proxy access. Is where clients should point to if not using the WSDL functionality.

Static path /static/

This is the path where static files are served from, it won't output a file index it will only serve existing files from within the ./data/www folder inside the installed path.

Files path /<source>/*

Any encoded resource is referenced through the source parameter returned by the getProcess method from the SOAP API. To see accessible paths see the profiles section and the profiles files to see which mount points are setted in your server.

Upload path /upload

This path has a double function, it will output an html form example if accessed via GET method and will save to the video.input.dir parameter folder any multipart file posted to this path via POST method. After posting a file the server will output an xml with the filename used to save the file, be careful it's not always the same filename with which you posted yours a random one may be generated if there's already a file with the same name, the extension will be always preserved. And the size of the saved file in bytes.

Stats xml file /stats.xml

This file is generated each time this is called it outputs an xml file with some statistics of the server. It's mainly used for the monitor in the main information screen found at /.

News xml file /news.xml

This file is the news file used to show news on the main page, if you don't want to show news on the main page just use the parameter on the config file.

Processes xml file /processes.xml

This is the same file that output.file from config, this access is for easiness and for monitoring purposes.



The soap proxy may be accessed through the /soap as specified before, even though it can be really accessed via any path that is not resolvable to any of listed above.

An WSDL file definition is accesible through any uri at the server just appending ?wsdl, so /soap?wsdl will return the spec file.

ffencoderd SOAP functionality is based on SOAP-Lite so please refer to the module documentation for further information on how the SOAP part works.

You may post any request to the SOAP server conforming the SOAP 1.1 specification.

See the API documentation for more information about accesible methods on the server.


Constants that are returned by the SOAP API


Context : ffencoderd service status functions

value : 100


Context : ffencoderd service status functions

value : 101


Context : ffencoderd encoding processes functions

value : 200


Context : ffencoderd encoding processes functions

value : 201


Context : ffencoderd encoding processes functions

value : 202


Context : ffencoderd encoding processes functions

value : 203

The method returns the status of the ffencoderd process. It returns an integer value corresponding to an ffencoderd SOAP API constant



integer : Constant with the status of the server FFENCODERD_OK|FFENCODERD_FAIL. If FFENCODERD_FAIL there is some problem with the server

The method returns an xml with some metadata about the process which has been codified



processId : Identifier for the process, this corresponds to the process identifier returned in getList()


string : An xml string with some information about the process, mainly its characteristics or FFENCODERD_FAIL if didn't find it

Returns an xml formatted response with a list with uid of ended encoding processes



string : An xml string with a list of processes listed by uid

Add a resource to encode



process : The process definition as a complex SOAP structure


string : Returns a string with a constant indicating if the creation of the process was succesful

Returns the API version



string : A string with the API's version


Next is an example of using SOAP-Lite as client to request version number to ffencoderd running in localhost.

	use SOAP::Lite;
	my $soap = SOAP::Lite
	my $invoca = $soap->version();
	my $version = $invoca->result();
	print "ffencoderd v$version";

Or the same in PHP would be something like this.

		$client = new SoapClient("http://localhost:8080/soap?wsdl",array('uri'=>'Service'));
		echo "ffencoderd v".$client->version()."";

See also


See the developers documentation





The latest version of this program should be accessible through the main ffencoderd site