Documentation for Helix Producer Remote Encoder Sample

Steve McMillen <stevemc@real.com>
August 7, 2003


This document describes how to configure the remote encoder sample for Helix Producer command line application.  This is a CGI-interface to Helix Producer that allows encodes to be started and stopped remotely via a web browser.  

Any web server may be used to drive the encoder but some configuration is requried.  This document specifically documents how to configure Apache web server on Linux and IIS on Windows.  Other configurations may need to be extrapolated from the information below.

This utility is also posted to the File Sharing section of the helix-producer project at: https://helix-producer.helixcommunity.org/

Background (how it works)

Helix Producer is able to accept a signal from another application running on the same machine using UNIX signal handlers or similar mechanism on Windows.  Signals are a way to send a notification to an application to perform some action without having to write to any specific API.  Helix Producer implements a Stop and cancel signal handler to stop and cancel and encode repsectively.

Signals can be easily sent from the UNIX 'kill' command or a sample executable that is available with Helix Producer called Helix Producer Signal Generator that sends a signal to Helix Producer on either Windows or Linux.  The Helix Producer Signal Generator is provided as source and compiled form (located in the 'bin' directory) for Windows and Linux with the RemoteEncoder sample.  For instructions on how to compile, see the comments in the top of the source file, signalproducer.ccp.  Linux users may need to compile due to library incompatabilities.

The Helix Producer Signal Generator is called 'signalproducer' (or signalproducer.exe on Windows) and has the following usage:

Usage: signalproducer {-p <PID> | -P <PIDFILE>} [-a <stop|cancel>] [-q]

This program can be used to send one of two command to Helix Producer:
Stop - Stop encoding normally
Cancel - Cancel encoding (stop, remove temp files, do not produce results)

In order to know what Process ID to use in the prodctrl utility, you can use the -pid option in Helix Producer.  The -pid option takes a filename as an argument.  Helix Producer will create a text file and write the process ID of the running instance of Helix producer to that file.  The file is automatically deleted when Helix Producer finishes encoding and exits.

You can use the -pid option as follows:

producjer -ac 0 -vc 0 -pid /tmp/producer.pid
(this example is for capture from audio device 0 and video device 0)

You can then send a signal to Helix Producer to stop encoding as follows:

prodctrl -P /tmp/producer.pid

(use lower case -p if you want to send the PID number instead of the file)

The Helix Producer command line application will stop normally.

The Helix Producer command line application and signalproducer utility can be run via a CGI Script.  Thus, you can build a web page that allows you to start instances of Helix Producer and send stop signals to that instance of producer using the PID file mechanism described above.  You can also identify a running producer instance by storing the PID file to a specific directory and send a stop signal to that instance using the signalproducer utility described above.   Helix Producer deletes the PID file when it exits normally.

Note: A feature request has been submitted to update the timestamp on the PID file every second to allow detection of zombie Helix Producer processes.  Such an improvement would be a great project for someone wishing to contribute to the helix-producer project in Helix Community (https://helix-producer.helixcommunity.org) and would offer even more reliable detection of running jobs for this remote encoder application.

The above describes the basis for a remote encoding utility for Helix Producer.  The information below describes specific implementation and configuration details about Helix Producer Remote Control sample application.

Helix Producer Remote Control Sample Implementation

The remote encoder sample does the following:
- Generate a list of job files stored in a directory on the web server
- Allow user to upload new job files. (It assumes these files are edited in the Helix Producer GUI or some other user interface)
- Edit uplaoded job files using HTML form (very simple editing - nothing fancy)
- Provides a link to list all jobs in the jobs directory using a CGI script.
- The user can start any of the jobs in the jobs directory by clicking on a link
  * The -pid option is used when producer instances are executed to have the PID file written to a directory called "runningjobs"
- List all the PID files located in the "runningjobs" directory. The name of the PID file is used to identify the job.
- Stop any running job by clicking on the 'stop' link for that job
  * A CGI script is executed that runs the 'signalproducer' program to stop the running producer instance.  Because Helix Producer automaticlly removes the PID file when it shuts down, the stopped instance of producer will no longer be listed in the "runningjobs" list.
- List devices installed on the server
- List audiences in the audiences directory of Helix Producer
- Access Helix Producer user and settings files documentation
- View (http) or download/upload (ftp) source and encoded files

Feel free to send a request for the code to <stevemc@real.com>

Note: Because of the design, each job file can be executed only once without causing confict in the listing of running jobs and log files for a running job.  The reason for this is that the name for hte PID file and log file used for a running instance of producer is the name of the job.   This allows users to easily identify the job they started (instead of using a PID number or something unique).  The producer instance will actually run with no problem - it will simply not be possible to stop or view log for all but the last execution of each job file.  The scripts could be modified to allow for each job to be uniquely run or to prevent executation of the same job filename twice (I think maybe I have the later in place now).

Helix Producer Remote Control Sample Configuration

To configure the remote control sample, you need to make sure your permissions are set up correctly on your web server to allow the producer and signalproducer executables to be lanuched and for the CGI scripts to write to certain directories and files.  You may also need to perform translation to various scripting environments if you wish to use CGI scripting languages other than TCL.

The instructions below are for configuring Helix Producer Remote Control sample on Linux/Apache and on Windows/IIS, both using TCL as the scripting language.

Apache & Linux:

Disclaimer:  The instructions below open certain security holes and is only recomened on closed networks where users can be trusted not to abuse the system.  While it would take a concerted effort to abuse the system, it is still feasible and should be guarded against.  If a more open system is required, modifcations to the CGI scripts might be needed to add levels of indiration to accesing the disk.  For exaple, instead of executing producer directly, maybe a text file is updated and read by cron every few seconds to initiate jobs.


1. Unpack the entire zip file package in your web root.  

2. Set up permission as follows:
   Make the 'library', 'logs' and 'running' subdirectories of the 'jobs' directory writeable by the apache process (usually nobody). This can be done with the following commands:
		cd <path to remote encoder dir>
		chmod o+w jobs/*
   Make sure the Helix Producer is executable via CGI (i.e. executable by user 'nobody')
   Make sure 'sinalproducer' is executable via CGI (i.e. executable by user 'nobody')
   Make sure all files ending with ".tcl" are executable via CGI (i.e. executable by user 'nobody')

* When configuring the CGI directory, it may be helpful to try to execute 'env.tcl' to debug problems.

3. You may need to re-compile the signalproducer executable.  This is especially true on Linux where you may not have the same libraries or version of gcc that was used to compile the utility with.

4. Edit the file 'options.cfg' in the 'scripts' dir for your system.  See comments in that file for system specific information.

5. Edit the link to toc.tcl in html/index.htm to point at the correct location
For example, src="/RemoteEncoderScripts/toc.tcl"



IIS and Windows

TBD - I have set this up before but simply have not documented the process.  The process is the same in principal to that of Apache and Linux above except that IIS is used for configuration and I forget what, if anything, needs to be done with file system permissions.