Modules structure

Alembik server is an enterprise J2EE application that is built (into EAR archive) from the following set of modules:

• alembik-api: Java interface of the server, which consists of service API, service locator framework with an EJB-based implementation and a set of utility methods,
• alembik-core: implementation of transcoding service, which includes media processor classes, User-Agent and mime-type resolution utilities along with Storage interface and implementation; additional parts are monitoring service implementation, cache and configurator module,
• alembik-server: EJB3-based services for remote and asynchronous processing as well as the clustering support (JBoss only),
• alembik-soap: JAXWS-based SOAP and HTTP service implementations, file serving engine for web rendering and administration console,
• alembik-wurfl: WURFL extension library defining the sets of capability values for video and audio codecs,
• alembik-build: main Ant build script and configuration files for assembling and deploying the server,
• alembik-client: Java client for Alembik server offering remote access with service API through EJB and SOAP (with a SOAP-based service locator implementation),
• alembik-taglib: JSP tag library with transcoding functionality,
• alembik-webapp: exemplary web application making use of the JSP tag library.

Each module is provided with its own Ant build script along with configuration files for Eclipse environment.

Application server platform

The build scripts depend on two configuration files from /alembik-build/etc directory:

• local.properties,
• %servertype%.local.properties, where the %servertype% token may be either glassfish, jboss or tomcat.

Initially both have to be created and filled according to the content of their counterparts: sample.properties and %servertype%.sample.properties respectively. The actual server type is determined at runtime by the use.server property (the example setting below selects Glassfish).

After choosing a particular application server, say Glassfish, the glassfish.local.properties file has to be filled with appropriate parameter values. In majority they constitute the set of Configurator's initial values and can be modified after deployment at the server's runtime.

First the folder paths to server libraries need to be specified (see Alembik installation chapter).

Storage

Then a disk location must be provided for the Storage component to place downloaded media sources along with all transcoded results. The Storage directory (transcoding.storage.root.dir) has to be chosen carefully, since it is directly related with a URL path to transcoded files (transcoding.storage.url.path), which is sent back to clients. At present, the root directory of Storage has to be equal to the real path, into which the appointed URL gets resolved by Alembik's web server.

Media processors

The next configuration step involves choosing the desired media processors from the 'alembik-core' module. Currently there are two options for image processing: ImageMagickMediaProcessor and GAIAMediaProcessor, while there is only one for audio and videos: FFMpegMediaProcessor. The actual selection is to be made with transcoding.%mediatype%.mediaprocessor parameters, where the %mediatype% token may be image, audio and video, while the value has be set to a full processor's Java classname.

Choosing ImageMagick and/or FFmpeg as transcoding tools for Alembik requires further customization. Then the full path command line has to be specified for each selected tool. Besides, in the case of FFmpeg, the version of the codec library and (optionally) the the path to imlib2 library are required too. See installation guidelines for in-depth details.

Definition files directory

