Preview Generation

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.

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:

which convert

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.

  1. Log in as admin user.
  2. From the control panel, go to "Server Admin" and the "External Services" tab.
  3. At the bottom, select the most suitable jar for download.
  4. After that, restart the server.
  5. 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:

dl.file.entry.preview.video.containers=mp4,ogv

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.
2 Attachments
53377 Views
Average (6 Votes)
The average rating is 4.666666666666667 stars out of 5.
Comments
Threaded Replies Author Date
I am trying to use Xuggler in Liferay 6.1 GA2.... Navin Agarwal October 17, 2012 4:57 AM
I presume you have restarted the server after... Alexander Chow April 23, 2013 1:03 AM
Hi, I just want to disable PDF thumbnails. I... Ciprian Pavel February 15, 2013 5:37 AM
Hi, I am able to get preview but it takes... Suyash Bhalekar March 11, 2013 5:53 AM
Hi, I am able to get preview but it takes... Suyash Bhalekar March 11, 2013 5:55 AM
@Ciprian What version are you running? There... Alexander Chow April 23, 2013 1:08 AM
Hi Alexander, I am running 6.1.0 CE. Ciprian Ciprian Pavel April 24, 2013 4:56 AM
So, in 6.1.0 CE it should disable the... Alexander Chow April 25, 2013 7:29 AM
I added the imageMagick and I can see in the... Bogdan Herte October 18, 2013 3:30 AM
The link given in this page related to Xuggler... asif aftab February 19, 2014 6:34 AM
Hi! I'm facing the same issue. By command line... Alba Garcia March 12, 2015 5:03 AM
How to obtain preview in ADT? For example after... Alessandro Lachina February 5, 2015 8:49 AM
How to obtain preview in ADT? For example after... Alessandro Lachina February 5, 2015 8:49 AM
How to obtain preview in ADT? For example after... Alessandro Lachina February 5, 2015 8:49 AM
How to obtain preview in ADT? For example after... Alessandro Lachina February 5, 2015 8:49 AM
How to obtain preview in ADT? For example after... Alessandro Lachina February 5, 2015 8:49 AM
How to obtain preview in ADT? For example after... Alessandro Lachina February 5, 2015 8:49 AM
Any News? Alessandro Lachina March 26, 2015 4:16 AM

I am trying to use Xuggler in Liferay 6.1 GA2. in Server Administration -> External Services in Xuggler sections. Where is says to download and install the OS compatible version. Which I have done.

Now in portal-ext.properties , I have mentioned
xuggler.enabled=true
dl.file.entry.preview.video.containers=mp4,ogv

I have uploaded .Mp4 video is Document Library , when I try to preview it , it does not show the video.
Help me with suggestion
Posted on 10/17/12 4:57 AM.
Hi,

I just want to disable PDF thumbnails.
I have tried setting dl.file.entry.thumbnail.enabled=false without any luck.

Any ideaas?

Ciprian
Posted on 2/15/13 5:37 AM.
Hi,

I am able to get preview but it takes around 5-10 min time. We have the functionality of multiple uploads. So just wanted to know that
1. How preview generation process works?
2.Is it simultaneously creating preview for my multiple uploads and is it/what is the cause for taking long time for preview?

Thanks.
Posted on 3/11/13 5:53 AM in reply to Ciprian Pavel.
Hi,

I am able to get preview but it takes around 5-10 min time. We have the functionality of multiple uploads. So just wanted to know that
1. How preview generation process works?
2.Is it simultaneously creating preview for my multiple uploads and is it/what is the cause for taking long time for preview?

Thanks.
Posted on 3/11/13 5:55 AM.
I presume you have restarted the server after installing the library? When you try to preview it, does it say it is trying to generate a preview? Are there any stack traces.
Posted on 4/23/13 1:03 AM in reply to Navin Agarwal.
@Ciprian What version are you running? There was a bug on this at one point but it should be fixed in the latest build.

@Suyash All the requests are queued up so one at a time. It really depends on the format and the file you are generating a preview for – videos/audio files can take 30min-1hr if they are pretty big whereas a simple PDF document or image can be done in a matter of seconds.
Posted on 4/23/13 1:08 AM.
Hi Alexander,

I am running 6.1.0 CE.

Ciprian
Posted on 4/24/13 4:56 AM in reply to Alexander Chow.
So, in 6.1.0 CE it should disable the generation of the thumbnail but, unfortunately, it will leave a 404 for the actual thumbnail. This is fixed as part of LPS-29612.

Alex
Posted on 4/25/13 7:29 AM in reply to Ciprian Pavel.
I added the imageMagick and I can see in the logs that it converts the pdf but nothing appears in the document_preview directory. When executing the command from terminal it's working, the pdf is converted.
This is the command : convert -limit area 2GiB -limit map 1GiB -limit memory 2GiB -alpha off -density 300x300 -adaptive-resize 1000 -depth 8 /Users/username/Documents/liferay-portal-6.1.20-ee-ga2/data/document_library/101­54/85616/4902/1.0 /Users/username/Documents/liferay-portal-6.1.20-ee-ga2/tomcat-7.0.27/temp/lifera­y/document_preview/157577.1.0.png
Posted on 10/18/13 3:30 AM.
The link given in this page related to Xuggler is not working. Please provide some working link. Thanks for aforesaid information it is really helpful.
Thanks
Posted on 2/19/14 6:34 AM in reply to Bogdan Herte.
How to obtain preview in ADT? For example after enabled Xuggler Asset Publisher that show a single Document (video) in Full content show also the preview pane.
But how to show only preview pane (so we could obtain a sort of video player portlet) ?
Posted on 2/5/15 8:49 AM.
How to obtain preview in ADT? For example after enabled Xuggler Asset Publisher that show a single Document (video) in Full content show also the preview pane.
But how to show only preview pane (so we could obtain a sort of video player portlet) ?
Posted on 2/5/15 8:49 AM.
How to obtain preview in ADT? For example after enabled Xuggler Asset Publisher that show a single Document (video) in Full content show also the preview pane.
But how to show only preview pane (so we could obtain a sort of video player portlet) ?
Posted on 2/5/15 8:49 AM.
How to obtain preview in ADT? For example after enabled Xuggler Asset Publisher that show a single Document (video) in Full content show also the preview pane.
But how to show only preview pane (so we could obtain a sort of video player portlet) ?
Posted on 2/5/15 8:49 AM.
How to obtain preview in ADT? For example after enabled Xuggler Asset Publisher that show a single Document (video) in Full content show also the preview pane.
But how to show only preview pane (so we could obtain a sort of video player portlet) ?
Posted on 2/5/15 8:49 AM.
How to obtain preview in ADT? For example after enabled Xuggler Asset Publisher that show a single Document (video) in Full content show also the preview pane.
But how to show only preview pane (so we could obtain a sort of video player portlet) ?
Posted on 2/5/15 8:49 AM.
Hi! I'm facing the same issue.

By command line I can convert from PDF to png.
convert /opt/liferay/bundle/liferay-portal-6.2-ce-ga2/data/document_library/10154/10202/­602/1.0 /opt/liferay/bundle/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/temp/liferay/documen­t_preview/12345.png

But I cannot see the PDF previews in the documents and media portlet. In fact the document_preview folder is empty.
Posted on 3/12/15 5:03 AM in reply to Bogdan Herte.
Posted on 3/26/15 4:16 AM in reply to Alessandro Lachina.