Authors: Will Abson (Alfresco), Peter Löfgren (Loftux AB)
This add-on project for Alfresco Share provides a number of content viewers to complement the out-of-the box set supplied with Share, plus a dashlet allowing any content item to be displayed on a site dashboard. The add-on was previously known as Media Previews.
Viewers can be configured into the Web Preview component of the Document Details Page. In addition, the add-on supplies a custom dashlet which can be used to display any chosen document or content item on a site dashboard.
The following viewers are supplied in the v2.x add-on for use on Alfresco 4
PdfJs displays documents, presentations and any other file capable of being transformed to PDF in-line in the web browser using the excellent pdf.js viewer, which uses the power of HTML5 to remove Share's Flash dependency for document viewing.
The viewer supports a number of features not directly supported by the Flash document previewer, such as a sidebar with thumbnail, outline and search views, bookmarking of individual pages of a document, and will remember the page number and zoom level of previous documents that you have viewed.
FLVPlayer and MP3Player display compatible audio and video files respectively, within the web-browser using the open source FLV Player and MP3 Player media players by neolao. Based on the content's MIME type, the updated component automatically chooses the appropriate previewer to use.
While similar to the Flash players provided by Share out-of-the-box, these implementations allow advanced customization of the player via configuration and if FFmpeg is installed, will fire up a transformation to allow viewing of non-H264/FLV video and non-MP3 audio. The user is informed when conversion is in progress and the screen automatically updates when the content can be viewed.
Embed uses an in-line iFrame to embed the content itself directly inside the web page. It is suitable for use with content types that can be viewed directly within the web browser such as plain text and PDF, with the Chrome or Acrobat plugins installed. Again, this can be used to avoid the use of the Flash previewer for some clients.
Prettify allows formatted code, mark-up and other supported text formats to be displayed in directly in the document and uses the google-code-prettify project to provide an in-line browser-based view with syntax highlighting.
WebODF is an EXPERIMENTAL viewer which uses the AGPL-licensed WebODF project to display ODF content directly in the web browser.
WebODF cannot be distributed with the add-in itself, so in order to use it you must also download the latest JAR file from the supporting share-webodf project and install it in the same way as the main media-viewers JAR file.
This custom dashlet allows a site administrator to pick a content item from the site which will be displayed to all site members on the site dashboard. The dashlet will choose the correct viewer automatically and is able to use the out-of-the-box viewers supplied plus the custom viewers provided by this add-on or other add-ons.
In addition to the Share component extensions the add-on supplies repository extension configuration for defining 'thumbnailed' content in PDF, H264/FLV and MP3 formats, a full-size image thumbnail for video files in JPEG format, and a transformer based on FFmpeg for generating the audio and video formats.
For Alfresco 4.x, download the latest 2.x version of Media Viewers.
For Alfresco 3.x, download the latest 0.x or 1.0 version of Media Preview.
Copy the JAR file into the tomcat/shared/lib folder of your Alfresco installation (create the lib directory if it does not exist). If you are hosting the repository and Share in different Tomcat containers then you should install it in both.
See Configuration below, for instructions on how to enable the viewers in Share.
The supplied Spring configuration extends the repository thumbnailing capabilities to support H264/FLV thumbnails for video content and MP3 thumbnails for audio content, both using FFmpeg, and PDF thumbnails for content such as Microsoft Word and Powerpoint files. PDF thumbnails can be generated using the default repository transformers, but a custom transformer is supplied to enable the FFmpeg transformations.
The previews therefore do not require FFmpeg, but it is highly recommended to support the widest range of formats, and for thumbnail image generation.
To enable FFmpeg support you must
-
Install FFmpeg (with x264) on the server
It is unlikely that your standard package manager will install this for you. The FFmpeg documentation does however contain detailed documentation for compiling on Ubuntu and other operating systems and the project also makes pre-built binaries available for download.
-
If the
ffmpegexecutable is not on your system's PATH (i.e. typingffmpeg -versionindicates thatffmpegcould not be found), you must edit youralfresco-global.propertiesfile to define the correct location, e.g.ffmpeg.exe=C:\\FFmpeg\\ffmpeg.exeThe path should not contain spaces, and if you are on Windows you should use forward slashes rather than backslashes as your directory separator, or use double-backslashes to escape them.
If you are running Alfresco and Share in the same application server then the JAR file also contains the required repository configuration, but if these are in separate containers then you will need to install it into both.
Check the alfresco.log file while the repository is starting up for any warnings or errors related to FFmpeg, if you have enabled it.
The dashlet is packaged as a single JAR file for easy installation into Alfresco Share.
An Ant build script is provided to build a JAR file containing the custom files, which can then be installed into the tomcat/shared/lib folder of your Alfresco installation.
To build the JAR file, run the Ant from the base project directory.
ant -f project.xml dist-jar
Or, for the 0.x/1.0 release
ant dist-jar
The command should build a JAR file named media-viewers-<version>.jar in the build/dist directory within your project.
To deploy the add-on files into a local Tomcat instance for testing, you can use the hotcopy-tomcat-jar task. You will need to set the tomcat.home property in Ant.
ant -f project.xml -Dtomcat.home=C:/Alfresco/tomcat hotcopy-tomcat-jar
After you have deployed the JAR file you will need to restart Tomcat to ensure it picks up the changes.
No additional configuration is required for the 0.x/1.x version of the add-on in Alfresco 3, beyond the optional FFmpeg installation documented in Installation, above (required if you wish to use audio/video renditions with the FLVPlayer and MP3Player plugins).
If you are using Alfresco 4, you must enable the correct module in Share's Module Deployment console, which can be accessed by navigating to http://hostname:port/share/page/modules/deploy on your Alfresco server.
The following modules will import the dependencies for the different viewers. You may enable as many as you need.
- PdfJs Viewer
- Embed Viewer
- FLVPlayer Viewer
- MP3Player Viewer
- Prettify Viewer
- WebODF Viewer (Experimental)
The final step to configure the exact content types which the viewer should be used for varies between Alfresco 4.0/4.1 and 4.2, so please follow the correct instructions for your Alfresco version.
If you are using Media Viewers 2.5 or greater on Alfresco 4.2, then you can use the additional configuration modules, e.g. PdfJs Configuration, to automatically enable the viewers in the Document Details page and the dashlet. No overriding of web-preview.get.config.xml is required.
If installing the add-on in Alfresco 4.0/4.1, you must configure the web-preview.get component to use the particular viewers that you wish to enable. To do this, you must
-
Copy the file
WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/preview/web-preview.get.config.xmlfrom the exploded Alfresco webapp into the directoryalfresco/web-extension/site-webscripts/org/alfresco/components/previewunder yourtomcat/shared/classes. You will need to create the new directories if you have not done this previously. -
Modify that file to add in the new viewers as needed, or replace the content with the suggested sample configuration
An in-depth discussion of the redesigned web-preview component in Alfresco 4 is provided on
Will's blog,
where the configuration mechanism is explained.
Upload a supported file type to Alfresco Share and navigate to the Document Details page to see the preview.
To use the Document Viewer dashlet, navigate to a site dashboard. Then, click the Customize Dashboard button to edit the contents of the dashboard and drag the dashlet into one of the columns from the list of dashlets.
###Web Previews
The most common problem that you may see when using the viewers is that the text Preparing Previewer... is shown on the screen. This is usually accompanied by an error in the browser JavaScript console indicating that the plugin instance could not be created.
If you see this on your system, check that the add-on is installed correctly and that you have enabled the relevant viewers in the Module Deployment console.
- If your content does not load using the viewers, check that you have enabled the viewer and configuration modules in Share's Module Deployment console, and (for Alfresco 4.0/4.1) that you have configured your
web-preview.config.xmlas documented above - If PDF content loads using the PdfJs or Embed viewers but other document types do not (e.g. Word, PowerPoint), check that you have added the JAR file to the repository or at least added the repository Spring configuration in your
<TOMAT_HOME>/shared/classes/alfresco/web-extensionfolder.
###FFmpeg
If you have problems with audio and video previews or thumbnails not working, first check your alfresco.log for any errors being thrown at startup, relating to FFmpeg.
If no errors are shown, you can force the transformers to give you a little more information by adding the
following lines to the file webapps/alfresco/WEB-INF/classes/log4j.properties.
log4j.logger.org.alfresco.util.exec.RuntimeExec=debug
log4j.logger.org.alfresco.repo.content.transform=debug
log4j.logger.org.alfresco.repo.thumbnail=debug
If no problems are obvious and you still find that thumbnails do not get generated or the player does not render,
you can make a direct request for the specific renditions to help diagnose the problem. In the URLs below you
will need to replace the {nodeId} token with the GUID of the problematic file (which you can grab from the end of
the Document Details page URL), and substitute in the hostname of your server in place of {hostname}.
- For thumbnail problems, hit http://{hostname}/share/proxy/alfresco/api/node/workspace/SpacesStore/{nodeId}/content/thumbnails/doclib?c=force
- For player problems, hit http://{hostname}/share/proxy/alfresco/api/node/workspace/SpacesStore/{nodeId}/content/thumbnails/h264preview?c=force
This should force the thumbnails to be generated syncronously, and a stack trace will be visible in the page response or in alfresco.log.
-
Internet Explorer is only supported in version 10 and greater due to performance problems in that browser. The Embed viewer can be used instead, otherwise rendering will fall back to the out-of-the-box Flash viewer.
-
In versions 3.3, 3.4.a, 3.4.b and 3.4.c, the video player only supports previews of MP4 and FLV content, due to a bug whereby the thumbnail service cannot produce renditions using a RuntimeExec transformer. The workaround for this is to apply the fix in the JIRA issue to patch your own
alfresco-repository.jar. This is fixed in version 3.4.d. -
Prior to Alfresco Community 3.4.b, adding the additional thumbnail definitions to the thumbnail registry required overriding the entire thumbnailRegistry bean. The supplied Spring configuration still uses this old method for now in order to support the widest range of versions, but if this causes you problems you can use the new
org.alfresco.repo.thumbnail.ThumbnailDefinitionSpringRegistrerbean instead (example config)