The Alembik tag library forms a separate module, which communicates with the server through the common transcoding API. Its main purpose is to make easier the construction of WAP/HTML pages in JSP environment, where media content needs to be transcoded before sending it back to client.

The tag library supports image, audio and video medias. The centre pivot of the framework is embodied by three master tags: <alembik:img>, <alembik:audio> and <alembik:video>, which define what media needs to be transcoded and how it should be loaded. Their work may be customized by a set of nested tags belonging to the following categories:

The master tags are in charge of producing single-job transcoding requests, which they pass afterwards to the server through its API. Each request structure is determined by the information passed through tag attributes and its nested tags.
Alembik tag library allows choosing the way the transcoding result is presented within a page. The resultMode attribute offers three different types of result formatting (for more details please refer to the master tags section):

  • htmlTag: produces an HTML/WAP output according to the obtained transcoding response (default).
  • htmlLink: return an HTML/WAP link to the required media.
  • byteStream: return the required media in form of direct byte stream.

The following samples present four different ways of putting the tag library into use (they all show <img> tag in action, but the pattern for <audio> and <video> tags is the same):

  • Basic Mode:

    Adapt media to device
    <alembik:img src="http://kimia.com/images/logo.jpg" alt="logotipo" wall="true">
        <alembik:userAgentAdaptation />
    </alembik:img>

    Adapt media to default profile
    <alembik:img src="http://kimia.com/images/logo.jpg" alt="logotipo" wall="true">
        <alembik:defaultProfileAdaptation profileId="TM_img_5" />
    </alembik:img>

  • Intermediate Mode:

    Adapt media to chosen transcoding parameters
    <alembik:img src="http://kimia.com/images/logo.jpg" alt="logotipo" wall="true">
        <alembik:imageProfileAdaptation mimetype="image/gif" width="80" />
    </alembik:img>
  • Expert Mode:

    Adapt media to the device with some additional features chosen
    <alembik:img src="http://kimia.com/images/logo.jpg" alt="logotipo" wall="true">
        <alembik:userAgentAdaptation />
        <alembik:imageProfileAdaptation mimetype="image/gif" width="80" height="60" resizeDirective="Stretch" />
    </alembik:img>

    Adapt media to the device and with transformations
    <alembik:img src="http://kimia.com/images/logo.jpg" alt="logotipo" wall="true">
        <alembik:userAgentAdaptation />
        <alembik:mirror axis="UD" />
        <alembik:noiseReduction />
    </alembik:img>

    Adapt media to the device with some features by default and with transformations
    <alembik:img src="http://kimia.com/images/logo.jpg" alt="logotipo" wall="true">
        <alembik:userAgentAdaptation />
        <alembik:imageProfileAdaptation mimetype="image/gif" width="80" resizeDirective="AspectRatio" maxColors="256" />
        <alembik:mirror axis="UD" />
        <alembik:noiseReduction/>
    </alembik:img>

  • Expert Async Mode:

    Adapt media to the device in async mode
    <alembik:video src="http://kimia.com/video/intro.mpg" alt="intro" wall="true">
        <alembik:userAgentAdaptation/>
        <alembik:imageProfileAdaptation width="80" resizeDirective="AspectRatio" />
        <alembik:mirror axis="UD" />
        <alembik:async jobId="job_001" />
    </alembik:img>

    .......

    <alembik:waitAndShow jobId="job_001" timeout="4000" />

    ... or ...

    <alembik:isMediaReady jobId="job_001">
        <alembik:showMedia jobId="job_001" />
    </alembik:isMediaReady>

The Alembik TLD definition file is available here.

 

Master tags:

Generic tags:

Adaptation tags:

Asynchronous mode tags:

Information tags:

Transformation tags:

 

 

The master tags create and pass transcoding requests to the server. They specify which media file needs to be transcoded and how to load it. At the moment there are three master tags available, one for each supported media type:

  • <img>: processes an image file
  • <audio>: processes an audio file
  • <video>: processes a video file

<img>

The master tag for the image transcoding describes the location of a source file to be processed; additional transcoding parameters can be specified in the nested tags. Its implementation is provided in the following classes:

  • org.alembik.taglib.image.ImageTag
  • org.alembik.taglib.image.ImageTEI
img tag attributes and possible values
Parameters Required Default Value Possible Values
src:
url of the source file to transcode 		No   a URL or a relative path
protocol:
the protocol for reading the source file		 No if src is context-relative file, otherwise http http, file, cache
resultMode:
result returning mode		 No htmlTag htmlTag, htmlLink, byteStream
wall:
is the tag nested within tags of WNG (WALL Next Generation) library?		 No false true, false
alt:
a short description of the image		 No   a string value

For a full description of the protocol attribute's cache value, please refer to the <cache> tag description.

Example:
<body>
    <alembik:img src="http://alembik.com/images/logo.jpg" alt="logo" wall="false"></alembik:img>
</body>

The HTML result is presented below:

<body>
    <img src="transcoded file location" alt="logo" />
</body>

<audio>

The master tag for the audio transcoding assigns a source file to be transcoded; additional transcoding parameters can be specified in the nested tags. Its behavior is implemented in the following classes:

  • org.alembik.taglib.audio.AudioTag
  • org.alembik.taglib.audio.AudioTEI
audio tag attributes and possible values
Parameters Required Default Value Possible Values
src:
url of the source file to transcode 		No   a URL or a relative path
protocol:
the protocol for reading the source file		 No if src is context-relative file, otherwise http http, file, cache
resultMode:
result returning mode		 No htmlTag htmlTag, htmlLink, byteStream
wall:
is the tag nested within tags of WNG (WALL Next Generation) library?		 No false true, false
alt:
a short description of the audio		 No   a string value
identityUrl:
an identity URL of a source file		 No   a URL
Example:
<body>
    <alembik:audio src="http://alembik.com/audio/jingle.mp3"></alembik:audio>
</body>

The HTML result is presented below:

<body>
    <embed src="transcoded file location" />
