The part of API based on the OMA approach follows its specification and uses the TranscodingRequest and TranscodingResponse classes as the primary Data Transfer Objects to communicate with the transcoding server.

The first two methods: processSync() and processAsync() are the core for the whole framework. They send an OMA transcoding request to the server in synchronous and asynchronous mode respectively. The synchronous version returns a TranscodingResponse instance, which contains a set of JobResult instances for all scheduled jobs (see below). In case a client does not want to perform any transcoding, but merely load a source media file into the server's storage, there is a TranscodingUtils.setNoTranscoding() method available, which sets the appropriate flag.

Once having a request sent, there are two simple methods to obtain the current status of any of its jobs: isSourceFileReady() and isTranscodedFileReady(). Both let clients check the availability of a source and an output media file respectively, whose processing has been previously scheduled by a job of the specified identity (within a given request).

For those who require more detailed info the API offers getTranscodingInfo() method, through which client can obtain more detailed description of a job status. The returned JobResult object (returned as well within the processSync response) contains Output instance with the location (URL) of a result file (a source one in case of "no transcoding" flag imposed, otherwise a transcoded one).

More information is carried within the JobResult.OutputMediaProperties' extension data. For clients convenience TranscodingUtils class offers two methods: getResultState() and getResultInfo(). The first returns phase (TranscodingState.getPhase()) and estimated progress (TranscodingState.getPercentage()) of a transcoding process. The latter one provides the detailed information about the result file.

The result info covers: the file duration in seconds (if it is audio or video) and file size in KBs of a processed file. Both info refers either to a source or a transcoded file depending on "no transcoding" flag setting. In case of a source file one may get some additional data: the boolean value stating whether the source file has been loaded in its entirety, the optional number of downloaded segments (see DownloadTransformation) and its storage loading timestamp in milliseconds.

For those interested in a more straight-forward approach, there is a simplified slice of API available.

The methods are actually the counterparts of the API methods described before; instead of a fully-fledged request object these methods accept a URL of the media file to be transcoded along with a transcoding profile id and an optional size limit of the output file. As mentioned elsewhere the server maintains a list of predefined profiles (each with a unique id); each one is actually a predefined set of transcoding parameters.

For the clients focused on mobile environments, the TranscodingManager component provides some utility methods for constructing transcoding requests on behalf of particular devices.

The first method constructs a transcoding request for a URL source of the media file, a User-Agent identifier corresponding to the mobile device, the actual media type (Image, Audio, Video or Text) and an optional size limit. The second enforces the desired dimensions of the output media file (which applies only to images and videos). Alternatively one may use the third option, which specifies the required media dimensions as percentage of a device screen size. Last but not least, there is the fourth method, by which the streaming transformation can be requested (videos only).

In all these cases the server takes responsibility for translating the User-Agent string (with optional dimensions) into a set of transcoding parameters. Otherwise it is the client who has to provide values. Please mind that in case of audios and videos one has to specify proper codecs in mime format; please refer to a special MediaConstants class, which defines most popular codec names and content types.

Alembik SOAP service is built on the JAX-WS 2.1.x technology following the OMA STI guidelines. The WSDL file of the transcoding service is located at the following location (of any Alembik server instance):

Most WSDL service methods are the extact counterparts of those of TranscodingService; the only difference is that the asynchronous mode is not exposed through a separate method, but is enforced by passing the asynchro string in the TranscodingRequest's policyRef field.

Please have a look at simple examples of SOAP envelopes, which represent transcoding request and transcoding response.

The thorough description of service objects can be found in the OMA-STI specification. Note that several proprietary extensions have been added in all the places where OMA did not provide sufficient coverage. All of them are explained in detail in the sections relevant to the functionality they affect.

Another way for scheduling media transcoding is exposed through a set of Java servlets. The principal component of the HTTP API is org.alembik.http.SyncTranscodingServlet, which is mapped at the server-side by /transcode path. The servlet carries out transcoding in the synchronous mode and if successfully finished it redirects a client to a result file; in case of failure the client is served with an error image or page.

Asynchronous processing is realized by org.alembik.http.AsyncTranscodingServlet, available through /transcodeAsync path. Unfortunately this mode is currently not supported in Tomcat container.

The status checking mechanism comes with org.alembik.http.IsFileReadyServlet exposed via /isReady path. The components checks the transcoding process state and returns one of the following results:

• a result file, if it is ready,
• an auto-refreshing status page with the actual job state (percentage and phase), if the job is still in process,
• an error image/page, if the job transcoding has failed.

Note that this servlet works in the same manner for both synchronous and asynchronous jobs.

The fourth API component is org.alembik.http.TimeoutTranscodingServlet and it is mapped with /timeoutTranscode path. The servlet calls the standard (synchronous) transcoding servlet with a given connection timeout set for a given amount of milliseconds passed by timeout parameter (default value is 5000 milliseconds). If the waiting time elapses and there is no result available yet, it returns an error (see above).

Hence if the transcoding process is finished on time (HTTP response arrival or job in the RELEASED state), it returns a result file; otherwise (socket timeout error or timeout expiry) it redirects client to an error image/page. As one may observe the servlet can be used for the asynchronous mode emulation in the application containers which do not support it.

Moreover, clients can easily distinguish a failure from processing/release states by examining the HTTP response headers. All transcoding errors are returned/redirected with Alembik-Status header set to 404, which otherwise is set to 200.

All the servlets work in a very intuitive manner; they accept all possible property names of OMA TranscodingJob object (including the composite ones too) as URL path parameters and directly returns transcoded output to the requesting client.

