In Liferay 6.1, the Document Library portlet has been renamed to the Documents and Media portlet to highlights its unique qualities in supporting documents (e.g., .doc, .odt, .pdf, etc.) as well as multimedia formats (e.g., .wav, .mp3, .mov). Moreover, if configured properly, Liferay will be able to generate preview files for end users to view these files without needing to download them in their entirety. This article addresses this feature of preview generation.
Table of Contents [-]
- Document Previews
- Audio and Video Previews
- Known Issues
Document Previews #
Basic Configuration #
Out of the box, Liferay only ships with Java-based APIs to generate previews for documents. The only tool available that is 100% Java and has a compatible license to be distributed with Liferay is PDFBox. From a vanilla installation of Liferay 6.1, if you upload a PDF file to the new Documents and Media portlet, Liferay will process the PDF in a separate thread. If it is a small file, it can be finished in a matter of seconds. The larger the file is, the longer it takes.
However, the first time you run a conversion like this, you will notice a message that indicates something like the following:
Liferay is not configured to use ImageMagick for generating Document Library previews and will default to PDFBox. For better quality previews, install ImageMagick and enable it in portal-ext.properties.
What this means is quite self-explanatory. You need to install ImageMagick for whatever operating system you are in, which also includes the installation of GhostScript. Then, in portal-ext.properties or the Server Administration control panel under "External Services," enable ImageMagick and double check your the paths for the executable. Then, you should be on your way.
Enable ImageMagick in portal-ext.properties #
In portal-ext.properties the following values are set by default:
imagemagick.enabled=false imagemagick.global.search.path[apple]=/opt/local/bin imagemagick.global.search.path[unix]=/usr/local/bin imagemagick.global.search.path[windows]=C:\\Program Files\\ImageMagick
In order to find out which path ImageMagick is installed in Unix-Systems you may type the following command on your shell:
Support for DOC, ODT, etc. #
Of course, the generation of PDF files are nice, but what about my MS Office or OpenOffice files? For this to work, you need to have OpenOffice running as a separate server and Liferay configured for this. You can simply follow the instructions on the wiki for Document Conversion with OpenOffice, and Liferay should automatically convert from DOC to PDF to the individual preview files.
Font Problems in Preview #
Some configurations have issues with the way a preview is generation where the text seems to be all mixed into each other. This is normally due to problems with the converter not knowing your fonts.
If you are using PDFBox, then reconfigure yourself to use ImageMagick. That's why we put that warning message earlier on. :)
If you are using ImageMagick, then your problem is most likely that ImageMagick does not know the correct path to your fonts. Basically, what is happening is ImageMagick is deferring conversion of PDF files to GhostScript. So, really, you need to make sure the path for the fonts used by ImageMagick is correctly configured in your portal-ext.properties or in your control panel. By default, these are the entries listed in portal.properties:
imagemagick.global.search.path[apple]=/opt/local/bin:/opt/local/share/ghostscript/fonts:/opt/local/share/fonts/urw-fonts imagemagick.global.search.path[unix]=/usr/local/bin:/usr/local/share/ghostscript/fonts:/usr/local/share/fonts/urw-fonts imagemagick.global.search.path[windows]=C:\\ProgramFiles\\ImageMagick
On many Windows systems, the fonts directory is automatically loaded. For OS X, Unix and Linux, you can find this by executing this in your command line:
convert -list configure
This will tell you how ImageMagick is configured, and you should be able to find the font directory as specified as "--with-gs-font-dir=" in CONFIGURE. Just lump that to your ImageMagick path in Liferay and you should be good to go.
If you still have problems, you may just not have the font available to ImageMagick. The way you test is by executing this in your command line:
identify -list font
If the font you need is not listed there, there are a few tutorials online to explain how to add more fonts to ImageMagick:
If you find any other useful links, please add them here.
ImageMagick Throttling #
Both the CPU and the memory usage can be configured to tune resource allocations for ImageMagick. There are two main areas that this can be done: the policy.xml configuration file and environment variables. You can find out what the configured settings are on your system by typing this at the commandline:
identify -list resource
Audio and Video Previews #
Liferay 6.1 also supports the generation of preview files for audio and video files. This also requires another tool to be installed: Xuggler. There are two ways to install this, depending on whether you are running Liferay 6.1 CE/EE GA1 or GA2.
Basic Configuration (6.1 CE/EE GA2) #
For 6.1 CE/EE GA2, installing the Xuggler jar is fairly straight forward.
- Log in as admin user.
- From the control panel, go to "Server Admin" and the "External Services" tab.
- At the bottom, select the most suitable jar for download.
- After that, restart the server.
- Log back in as admin user and make sure Xuggler is enabled in the control panel in the same "External Services" tab.
Basic Configuration (6.1 CE/EE GA1) #
The 6.1.0 CE and EE releases require Xuggler 3.4.1012 which can either be built from source or installed from the binaries:
After this is installed, make sure to enable it in the portal-ext.properties or under the Server Admin control panel. That's pretty much all you need to do and preview files will be generated for most major audio and video formats, and thumbnails extracted from the video file as well.
However, if it is not as easy as you thought, you may have come across a problem where you get an "UnsatisfiedLinkError." If not, you did not follow the installation instructions correctly. See Xuggler's FAQ on this matter since, in fact, it is a frequently asked question. That FAQ also has specific information if you are running this in Eclipse as well.
HTML5 Support #
Ah the beauty of HTML5 is you do not need to have Flash installed to play audio and video. In Liferay 6.1, we have put in the HTML5 hooks for video files. Unfortunately, as of this writing, we may not be able to get the HTML5 audio code working for 6.1 and we are still dependent on Flash (see LPS-22919).
When generating previews for multimedia files, it does take a lot longer to generate than a small DOC file because the files are just that much bigger. Moreover, the browsers you are trying to support will determine which container formats you want need to support. MP4, for example, is supported natively on Safari, Chrome and IE whereas OGV is supported natively on Firefox and Opera. You can therefore configure your portal-ext.properties to specify which of those two containers you are to support with the following property:
However, if you try to configure something other than MP4 or OGV, we will complain to you in a warning message in the console, but still let you do it.
Advanced Configuration #
While we have tried to release the best generation parameters as we can conceive of, you may want to do something different. Particularly, for MP4 generation, if you want to configure the ffmpeg presets, you can change them in portal-ext.properties. Just prefix your values with xuggler.ffpreset. and you should be good to go. You can also tune the bit rates and frame rates for each container format.
Known Issues #
- Don't change video/audio title when uploading it or if you do, add the file extension to it. This is needed by Xuggler so it can determine the video container and then make the conversion properly.
- When generating a video or audio preview, you get an "UnsatisfiedLinkError" in your console. This means you have not configured your paths correctly for Xuggler. See Xuggler's FAQ for the steps to configure your path properly, and the extra step needed if you are running from within Eclipse.
- When uploading an OGV video file, the preview generation treats it as an audio. This is most likely due to the name of your file that ends with the extension .OGG rather than an .OGV. According to the OGG spec, any file ending with .OGG is to be treated as an audio/ogg file. However, not all applications enforce this. Liferay, which leverages Tika in the backend, does and will only recognise this as an audio file. The workaround is to upload the file with the proper .OGV extension.
- Videos with more than 2 audio channels aren't supported. So, in that case, reduce the audio channels to 2 before uploading for preview to be created.
- WebM format isn't supported at the moment.