</body>

<video>

The master tag for the video transcoding assigns a source file to be transcoded; additional transcoding parameters can be specified in the nested tags. Its behavior is implemented in the following classes:

  • org.alembik.taglib.video.VideoTag
  • org.alembik.taglib.video.VideoTEI
video tag attributes and possible values
Parameters Required Default Value Possible Values
src:
url of the source file to transcode 		No   a URL or a relative path
protocol:
the protocol for reading the source file		 No if src is context-relative file, otherwise http http, file, cache
resultMode:
result returning mode		 No htmlTag htmlTag, htmlLink, byteStream
wall:
is the tag nested within tags of WNG (WALL Next Generation) library?		 No false true, false
alt:
a short description of the video		 No   a string value
identityUrl:
an identity URL of a source file		 No   a URL
Example:
<body>
    <alembik:video src="http://alembik.com/video/clip.flv"></alembik:video>
</body>

The HTML result is presented below:

<body>
    <embed src="transcoded file location" />
</body>

Result Mode

Each master tag may be embellished with the resultMode attribute, which specifies the way the transcoding result is presented. Currently there are three values supported: htmlTag, htmlLink and byteStream.

The htmlTag value (a default one) makes the framework return an appropriate HTML/WAP tag corresponding with the media type. Please refer to the previous examples to see how it works. Another option is the htmlLink value, which is recommended when dealing with media files, which are too big to be included in HTML/WAP pages. Switching to this option makes the tag return only an HTML/WAP link to the transcoded media file; it is up to users then whether to download it or not. In case of the video streaming being requested the result link will be a video streaming link with RTSP protocol applied.

The last option is the byteStream value, which returns the required media file in form of a direct byte stream. This mode is completely independent from the HTML context and gives immediate access to the result of a transcoding process.

audio.jsp
<%@ page %>
<%@ taglib uri="/WEB-INF/tlds/alembik.tld" prefix="alembik" %>
<% String path="http://alembik.com/audio/missile.mp3"; %>

<alembik:audio src="<%@=path%>" resultMode="byteStream">
  <alembik:audioProfileAdaptation mimeType="audio/mpeg" />
</alembik:audio>

As the example above shows the JSP file does not contain any HTML tag, just the Alembik <audio>; tag declaration. Whenever the page is requested the framework returns directly the required file setting the appropriate mime-type; it is up to the receiver to handle it properly (for example by use of a media player). It is also possible to call the JSP in an HTML file as follows:

<embed src="audio.jsp" width="140" height="150" />

In this case the result is the same as in htmlTag mode, but it allows introducing a different HTML tag or some additional tag attributes.
The following example presents a fine separation between HTML-oriented pages and the definition of streaming process. The audio.jsp reference could be used then within others JSP pages as a common-use component adapting media content to the requesting party needs.

audio.jsp
<%@ page %>
<%@ taglib uri="/WEB-INF/tlds/alembik.tld" prefix="alembik" %>
<% String path="http://alembik.com/audio/missile.mp3"; %>

<alembik:audio src="<%@=path%>" resultMode="byteStream">
  <alembik:offset startTime="15000" />
  <alembik:durationLimit limit="10000" />
</alembik:audio>

<body>
  <alembik:audio src="http://yourdomain.com/jsps/audio.jsp" resultMode="httpTag">
    <alembik:audioProfileAdaptation mimeType="audio/mpeg" />
  </alembik:audio>
</body>

 


 

This category includes four general tags, which can be used in conjuction with any master tag. They are explained in detail in the following sections:

<userAgentAdaptation>

Presence of this tag makes the framework adapt the given media to device capabilities, determined by the passed user-agent string. The server adjusts media dimension, format and other parameters to the available device capabilities set.
Its behaviour is implemented in the class:

  • org.alembik.taglib.generic.UserAgentAdaptationTag

<defaultProfileAdaptation>

The tag requests the server to transform a given media according to a predefined transcoding profile of the given profileId. Each profile usually defines a standard configuration for a particular category of devices. Its behaviour is implemented in the class:

  • org.alembik.taglib.generic.DefaultAdaptationTag
defaultProfileAdaptation tag attributes and possible values
Parameters Required Default Value Possible Values
profileId:
a predefined transcoding profile identifier		 Yes   A string value

<reloadPolicy>

The tag requests the server to load a given source media file using the reload policy of the given name. Its behaviour is implemented in the class:

  • org.alembik.taglib.generic.ReloadPolicyTag
reloadPolicy tag attributes and possible values
Parameters Required Default Value Possible Values
sourceReloadPolicy:
a reload policy name		 Yes   ONLY_ONCE, ALWAYS, IF_OLDER_THAN
sourceOlderThan:
a time lapse for the IF_OLDER_THAN policy (in mins)		 No 15 A non-negative integer value

<cache>

Cache tag provides developers with a possibility of reusing the result of a partial or complete transcoding job as the starting point for others jobs. The tag may be useful for users such as web administrators who need to prepare a set of well defined transcoded media in the storage, in order to speed up mobile site performance and improve final users experience. This operation, if well planned (eg. provide a set of videos adaptation for the most common devices), could improve the overall Alembik performance.
Its behaviour is implemented in the following classes:

  • org.alembik.taglib.generic.CacheTag
  • org.alembik.taglib.generic.CacheTEI
cache tag attributes and possible values
Parameters Required Default Value Possible Values
cacheId:
the cache key used to store and retrieve the media		 Yes   A string value
cachetime:
the expiry time of the element (in ms)		 Yes   A non-negative integer (0 disables expiry)

NOTE: At present the cache only works with GAIAMediaProcessor; other media processors will not work with this tag.

Example:

In the following example the levelCorrection and mirror transformations are reqested for the source image. The result gets stored in the cache (forced by <cache> tag) ready for subsequent processing (in this case - additional adaptations to the required devices).

