Home > Digital Asset Management > DAM Functional and Technical Description > HOWTO: Contribute Video Conversion
Digital Asset Management

HOWTO: Contribute Video Conversion

Updated: March 18, 2024

This page explains how video conversions are structured, and provide instructions to perform the standard video conversion operations.

Video conversion concepts

Video conversions are used to fill the video conversions (stored in the vid:transcodedVideos field of a document having the Video facet). The default ones are MP4 480p, Ogg 480p and WebM 480p. The video storyboard info are stored in the vid:storyboard property.

Video conversions are simple XML contributions done on the videoConversions extension point of the org.nuxeo.ecm.platform.video.service.VideoService component. The default video conversions launched after the creation of a Video document are declared in the automaticVideoConversions extension point.

Hyland University
Watch the related courses on Hyland University: DAM Concepts
university_dam.png
university_dam.png

A video conversion depends of a command, a converter and a videoConversion contributions.

Video conversions are working only on documents having the Video facet.

Common conversion contributions

Register a new converter

  • Contribute an XML extension to register a new command line converter called ffmpeg-towebm:
<extension target="org.nuxeo.ecm.platform.commandline.executor.service.CommandLineExecutorComponent"
  point="command">
  <command name="ffmpeg-towebm" enabled="true">
    <commandLine>ffmpeg</commandLine>
    <parameterString> -i #{inFilePath} -s #{width}x#{height} -acodec libvorbis -v 0 #{outFilePath}</parameterString>
    <installationDirective>
      You need to install FFmpeg from http://ffmpeg.org (apt-get install ffmpeg)
    </installationDirective>
  </command>
</extension>

Parameters:

  • inFilePath and outFilePath will be filled by Nuxeo,
  • width and height can be used in your command, they will be passed by the generic VideoConversionConverter.
  • Contribute an XML extension to register a converter that uses our new ffmpeg-towebm command line.
<extension target="org.nuxeo.ecm.core.convert.service.ConversionServiceImpl"
  point="converter">
  <converter name="convertToWebM" class="org.nuxeo.ecm.platform.video.convert.VideoConversionConverter">
    <sourceMimeType>video/mpeg</sourceMimeType>
    <sourceMimeType>video/mp4</sourceMimeType>
    <sourceMimeType>video/quicktime</sourceMimeType>
    <sourceMimeType>video/ogg</sourceMimeType>
    <sourceMimeType>video/x-ms-asf</sourceMimeType>
    <sourceMimeType>video/x-msvideo</sourceMimeType>
    <sourceMimeType>video/flv</sourceMimeType>
    <destinationMimeType>video/webm</destinationMimeType>
    <parameters>
      <parameter name="CommandLineName">ffmpeg-towebm</parameter>
      <parameter name="videoMimeType">video/webm</parameter>
      <parameter name="videoExtension">webm</parameter>
      <parameter name="tmpDirectoryPrefix">convertToWebM</parameter>
    </parameters>
  </converter>
</extension>

The converter contribution depends of an already defined command.

Here we use the generic VideoConversionConverter converter, only the sourceMimeTypes and parameters need to be filled.

Parameters:

  • CommandLineName: the command to use when running this converter (the one defined earlier)
  • videoMimeType: the mime-type of the converted video
  • videoExtension: the extension of the converted video
  • tmpDirectoryPrefix: the tmp directory where the conversion will be done

For instance, the converter to convert to MP4 looks like:

<converter name="convertToMP4" class="org.nuxeo.ecm.platform.video.convert.VideoConversionConverter">
  <sourceMimeType>video/mpeg</sourceMimeType>
  <sourceMimeType>video/webm</sourceMimeType>
  <sourceMimeType>video/quicktime</sourceMimeType>
  <sourceMimeType>video/ogg</sourceMimeType>
  <sourceMimeType>video/x-ms-asf</sourceMimeType>
  <sourceMimeType>video/x-msvideo</sourceMimeType>
  <sourceMimeType>video/flv</sourceMimeType>
  <destinationMimeType>video/mp4</destinationMimeType>
  <parameters>
    <parameter name="CommandLineName">ffmpeg-tomp4</parameter>
    <parameter name="videoMimeType">video/mp4</parameter>
    <parameter name="videoExtension">mp4</parameter>
    <parameter name="tmpDirectoryPrefix">convertToMP4</parameter>
  </parameters>
</converter>

Add a new video conversion

The video conversion contribution depends on an already defined converter. The same converter could be used for more than one video conversion if you wanted different sizes.

<extension target="org.nuxeo.ecm.platform.video.service.VideoService"
  point="videoConversions">
  <videoConversion name="WebM 480p" converter="convertToWebM" height="480"/>
</extension>

Parameters:

  • converter: the already defined converter to use when running this video conversion
  • height: the max height of the video. The width and height of the new video will be computed and passed through the command, where we reference #{width} and #{height}.

Running the video conversion manually

Assuming videoDocument is a Document with the Video facet, to launch the "WebM 480p" video conversion on it:

DocumentModel videoDocument = ...
VideoService videoService = Framework.getService(VideoService.class);
videoService.launchConversion(videoDocument, "WebM 480p");

Running the video conversion automatically

When importing Video, you can configure which video conversions will be run (asynchronously) automatically.

To run the "WebM 480p" video conversion automatically:

<extension target="org.nuxeo.ecm.platform.video.service.VideoService"
  point="automaticVideoConversions">
  <automaticVideoConversion name="WebM 480p" order="10" />
</extension>

Filter video conversions

You can filter the video conversion execution the same way picture conversions are filtered.

Disable or update a default conversion

If you need to disable a default conversion, just override the videoConversions extension point, and add the enabled=false attribute:

<extension point="videoConversions" target="org.nuxeo.ecm.platform.video.service.VideoService">
    <videoConversion enabled=false converter="convertToMP4" height="480" name="MP4 480p" rendition="true"/>
</extension>

In this scenario, the MP4 480p conversion won't be automated anymore and won't be displayed as available conversion in Nuxeo Web UI.

Display a custom conversion in the preview section

The default document view layout of Nuxeo Web UI displays the main file preview (i.e. the binary stored in file:content). To display a specific conversion, you need to edit the view layout by

  • Commenting the default previewer
<!-- comment this section -->
<nuxeo-document-viewer role="widget" document="[[document]]"></nuxeo-document-viewer>
  • Add the nuxeo-document-preview element to fetch a specific rendition.
<nuxeo-card>
  <nuxeo-document-preview document="[[document]]"
  xpath="vid:transcodedVideos/1/content">
  </nuxeo-document-preview>
</nuxeo-card>

The 1 value in the xpath attribute corresponds to the order of the picture conversion in the list of video conversions.

Set security on a specific conversion

Use the same procedure as for picture conversions.

Related How-Tos
Other Related Documentation