And last but not least, there has to be determined the directory where WURFL configuration files are placed (they are used by the Alembik's default User-Agent resolver). That is also the place where one may put custom definition files, like predefined profile definitions, FFmpeg codec dictionary and supported video/audio codecs.

HTTP server parameters

In addition to the configuration steps described above there are four more parameters related to the HTTP service domain. The most important is transcoding.servlets.url, which stands for the URL of Alembik web application; the URL is used by the web rendering processor for constructing links to Alembik servlets in transcoded HTML content.

Further on there are transcoding.admin.login and transcoding.admin.password - the credentials for accessing the server's administration console.

Finally there is a set of parameters associated with error handling and status checking via HTTP protocol. Since all of them are optional, they should be specified ONLY when one wants to provide his own implementations outside Alembik environment.

Actually there are four properties to be customized in the local.properties file (if necessary):

• transcoding.webrendering.error.page - appoints a URL of the web page, to which the web rendering engine will redirect browser on a transcoding failure.
  
  By default the server's local /webrendering/error.jsp is used; a custom one may look like this one.


• transcoding.error.page - defines a URL of the web page, to which Alembik will redirect browser in case of general failure.
  
  The default error page is server's local /info/error.jsp; a custom one may look like this one.


• transcoding.status.page - defines a URL of the web page, to which Alembik will redirect browser in case of status inquiry (see /isReady servlet).
  
  The default status page is server's local /info/status.jsp with the auto-refresh feature built-in; a custom one may look like this one.


• transcoding.image.error.path- specifies a URL path, which Alembik will use for serving error images upon an image transcoding failure (via HTTP API).
  
  The JPG image URL will be put together by appending the following name pattern: error_%lang%.jpg, where %lang% stands for the request locale's language (can passed via lang parameter too). Thus for the English locale Alembik will load %url_path%/error_en.jpg image and transcode it according to a requesting device.
  
  The default error image path is set to the server's local /imgs/error directory.

Alembik passes the processing data to the custom JSP pages through a set of request parameters, whose names are defined in the Constants class.

Streaming support

Enabling streaming requires additional software installation. Once installed there ought to be transcoding.mp4box.command property set, which describes a full-path MP4Box command line. MP4Box is a utility marking media files with appropriate time signatures.

Moreover, the URL path to Darwin streaming server must be assigned to transcoding.streaming.storage.url.path parameter.

NOTE: MP4Box does not work correctly with file paths with a length over 16 characters. Hence if the value of the transcoding.storage.root.dir parameter is longer one must create a shorter soft (virtual) link replacing the real path. For example:

Next the configuration of Darwin server (defined in streamingserver.xml file) has to be adjusted to the aforementioned Alembik settings.

The path to media content (movie_folder property) has to be set accordingly to the Storage directory setting (refer to transcoding.storage.root.dir). Then a new port number (the one from the streaming URL path passed to Storage - see transcoding.streaming.storage.url.path just above) must be appended to the Darwin's port numbers list (rtsp_port list).

Server build

Having all the above parameters supplied, one can launch a complete build process using the assemble_dependencies Ant task from /alembik-build/build.xml script. If the build is successful it should produce alembik.ear or alembik.war archive inside /alembik-build/assemble folder, ready for deployment in a selected J2EE/Web application server.

The actual type of the file depends on the chosen server; in case of Glassfish and JBoss the EAR archive will be produced, while Tomcat-oriented build will yield the WAR file.

Clients assembly

Once the server archive is built and deployed, an EJB or SOAP client archive (alembik-client.jar at /alembik-client/assemble) can be built. The EJB client script (/alembik-client/build-ejb.xml) requires EJB connection parameters to be set (all are prefixed by transcoding.ejb.).

Its SOAP counterpart (/alembik-client/build-soap.xml) needs only the URL of a WSDL file, which can be specified by transcoding.soap.wsdl property. Since the WSDL file is produced automatically during Alembik start-up, the server has to be running to make possible its SOAP client library build.

Example web application

Another module that can be constructed from the sources is the exemplary web application (alembik-web.war), which one may put together with /alembik-webapp/build.xml file. In this case we have to determine, which client (EJB or SOAP) is going to be used to get connected to Alembik server; assign either ejb or soap values to use.client flag in local.properties in order to choose a desired communication option.

Eclipse environment

For everyone, who is not satisfied with pure Ant development there is a ready-to-use option of using Eclipse tool. Though there are certain prerequisites in order to achieve a fully operative Eclipse environment. Since Glassfish AS has been chosen for a primary platform of Alembik development, all Eclipse modules are configured to use some environment properties provided by the IDE Glassfish plug-in (available here).

The plug-in itself requires its own prerequisite software, hence the fastest way to achieve a complete IDE is to plug it into an enhanced Eclipse distribution called Easy Eclipse Server. Easy Eclipse version 1.2.2.2 combined with Glassfish plug-in v. 0.4 make a safe and proven bet.