<alembik:img src="http://alembik.com/images/logo.jpg">
    <alembik:levelCorrection/>
    <alembik:mirror axis="UD"/>
    <alembik:cache cacheid="myKey" cachetime="10000"/>
    <alembik:userAgentAdaptation/>
</alembik:img>

<alembik:img src="myKey" protocol="cache">
    <alembik:defaultProfileAdaptation profileId="Nokiaprofile"/>
</alembik:img>

<alembik:img src="myKey" protocol="cache">
    <alembik:defaultProfileAdaptation profileId="LGprofile"/>
</alembik:img>

<alembik:img src="myKey" protocol="cache">
    <alembik:defaultProfileAdaptation profileId="Motorolaprofile"/>
    <alembik:rotation clockwiseAngle="90"/>
</alembik:img>


 

This section provides information on the specific adaptation tags. Each tag is associated to a particular media type (image, audio and video) and allow clients specify a set of transcoding parameters specific for that type. They are intended to be used wherever a traditional user-agent based profile resolution is not sufficient. Here is a list of currently available implementations:

<imageProfileAdaptation>

The tag adjusts the image transcoding parameters. If not used in conjuction with the <userAgentAdaptation> tag, at least mimetype attribute is required.
Its implementation is provided in the following classes:

  • org.alembik.taglib.image.ImageAdaptationTag
  • org.alembik.taglib.image.ImageAdaptationTEI
imageProfileAdaptation tag attributes and possible values
Parameters Required Default Value Possible Values
contentType:
requests the desired mime-type for an image 		No   An image mime-type
sizeLimit:
limits the size of a transcoded image file (in bytes)		 No   An integer
width:
sets the width of an image (in pixels)		 No   An integer
height:
sets the height of an image (in pixels)		 No   An integer
resizeDirective:
sets the resize method		 No AspectRatio AspectRatio, Crop, Stretch
upsizeAllowed:
permits upsizing of the image dimensions		 No false true, false
colorScheme:
sets the colors scheme		 No   True, PaletteColor, PaletteGrey
maxColors:
sets the max numbers of colors for the color scheme (only if set)		 No   An integer
Example:

In the following example the original JPEG image is transformed into a GIF image and resized the width to 80 pixels without deformation (AspectRatio resizing).

<alembik:img src="http://alembik.com/images/logo.jpg" wall="true">
    <alembik:imageProfileAdaptation contentType="image/gif" width="80" resizeDirective="AspectRatio"/>
</alembik:img>

<audioProfileAdaptation>

The tag adjusts the audio transcoding parameters. If not used in conjuction with the <userAgentAdaptation> tag, at least mimetype and codec attributes are required.
Its implementation is provided in the following classes:

  • org.alembik.taglib.image.AudioAdaptationTag
  • org.alembik.taglib.image.AudioAdaptationTEI
audioProfileAdaptation tag attributes and possible values
Parameters Required Default Value Possible Values
codec:
requests the desired codec for an audio 		No   An audio codec name
contentType:
requests the desired mime-type for an audio 		No   An audio mime-type
sizeLimit:
limits the size of a transcoded audio file (in bytes)		 No   An integer
bitRate:
sets the bit rate		 No   An integer
samplingRate:
sets the sampling rate		 No   An integer
samplingResolution:
sets the sampling resolution		 No   An integer
channels:
sets the number of channels		 No   Mono, Stereo
Example:

In this example the original MP3 audio file is transcoded into a mono WAV media file.

<alembik:audio src="http://alembik.com/audio/jingle.mp3" wall="true">
    <alembik:audioProfileAdaptation codec="audio/wav" contentType="audio/wav" channels="mono"/>
</alembik:audio>

<videoProfileAdaptation>

The tag adjusts the video transcoding parameters. If not used in conjuction with the <userAgentAdaptation> tag, at least mimetype, audioCodec and visualCodec attributes are required.
Its implementation is provided in the following classes:

  • org.alembik.taglib.image.VideoAdaptationTag
  • org.alembik.taglib.image.VideoAdaptationTEI
videoProfileAdaptation tag attributes and possible values
Parameters Required Default Value Possible Values
contentType:
requests the desired mime-type for a video 		No   A video mime-type
sizeLimit:
limits the size of a transcoded video file (in bytes)		 No   An integer
visualCodec:
requests the desired visual codec for a video		 No   a visual codec name
visualWidth:
sets the width		 No   An integer
visualHeight:
sets the height		 No   An integer
visualFrameRate:
sets the frame rate		 No   An integer
visualBitRate:
sets the visual bit rate		 No   An integer
visualResizeDirective:
sets the resize method		 No AspectRatio AspectRatio, Stretch, Crop
visualUpsizeAllowed:
permits upsizing of the video dimensions		 No false true, false
audioCodec:
requests the desired audio codec for a video		 No   An audio codec name
audioBitRate:
sets the audio bit rate		 No   An integer
audioSamplingRate:
sets the sampling rate		 No   An integer
audioSamplingResolution:
sets the sampling resolution		 No   An integer
audioChannels:
sets the number of audio channels		 No   Mono, Stereo
Example:

In this example the original MPEG video file is transcoded into a mono 3GP format file.

<alembik:video src="http://alembik.com/videos/spot.mpg" wall="true">
    <alembik:videoProfileAdaptation contentType="video/3gpp" visualCodec="video/mpg4" audioCodec="audio/aac" audioChannels="mono"/>
</alembik:video>


 

This section explains the usage of information tags in detail. Their major purpose is displaying information on a particular transcoded file, hence they always appear nested within master tags. Here is a list of currently available information providers:

<isSourceFileReady>

The tag checks whether a given source file is present (e.g. downloaded) in the server's storage. If it is present the tag's "body" will be evaluated; otherwise it is ignored.
Its implementation is provided in the following classes:

  • org.alembik.taglib.info.IsSourceFileReadyTag
  • org.alembik.taglib.info.IsSourceFileReadyTEI
