File Transformation

With the need to accommodate multiple devices, especially mobile phones, it is essential to adapt images and videos for better viewing in each situation. To address this, Lumis offers File Transformation, which allows modifications in size and format (video only) for each file added to the portal.

Enabling Transformations

Transformations will be enabled by service instance, allowing for activation in the service of Images or Documents. To enable a specific service instance, such as the image service, it is necessary to navigate to one of its interfaces and right-click on it, selecting the option "File Properties."

The window below will be displayed.

To enable transformation for the service instance, simply check the "File Transformation" checkbox.

Once enabled, the file transformation management will load, and the user will be asked if they wish to load the proposals suggested by Lumis for the transformations:

Customization of Metadata Extractors

Lumis already has its own metadata extractors by default, however, it is possible to customize the extraction of these metadata by registering new extractors, which will replace the default ones. To do this, it is necessary to enter the qualified name of the audio or video extractor in the fields shown above and then click Ok.

Notes

The custom extractor must implement the IMetadataExtractor interface.
For audio or video files, LumisXP uses the JAVE 1.0.2 library to extract metadata or transformations, and therefore it needs to be installed separately in the "www/WEB-INF/lib" folder, or an error will occur when trying to process these types of files. For more information and to download JAVE, consult the JAVE manual.
The JAVE library uses FFMPEG to encode and decode files. FFMPEG is a solution written in C language that requires specific compilation for the target platform to be portable from one platform to another. Therefore, JAVE allows the user to compile it and specify the path to the FFMPEG executable. To specify the path of FFMPEG in Lumis, simply uncomment the <fileTransformation> tag in the lumisportalconfig.xml file and provide the file path in the ffmpegExecutablePath node. By default, Lumis will use the executables provided in the JAVE package itself.

Adding Transformations

To add a new transformation, it is necessary to click "Add" in the "Transformation" area of the "File Properties" pop-up.

The following pop-up will be displayed:

Key:The key of the transformation. It is unique per service instance and will be displayed in the XML of the interface.
Description: The description of the transformation. Small JPEG, for example.
Prefix*: The prefix that will receive the transformed file name.
Suffix*: The suffix that will receive the transformed file name.
Content-Type: A regular expression indicating which content types of files will undergo the registered transformation. For example, the regular expression ^video/(flv|mpe?g)$ will cause files with the content type video/flv or video/mpeg to undergo the transformation.
Extension: What extension will receive the transformed file. If no extension is entered, the transformed file will receive the same extension as the original file.
Transformation Parameters: The parameters of the transformation are the attributes of the transformation.
- Name: The name of the parameter.
- Builder: The builder is the class responsible for initiating the transformation itself. A valid builder must implement the ITransformationBuilder and have an ITransformation associated to perform the transformation.
- Value: The expected value of the transformation. For example, if the transformation is to be made from a flv file to avi, its value should be avi. Or for scaling transformations, the value should be an integer.

* It is mandatory to enter at least the suffix or prefix for a transformation.

To add a new parameter, simply click "Add" and a new parameter set will appear.

To delete the parameter, simply click on the "X" next to the parameter set.

The number of parameters for a transformation is unlimited, provided that there is at least one registered parameter; when attempting to delete the last parameter, the portal should reject the action.

Note

By default, Lumis comes with 2 pre-registered builders. They are lumis.portal.file.transformation.TranscodingTransformationBuilder and lumis.portal.file.transformation.ScaleTransformationBuilder. These builders are used in 3 pre-registered parameters that can be used for new transformation parameters, requiring only the value to be entered. They are WIDTH, which must have as builder ScaleTransformationBuilder, FORMAT, which must have as builder TranscodingTransformationBuilder, and HEIGHT, which must have as builder ScaleTransformationBuilder. For example: Name: WIDTH, Builder: lumis.portal.file.transformation.ScaleTransformationBuilder, and Value: 420. The provided file would undergo a transformation and also generate another file with its width changed to 420. These builders and parameters cannot be deleted.

Upon filling in the data and clicking Ok, the transformation will be displayed in the management:

Editing Transformations

To edit an added transformation, just select the desired item and click "Edit".

The following editing pop-up will be displayed:

To edit, just modify the desired pop-up and click Ok.

Exclusion of Transformations

To delete a transformation, simply select the desired file and click "Delete".

Regenerating All Transformations

After adding new transformations to the service instance or editing the previously persisted ones, it is possible to retransform the files that have already been added, also applying the new transformations or changes to the previously made transformations to all files in the instance. To do this, after making a change to the transformations, simply check the "Regenerate all transformations" checkbox.

Upon clicking "Ok" in the pop-up, the following alert will be displayed:

Upon clicking "Ok," all files will be re-transformed.

Disabling Transformations

To disable transformations, simply click on the previously checked checkbox.

When disabling it, and consequently clicking "Ok," all transformations will be lost.

Transformed Files

The files added by the service instance will be automatically transformed (if there are any registered transformations) and will be persisted in the file system in the same folder where the original file will be persisted, relative to the path lumisdata\data\files.

LumFile XML

The information about the transformations executed by the service instance will be available in the LumFile XML, such as the generated file id (fileId), its path (fullPath), content type (contentType), size (fileSize), original file (originalFileId), its metadata, and the format (format).

Execution Queues

All operations on the file transformation functionality, except for adding transformations, use Execution Queues. That is, these actions are queued for execution along with other actions, whether related to the transformation or not. Therefore, for example, upon deleting/editing a certain transformation, depending on the number of queues to be executed and the number of files in which this change must be reflected, changes to the transformed files may take some time to be realized. For more information on Execution Queues, refer to Execution Queues.

Known Issues

The default library used by Lumis to perform video transformations, JAVE, includes and uses an FFMPEG executable. There is a known issue with this executable, which is not capable of performing scaling for frames that are not multiples of 2. Therefore, in the case of videos, it is not recommended to use odd values for the WIDTH and HEIGHT parameters, since said transformation will not occur, and an error will be logged regarding this event.