How to Contribute a New Video Conversion

Let's see how to contribute a new video conversion to convert a video to WebM format (assuming all the needed codecs are installed with FFmpeg).

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

Contributing the Command

Command contribution

<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.

Contributing the Converter

The converter contribution depends of an already defined command.

<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>

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>

Contributing the 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.getLocalService(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>