isSourceFileReady tag attributes and possible values
Parameters Required Default Value Possible Values
src:
url of the source file to transcode 		Yes   a URL or a relative path
protocol:
the protocol for reading the source file		 No if src is context-relative file, otherwise http http, file
identityUrl:
an identity URL of a source file		 No   a URL
size:
the maximum size of an original file (in bytes)		 No   a positive integer
duration:
the maximum duration of an original file (in seconds)		 No   a positive integer
treatComplete:
should the original file be treated as complete?		 No false true, false
start:
the size offset of an original file (in bytes)		 No   a positive integer
offset:
the duration offset of an original file (in seconds)		 No   a positive integer

The tag is supposed to be used independently from master tags. For more information on its application and partition-related paremeters (size, duration, etc.) and their usage please see the <downloadLimit> tag description.

<isNotSourceFileReady>

The tag checks whether a given source file is NOT present (e.g. downloaded) in the server's storage. If so the tag's "body" will be evaluated; otherwise it is ignored.
Its implementation is provided in the following classes:

  • org.alembik.taglib.info.IsNotSourceFileReadyTag
  • org.alembik.taglib.info.IsNotSourceFileReadyTEI
isNotSourceFileReady tag attributes and possible values
Parameters Required Default Value Possible Values
src:
url of the source file to transcode 		Yes   a URL or a relative path
protocol:
the protocol for reading the source file		 No if src is context-relative file, otherwise http http, file
identityUrl:
an identity URL of a source file		 No   a URL
size:
the maximum size of an original file (in bytes)		 No   a positive integer
duration:
the maximum duration of an original file (in seconds)		 No   a positive integer
treatComplete:
should the original file be treated as complete?		 No false true, false
start:
the size offset of an original file (in bytes)		 No   a positive integer
offset:
the duration offset of an original file (in seconds)		 No   a positive integer

The tag is supposed to be used independently from master tags. For more information on its partition-related paremeters (size, duration, etc.) and their usage please see the <downloadLimit> tag description.

<fileDuration>

The tag displays the duration of a transcoded video/audio file (if available).
Its implementation is provided in the following class:

  • org.alembik.taglib.info.FileDurationTag

Possible master tags:

  • <audio>
  • <video>
Example:

Below there is an example of the tag in action.

<alembik:video src="http://alembik.com/videos/clip.flv" wall="true">
    <alembik:userAgentAdaptation />
    <alembik:fileDuration />
</alembik:video>

Then the generated code will look like this:

<a href="http://localhost/alembik/storage/N314265626/131684052/tnsc--1698794398.mp4">
    Click here to open the media file
</a>
<br/>
    DURATION : 38 secs
<br/>

<fileSize>

The tag displays the size of a transcoded video/audio file (if available).
Its implementation is provided in the following class:

  • org.alembik.taglib.info.FileSizeTag

Possible master tags:

  • <img>
  • <audio>
  • <video>
Example:

Below there is an example of the tag in action.

<alembik:video src="http://alembik.com/videos/clip.flv" wall="true">
    <alembik:userAgentAdaptation />
    <alembik:fileSize />
</alembik:video>

Then the generated code will look like this:

<a href="http://localhost/alembik/storage/N314265626/131684052/tnsc--1698794398.mp4">
    Click here to open the media file
</a>
<br/>
    SIZE : 614 KB
<br/>

 

 

This section describes the tags designed to facilitate imposing various transformations on a given media content. Although not all of the transformations are applicable for each media type, the framework does not perform any verification of the viability of used tags and leaves it to the programmer's responsibility. The list of possible and implemented transformations for each tag are resumed in the media processing chapter. The thorough description of OMA-defined transformations can be found here

Properly applied the tags may improve output results and hence users experience, providing diverse filters like noise reduction, brightness adjusting or contrast increasing and some special features like overlaying of text or image on the original media or limiting duration of audio and videos.

The list of currently available transformation tags is presented below:

<levelCorrection>

The tag adjusts the image colors level. The filter resets the darkest and lightest values on the lightness scale [0 to 255] of the underlying image and adjusts the midrange of colors. The tag does not accept any attributes.
Its behavior is implemented in the following class:

  • org.alembik.taglib.transformations.LevelCorrectionTag

Possible master tags:

  • <img>
  • <video>
Example:

Below there is a code sample making use of the tag.

<alembik:img src="http://alembik.com/images/logo.jpg">
    <alembik:userAgentAdaptation />
    <alembik:levelCorrection />
</alembik:img>

<mirror>

The tag mirrors the image around the specified axis.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.transformations.MirrorTag
  • org.alembik.taglib.transformations.MirrorTEI
mirror tag attributes and possible values
Parameters Required Default Value Possible Values
axis:
the axis type		 Yes   UD (up-down: vertical), LR (left-right: horizontal)

Possible master tags:

  • <img>
  • <video>
Example:

The example below mirrors an image around the horizontal axis.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:userAgentAdaptation />
    <alembik:mirror axis="UD" />
</alembik:img>

<noiseReduction>