The only exception are transformations and extension data properties, which are handled in a different manner. Any attribute for a particular transformation can be passed by appending the transformation name and then the attribute name itself (both dot-separated) to target.transformation prefix. The extension data maps are handled in a similar way: an extension property name has to be added just behind extensionData string of a pertinent object.

For the sake of making the URLs shorter there have been introduced several abbreviations:

• "src." may replace "source."
• "src.loc" may replace "source.location"
• "trg." may replace "target."
• "trg.tp." may replace "target.transcodingParams."
• "trg.tr" may replace "target.transformation"
• "exD." may replace "extensionData."

All these constant values are defined in the Constants class. Below there are presented several examples of abbreviated URL parameters:

Note that transcoding a media file with a User-Agent as the sole "formatting" parameter requires determination of the proper result's media type:

The User-Agent itself can be passed either within HTTP header or as target.profileID parameter. Thus final URLs might look like those below:

Mind that Alembik API package contains the JobUtils class, which provides utility methods for converting a TranscodingJob object into a set of URL parameters and vice versa.

Below there is a list of the most important and useful transcoding URL parameters accepted by Alembik transcoding servlets.

• id - transcoding request's originator ID (as defined by OMA)
• lang - language in the lower-case, two-letter ISO Language Code (optional, used only in error handling now)



• source.location - URL of the source media file
• source.contentType - mime-type of the source media file (optional)
• source.extensionData.SourceProtocol - [HTTP, FILE, CACHE] - protocol for media retrieval (defaults to HTTP)
• source.extensionData.SourceReloadPolicy - [NEVER, ONLY_ONCE, ALWAYS, IF_OLDER_THAN] - media retrieval policy (defaults to IF_OLDER_THAN)
• target.extensionData.SourceOlderThan - number of minutes for which the source file will not be reloaded under IF_OLDER_THAN policy (defaults to 15 minutes)



• target.profileID - User-Agent string or pre-defined profile id (optional - defaults to 'User-Agent' header value of the request)
• target.applicationSizeLimit - desired maximum file size (in bytes - optional)



• target.transcodingParams.image - makes image the desired media type of the output (to be appended without any value if there is no other image-related parameter specified)
• target.transcodingParams.image.width - desired image width
• target.transcodingParams.image.height - desired image height
• target.transcodingParams.image.contentType - desired mime-type of the image
• target.transcodingParams.image.extensionData.relativeWidth - desired image width relative to a requesting device screen
• target.transcodingParams.image.extensionData.relativeHeight - desired image height relative to a requesting device screen
• target.transcodingParams.image.resizeDirective - [AspectRatio, Crop, Stretch] - resizing strategy (defaults to AspectRatio)



• target.transcodingParams.audio - makes audio the desired media type of the output (to be appended without any value if there is no other audio-related parameter specified)
• target.transcodingParams.audio.contentType - desired mime-type of the audio



• target.transcodingParams.video - makes video the desired media type of the output (to be appended without any value if there is no other video-related parameter specified)
• target.transcodingParams.video.contentType - desired mime-type of the video
• target.transcodingParams.video.videoVisual.width - desired video width
• target.transcodingParams.video.videoVisual.height - desired video height
• target.transcodingParams.video.videoVisual.codec - desired visual codec of the video
• target.transcodingParams.video.videoAudio.codec - desired audio codec of the video
• target.transcodingParams.video.extensionData.relativeWidth - desired video width relative to a requesting device screen
• target.transcodingParams.video.extensionData.relativeHeight - desired video height relative to a requesting device screen
• target.transcodingParams.video.resizeDirective - [AspectRatio, Crop, Stretch] - resizing strategy (defaults to AspectRatio)



• target.transcodingParams.text - makes text document (HTML page) the desired media type of the output (to be appended without any value if there is no other text-related parameter specified)
• target.transcodingParams.text.extensionData.screenWidth - desired text width
• target.transcodingParams.text.extensionData.screenHeight - desired text height
• target.transcodingParams.text.extensionData.ImageRendering - [NO_IMAGES, CLIENT_PROCESSING, SERVER_PROCESSING] - specifies the transcoding policy for embedded images (defaults to CLIENT_PROCESSING)
• target.transcodingParams.text.extensionData.MWDetect - [NONE, PASSIVE, ACTIVE] - specifies the level of mobile-enabled sites detection (defaults to ACTIVE)
• target.transcodingParams.text.extensionData.PageSizeEval - [TEXT_ONLY, TEXT_WITH_TAGS] - specifies the algorithm evaluating page sizes (defaults to TEXT_ONLY)



• target.transformation.DownloadLimit.size - cuts downloading after reaching the specified size (in bytes)
• target.transformation.DownloadLimit.duration - cuts video/audio downloading after reaching the specified duration (in seconds) - the result is approximate
• target.transformation.DownloadLimit.treatComplete - if true the truncated video/audio will be treated as a complete media file


• target.transformation.Offset.startTime - starts video/audio transcoding after the specified point (in miliseconds)
• target.transformation.DurationLimit.limit - cuts video/audio transcoding after reaching the specified duration (in miliseconds)


• target.transformation.ExtractFrame.second - extracts a frame (image) from a video at the given second of its duration


• target.transformation.Streaming - enables video streaming - to be appended with no value set
• target.transformation.Hinting - enables video hinting - to be appended with no value set


• target.transformation.NoLinks - suppresses links in a rendered page - to be appended with no value set
• target.transformation.OnlyText - suppresses links and media content (images, videos, etc.) in a rendered page - to be appended with no value set
• target.transformation.OrganizeText - rearranges the text content of a source page - to be appended with no value set