The tag reduces noise of an image or a video. The transformation is actually a noise peaks elimination filter that smooths the objects within an image (or video's visual part) without losing edge information and without creating undesired structures. The tag does not accept any attributes.
Its behavior is implemented in the following class:

  • org.alembik.taglib.transformations.NoiseReductionTag

Possible master tags:

  • <img>
  • <video>
Example:

The sample code below presents a noise reduction example.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:userAgentAdaptation />
    <alembik:noiseReduction />
</alembik:img>

<rotation>

The tag rotates an image or a video's visual part.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.transformations.RotationTag
  • org.alembik.taglib.transformations.RotationTEI
rotation tag attributes and possible values
Parameters Required Default Value Possible Values
clockwiseAngle:
the clockwise rotation angle		 Yes   90, 180, 270, auto

The "auto" value makes the operation dependent on the image/video resizing (if requested). The appropriate rotation will be applied only if it helps maintain aspect ratio as close as possible to the original dimensions. For example resizing image from its original [176x144] size to the new [144x176] with the clockwiseAngle set to auto will invoke the 90 degrees rotation. Thus the "automatic" rotation is meaningful only if media resizing is appropriately defined.

Possible master tags:

  • <img>
  • <video>
Example:

Here is a code sample with the image rotation in action.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:userAgentAdaptation />
    <alembik:rotation clockwiseAngle="90" />
</alembik:img>

<sharpen>

The tag performs the image or video visual sharpening. The tag does not accept any attributes.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.transformations.SharpenTag
  • org.alembik.taglib.transformations.SharpenTEI

Possible master tags:

  • <img>
  • <video>
Example:

Below there is an example usage of the tag.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:userAgentAdaptation />
    <alembik:sharpen />
</alembik:img>

<durationLimit>

The tag reduces the duration time of an audio or a video file by cutting off the part which exceeds it.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.transformations.DurationLimitTag
  • org.alembik.taglib.transformations.DurationLimitTEI
durationLimit tag attributes and possible values
Parameters Required Default Value Possible Values
limit:
the required duration time (in milliseconds)		 Yes   A positive integer

Possible master tags:

  • <audio>
  • <video>
Example:

The example below shortens an MP3 file to 5 seconds.

<alembik:audio src="http://alembik.com/audios/jingle.mp3">
    <alembik:userAgentAdaptation />
    <alembik:durationLimit limit="5000" />
</alembik:audio>

<offset>

The tag makes an audio or a video file start from a specified offset time by cutting off the part which precedes it.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.transformations.OffsetTag
  • org.alembik.taglib.transformations.OffsetTEI
offset tag attributes and possible values
Parameters Required Default Value Possible Values
startTime:
the offset time (in milliseconds)		 Yes   A positive integer

Possible master tags:

  • <audio>
  • <video>
Example:

This example below removes the first 15 seconds of an MP3 file.

<alembik:audio src="http://alembik.com/audios/jingle.mp3">
    <alembik:userAgentAdaptation />
    <alembik:offset startTime="15000" />
</alembik:audio>

<agc>

The tag performs the Automatic Gain Control. The tag does not accept any attributes.
Its behavior is implemented in the following class:

  • org.alembik.taglib.transformations.AGCTag

Possible master tags:

  • <audio>
  • <video>
Example:

Here is an example application of the tag.

<alembik:audio src="http://alembik.com/images/gioconda.jpg">
    <alembik:userAgentAdaptation />
    <alembik:agc />
</alembik:audio>

<frameRateSample>

The tag sets the frame sampling rate of an animated image (without changing the speed and the duration of the media). It changes the number of frames/slides.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.transformations.FrameRateSampleTag
  • org.alembik.taglib.transformations.FrameRateSampleTEI
frameRateSample tag attributes and possible values
Parameters Required Default Value Possible Values
fps:
the frame sampling rate for an animated image		 Yes   A positive float

Possible master tags:

  • <img>
Example:

In the example below an animated image is adapted to the device capabilities, while its frame sampling rate is set to 32 fps.

<alembik:img src="http://alembik.com/images/animated.gif">
    <alembik:userAgentAdaptation />
    <alembik:frameRateSample fps="32" />
</alembik:img>

<frameRateOutput>

The tag sets the frame rate in the transcoded animated image (and thus change also the speed and the duration, e.g. to create slow/fast motion effects/adjustments). However, it does not change the number of frames/slides. For animation, this determines the time interval for each frame.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.transformations.FrameRateOutputTag
  • org.alembik.taglib.transformations.FrameRateOutputTEI
frameRateOutput tag attributes and possible values
Parameters Required Default Value Possible Values
fps:
the frame sampling rate for an animated image		 Yes   A positive float

Possible master tags:

  • <img>
Example:

In the example below an animated image is adapted to the device capabilities, while its frame sampling rate is set to 32 fps.

<alembik:img src="http://alembik.com/images/animated.gif">
    <alembik:userAgentAdaptation />
    <alembik:frameRateOutput fps="32" />
</alembik:img>

<numberOfFrames>

The tag sets the number of frames/slides in the transcoded animated image. Thus it indicates whether animation (>1) or single image (=1) is intended.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.transformations.NumberOfFramesTag
  • org.alembik.taglib.transformations.NumberOfFramesTEI
numberOfFrames tag attributes and possible values
Parameters Required Default Value Possible Values
totalFrames:
the number of frames		 Yes   A positive integer

Possible master tags:

  • <img>
Example:

In this example an animated gif image is transformed into a static one.

<alembik:video src="http://alembik.com/images/animated.gif">
    <alembik:userAgentAdaptation />
    <alembik:numberOfFrames totalFrames="1" />
</alembik:video>

<frameFill>

The tag indicates if the target image frame should be filled while source image aspect ratio will be maintained, overriding either target height or width (when applicable). The parameters, if exists, define the chosen color, using RGB values.
Its functionality is implemented in the classes:

  • org.alembik.taglib.transformations.FrameFillTag
  • org.alembik.taglib.transformations.FrameFillTEI
frameFill tag attributes and possible values
Parameters Required Default Value Possible Values
r:
red level 		Yes   An integer from the [0..255] range
g:
green level		 Yes   An integer from the [0..255] range
b:
blue level		 Yes   An integer from the [0..255] range

Possible master tags:

  • <img>
  • <video>
Example:

Here is an example code making use of the tag.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:frameFill r="0" g="0" b="0"/>
</alembik:img>

<cropping>

The tag performs cropping of an image or a video visual. The transcoded result is then a rectangular area defined by the pixel coordinates of the source image.
Its functionality is implemented in the classes:

  • org.alembik.taglib.transformations.CroppingTag
  • org.alembik.taglib.transformations.CroppingTEI
cropping tag attributes and possible values
Parameters Required Default Value Possible Values
top:
the Y coordinate of the top corner of the area to crop 		Yes   A positive integer
left:
the X coordinate of the top corner of the area to crop		 Yes   A positive integer
bottom:
the Y coordinate of the down corner of the area to crop		 Yes   A positive integer
right:
the X coordinate of the down corner of the area to crop		 Yes   A positive integer

The cropping coordinates should be set within the actual dimensions of the original image or video.

Possible master tags:

  • <img>
  • <video>
Example:

In the example below a JPG image is cropped in its [100x100] (pixels) sub-area.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:cropping top="200" left="570" bottom="300" right="670" />
</alembik:img>

<brightness>

This tag adjusts the brightness correction of an image or a video's visual part.
Its functionality is implemented in the classes:

  • org.alembik.taglib.transformations.BrightnessTag
  • org.alembik.taglib.transformations.BrightnessTEI
brightness tag attributes and possible values
Parameters Required Default Value Possible Values
level:
the brightness correction level		 Yes   An integer from the [-50..50] range (inclusive)

When level is set to 0 there is no correction applied.

Possible master tags:

  • <img>
  • <video>
Example:

The example below shows an image with brightness correction adjusted to its maximum level.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:brightness level="50" />
</alembik:img>

<contrast>

This tag adjusts the contrast correction of an image or a video's visual part.
Its functionality is implemented in the classes:

  • org.alembik.taglib.transformations.ContrastTag
  • org.alembik.taglib.transformations.ContrastTEI
contrast tag attributes and possible values
Required Default Value Possible Values
level:
the contrast correction level		 Yes An integer from the [-50..50] range (inclusive)

When level is set to 0 there is no correction applied.

Possible master tags:

  • <img>
  • <video>
Example:

The example below shows an image with contrast correction adjusted to its maximum level.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:contrast level="50" />
</alembik:img>

<color>

This tag adjusts the gamma correction of an image or a video's visual part.
Its functionality is implemented in the classes:

  • org.alembik.taglib.transformations.ColorTag
  • org.alembik.taglib.transformations.ColorTEI
color tag attributes and possible values
Parameters Required Default Value Possible Values
level:
the gamma correction level		 Yes   An integer from the [-50..50] range (inclusive)

When level is set to 0 there is no correction applied.

Possible master tags:

  • <img>
  • <video>
Example:

The example below shows an image with gamma correction adjusted to its maximum level.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:color level="50" />
</alembik:img>

<textOverlay>

The tag places a text message over an original image or video. It gives the possibility of choosing its color and font. In case of image overlaying the tag offers various effects like text orientation, opacity and font style; for videos one may define position and time coordinates as well as enable "scrolling" effect.
Its functionality is implemented in the classes:

  • org.alembik.taglib.transformations.TextOverlayTag
  • org.alembik.taglib.transformations.TextOverlayTEI
textOverlay tag attributes and possible values
Parameters Required Image Video Default Value Possible Values
message:
the text to be overlayed 		Yes V V   A string
family:
the family font		 No V V <img>
Serif		 <img>
Serif, Sans-serif, Monospaced, Dialog, and DialogInput
and all the others supported by the local JRE
<video>
LucidaBrightRegular		 <video>
LucidaBrightDemiBold, LucidaBrightDemiItalic, LucidaBrightItalic, LucidaBrightRegular, LucidaSansDemiBold, LucidaSansRegular, LucidaTypewriterBold, LucidaTypewriterRegular
color:
the color of the message		 No V V red <img>
black, blue, cyan, DarkGray, gray, green, LightGray, magenta, orange, pink, red, white, yellow
<video>
all the above and
navy, turquoise, DarkGreen, khaki, gold, beige, chocolate, brown, salmon, tomato, maroon, violet, purple
style:
the text style		 No V X plain plain, bold, italic, bold-italic
opacity:
the background opacity		 No V X 100 (no opacity) A positive integer
smooth:
the anti-aliasing value		 No V X yes yes, no
orientation:
the text orientation		 No V X horz horz, diag, lowbanner
effect:
the visual effect		 No V X   shadow, outline, engrave
size:
the font size		 No X V 80 A positive integer
posX:
the horizontal position of the text (in pixels)		 No
(applicable only when scrolling is disabled)		 X V 10 A positive integer
posY:
the vertical position of the text (in pixels)		 No X V video height / 2 A positive integer
offset:
the second from which on the text appears		 No X V 0 A positive integer
duration:
the number of seconds the text is shown		 No X V 5 A positive integer
scroll:
is text scroolling enabled?		 No X V false true, false

Possible master tags:

  • <img>
  • <video>
Example:

Below there is a slice of JSP code with an exemplary use of the tag.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:textOverlay message="DEMO" style="bold" effect="shadow" />
</alembik:img>

<overlayLogo>

The tag overlays an image on a selected image or video. It usually serves for placing a logo or a symbol on the original file (e.g. to produce copyrighted or preview images). It is possible to choose a transparent color and a general transparency level by setting the appropriate attributes.
Its functionality is implemented in the classes:

  • org.alembik.taglib.transformations.OverlayLogoTag
  • org.alembik.taglib.transformations.OverlayLogoTEI
overlayLogo tag attributes and possible values
Parameters Required Image Video Default Value Possible Values
src:
the URL of an image to overlay		 Yes V V   A URL or a relative path
protocol:
the protocol to use for read an image to overlay		 No V V if src is context-relative file, otherwise http file, http
width:
the image width (in pixels)		 No V V 120 A positive integer
transparentcolor:
the transparent color in the background		 No V X black black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white, white, yellow
posX:
the horizontal position of the image (in pixels)		 No X V 0 A positive integer
posY:
the vertical position of the image (in pixels)		 No X V 0 A positive integer
offset:
the second from which on the image appears		 No X V 0 A positive integer
duration:
the number of seconds the image is shown		 No X V 3 A positive integer

Possible master tags:

  • <img>
  • <video>
Example:

Below there is a slice of JSP code with an exemplary use of the tag.

<alembik:img src="http://alembik.com/images/gioconda.jpg">
    <alembik:overlayLogo src="http://alembik.com/images/logo.gif" />
</alembik:img>

<advertisement>

The tag concatenates two videos: the advertisement one determined by videoURL and the original one appointed by the master <video> tag.
Its functionality is implemented in the class:

  • org.alembik.taglib.transformations.AdvertisementTag
advertisement tag attributes and possible values
Parameters Required Default Value Possible Values
videoURL:
the URL of a video to be placed
before the original one		 Yes   A URL of the advert video

Possible master tags:

  • <video>
Example:

The code sample below concatenates an advert file with an original video clip.

<alembik:video src="http://alembik.com/videos/clip.mpg">
    <alembik:advertisement videoURL="http://alembik.com/videos/adver.mpg" />
</alembik:video>

<animatedToStatic>

The tag converts an original animated image into a static one extracting the first frame. The tag does not accept any attributes.
Its functionality is implemented in the class:

  • org.alembik.taglib.transformations.AnimatedToStaticTag

Possible master tags:

  • <img>
Example:

The code sample below transforms an animated image into a static one.

<alembik:img src="http://alembik.com/images/animatedImage.gif">
    <alembik:animatedToStatic />
</alembik:img>

<downloadLimit>

The tag offers various download manipulations of a source media file. Its principal purpose is to shorten the waiting time for a media transcoding. It may offer a fast access to a video preview as well as subsequent segments progressively produced. Since the transformation truncates source files physically, it is only applicable to videos and audios (providing that it does not corrupt them). Its functionality is implemented in the class:

  • org.alembik.taglib.transformations.DownloadLimitTag
  • org.alembik.taglib.transformations.DownloadLimitTEI
downloadLimit tag attributes and possible values
Parameters Required Default Value Possible Values
size:
the maximum size of an original file (in bytes)		 No   a positive integer
duration:
the maximum duration of an original file (in seconds)		 No   a positive integer
treatComplete:
should the original file be treated as complete?		 No false true, false
repeat:
should download progressively produce segments of an original file? (download only - no transcoding)		 No false true, false
maxCount:
the maximum number of segments to be produced (see repeat above)		 No   a positive integer
minDuration:
the minumum duration of a segment to be produced (see repeat above)		 No   a positive integer
start:
the size offset of an original file (in bytes)		 No   a positive integer
offset:
the duration offset of an original file (in seconds)		 No   a positive integer

Possible master tags:

  • <audio>
  • <video>
Example:

The following samples show various modes of making use of the tag functionality. The first example terminates downloading of a video file after reaching 500KB (if it is larger) and then adapts its truncated part to a user device.

<alembik:video src="http://alembik.com/videos/clip.mpg" resultMode="htmlLink">
    <alembik:userAgentAdaptation />
    <alembik:downloadLimit size="512000" />
</alembik:video>

In the next sample the tag terminates downloading of a video file after reaching 15 seconds (if it is longer) and then adapts its truncated part to a user device.

<alembik:video src="http://alembik.com/videos/clip.mpg" resultMode="htmlLink">
    <alembik:userAgentAdaptation />
    <alembik:downloadLimit duration="15" />
</alembik:video>

The example below shows how to force the truncated file be treated like a complete one. The source file will be treated by subsequent transcoding requests as if it were not truncated. The treatComplete attribute may be used in conjuction with size and duration parameters. In case when both are specified, the more restrictive value prevails, but the file is ALWAYS treated as a complete one (to avoid any storage namespace ambiguity).

<alembik:audio src="http://alembik.com/audios/track.mp3" resultMode="htmlLink">
    <alembik:userAgentAdaptation />
    <alembik:downloadLimit duration="12" treatComplete="true" />
</alembik:audio>

The next piece of JSP code demonstrates progressive segmentation of a video. Here the file will be loaded dynamically producing file segments of a determined size or duration. This approach allows for the on-the-fly access to subsequent parts of the video file, which are constantly being made available as the downloading process carries on.

The repeat attribute may be used in conjuction with either size or duration. Additionaly one may limit the number of segments with maxCount attribute (the download will stop after reaching the desired value) and/or, in case of duration-based segmentation, specify the minimum duration with minDuration for the last part (if not met it will be appended to the previous segment).

The attribute does NOT permit any additional transcoding; the tag will only download and partition the file. Since there is no final result to be shown it is recommended to apply it in asynchronous mode.

<alembik:video src="http://alembik.com/videos/clip.flv">
    <alembik:downloadLimit repeat="true" duration="20" maxCount="4" minDuration="3" />
    <alembik:asyncRequest jobId="job_repeat_001" />
</alembik:video>

The last sample shows how to make advantage of progressive segmentation described above. A relevant segment is referenced by the combination of start and size attributes (in case of the size-based segmenting) or the duration and offset pair (for the duration-based segmenting). Note that size value must match the one from previous "repeat call" and start value has to be its whole multiple.

Since the progressive download is supposed to work asynchronously, first the isSourceFileReady tag needs to be used to check whether the relevant file segment is already in place. Observe that start value must be a multiplication of size; the same rule applies to offset and duration respectively.

<alembik:isSourceFileReady src="http://alembik.com/videos/clip.flv" start="800000" size="400000">
    <alembik:video src="http://alembik.com/videos/clip.flv" resultMode="htmlLink">
        <alembik:userAgentAdaptation />
        <alembik:downloadLimit start="800000" size="400000" />
    </alembik:video>
</alembik:isSourceFileReady >

<alembik:isSourceFileReady src="http://alembik.com/videos/clip.flv" offset="40" duration="10">
    <alembik:video src="http://alembik.com/videos/clip.flv" resultMode="htmlLink">
        <alembik:userAgentAdaptation />
        <alembik:downloadLimit offset="40" duration="10" />
    </alembik:video>
</alembik:isSourceFileReady >

<extractFrame>

The tag extracts a frame at a given point of time from a video. Since the result is an image, its appropriate master tag is <img>.
Its functionality is implemented in the class:

  • org.alembik.taglib.transformations.ExtractFrameTag
extractFrame tag attributes and possible values
Parameters Required Default Value Possible Values
second:
the second at which a frame is to be extracted		 Yes   an integer

Possible master tags:

  • <img>
Example:

The sample code below extracts from a video the frame at its 5th second and then resizes the output image.

<alembik:img src="http://alembik.com/videos/clip.mpg">
    <alembik:imageProfileAdaptation width="50" height="50" />
    <alembik:extractFrame second="5" />
</alembik:img>

<streaming>

The tag makes a transcoded video be returned as a stream. The tag does not accept any attributes.
Its functionality is implemented in the class:

  • org.alembik.taglib.transformations.StreamingTag

Possible master tags:

  • <video>
Example:

Here is the example of a typical usage of the tag.

<alembik:video src="http://alembik.com/videos/clip.mpg" resultMode="httpLink">
    Streaming
    <alembik:streaming/>
</alembik:video>

The generated code will look like this:

<a href="rtsp://localhost/N1715139055/N1676212809/tnsc--1171805225.mp4">
    Streaming
</a>

 

 

The tags described here allow clients to introduce asynchronous processing into their JSP pages. Its biggest advantage is that the client can show HTML pages without waiting for the Alembik response; the user will be free then to read the page content or to navigate to other pages, while the transcoding request is processed in the background. It is a special treat for mobile clients whose connections may be expensive, slow and their devices could be blocking other functions awaiting a complete response.

Below there is a list of all tags of this category, followed by two examples at the end of the chapter.

<asyncRequest>

The tag makes the request be processed in the asynchronous mode. It just needs to be nested inside a master tag (<img>, <audio> or <video>). The jobId attribute specifies a distinct name for the transcoding job, by which the other async-mode tags may identify it.
Its behavior is implemented in the following class:

  • org.alembik.taglib.generic.AsyncRequestTag
asyncRequest tag attributes and possible values
Parameters Required Default Value Possible Values
jobId:
assigns the distinct name to a transcoding job 		Yes   A string

<waitAndShow>

The tag makes the environment await a specified job (of the id assigned previously by <asyncRequest> tag) for a given period of time. If the response arrives on time, the transcoded result will be shown; otherwise it will be ignored.
Its behavior is implemented in the following classes:

  • org.alembik.taglib.generic.WaitAndShowTag
  • org.alembik.taglib.generic.WaitAndShowTEI
waitAndShow tag attributes and possible values
Parameters Required Default Value Possible Values
jobId:
the name of a transcoding job 		Yes   A string
timeout:
the timeout (in millisecs) 		No 5000 A positive integer

<status>

The tag shows the current status of the job processing. As above the actual job is determined by the id assigned previously by <asyncRequest> tag.
Its behavior is implemented in the following class:

  • org.alembik.taglib.generic.StatusTag
status tag attributes and possible values
Parameters Required Default Value Possible Values
jobId:
the name of a transcoding job 		Yes   A string

<isMediaReady>

The tag asks the server if the transcoding job has been completed and thus whether the result media is ready. If it is ready the tag's "body" will be evaluated; otherwise it is ignored. As above the actual job is determined by the id assigned previously by <asyncRequest> tag.
Its behavior is implemented in the following class:

  • org.alembik.taglib.generic.IsMediaReadyTag
isMediaReady tag attributes and possible values
Parameters Required Default Value Possible Values
jobId:
the name of a transcoding job 		Yes   A string

<isNotMediaReady>

The tag asks the server if the transcoding job has been completed and thus whether the result media is ready. If it is NOT ready the tag's "body" will be evaluated; otherwise it is ignored. As above the actual job is determined by the id assigned previously by <asyncRequest> tag.
Its behavior is implemented in the following class:

  • org.alembik.taglib.generic.IsNotMediaReadyTag
isNotMediaReady tag attributes and possible values
Parameters Required Default Value Possible Values
jobId:
the name of a transcoding job 		Yes   A string

<showMedia>

The tag shows the result of a transcoding job determined by the id assigned previously by <asyncRequest> tag. Normally this tag should be nested within <isMediaReady> tag to ensure that the job has been actually completed.
Its behavior is implemented in the following class:

  • org.alembik.taglib.generic.ShowMediaTag
showMedia tag attributes and possible values
Parameters Required Default Value Possible Values
jobId:
the name of a transcoding job 		Yes   A string
Example 1

In the following example the image transcoding request is sent in asynchronous mode. During the page evaluation the client will be waiting up to 4 seconds for any response from the server.

<%@ page%>
<%@ taglib uri="/WEB-INF/tlds/alembik.tld" prefix="alembik"%>
<html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<head>
  <title>Alembik - async media transcoding & displaying</title>
</head>
<body>
  <%String path = "http://alembik.com/image/gioconda.jpg";%>
  <h2>ALEMBIK IMAGE:</h2>
  <br>
  <alembik:img src="<%=path%>">
      <alembik:mirror axis="UD" />
      <alembik:asyncRequest jobId="job_001" />
  </alembik:img>

  Read the text waiting for the result!

  <alembik:img>
      <alembik:waitAndShow jobId="job_001" timeout="4000" />
  </alembik:img>
</body>
</html>
Example 2

This example presents two separate pieces of code. First sends an image transcoding request in asynchronous mode. The second will present the result to a user providing that it is ready. Those two samples can be placed in different places (JSP pages) allowing portal builders to prepare the transcoding data beforehand.

<head>
  <title>Alembik - asynchronous media transcoding</title>
</head>
<body>
  <%String path = "http://alembik.com/image/gioconda.jpg";%>
  <alembik:img src="<%=path%>">
      <alembik:mirror axis="UD" />
      <alembik:asyncRequest jobId="job_001" />
  </alembik:img>
</body>
</html>

<head>
  <title>Alembik - asynchronous media displaying</title>
</head>
<body>
  <alembik:isMediaReady jobId="job_001">
     <h2>ALEMBIK IMAGE:</h2>
     <br>
     <alembik:img>
         <alembik:showMedia jobId="job_001" />
     </alembik:img>
  </alembik:isMediaReady />
</body>
</html>