![None](https://img.shields.io/static/v1?label=UI&message=none&color=lightgrey)

This extension provides two so-called "translators" for the video conversion processes

* VideoOrImageDimensionExceptionTranslator - simply throws an exception when you try to download a video in a bigger resolution than is provided by the video file (as the download formats are not filtered based on resolution).
* VideoDimensionCroppingTranslator - calculates how a video needs to be cropped when the aspect ratio of the source- and target-dimensions are different (e.g. 16:9 to 2:3). Note that this removes image material (either top & bottom or left & right, depending on which way you're going). This may be desirable for certain social media formats.


[MINITOC]


## Properties

To be configured in {home}/appserver/conf/custom.properties

##### videoDimensionTranslator.license
> type: String, **required: yes**, default: -

The license key for the plugin (product: videoDimensionTranslator), provided by *brix*.

## Setup

in {home}/appserver/spring/conversionProcessDefinitions.xml

#### VideoOrImageDimensionExceptionTranslator

Available for both video and image downloads, use this as the first bean in the `processList`

```xml
<bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStep">
  <property name="conversionProcessExecutorName" value="variable-modification"/>
  <property name="parameters">
	<set>
	  <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
		<property name="parameterName" value="TargetVariable"/>
		<property name="parameterValue" value="dimensionExceptionDummy"/>
	  </bean>
	  <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
		<property name="parameterName" value="Expression"/>
		<property name="parameterValue" value="$translator[VideoOrImageDimensionExceptionTranslator:]"/>
	  </bean>
	</set>
  </property>
</bean>
```



#### VideoDimensionCroppingTranslator

In `DownloadVideo`, add an option for cropping in the `parameterList`:

```xml
<bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDefinitionParameter">
	<!-- video cropping -->
	<property name="identifier" value="videoCropping"/>
	<property name="defaultValue" value="keepOriginal"/>
	<property name="description" value="Choose if the video should be cropped to the specified dimensions"/>
	<property name="label" value="Video Cropping"/>
	<property name="allowedValues">
		<list>
			<value>crop</value>
			<value>keepOriginal</value>
		</list>
	</property>
</bean>
```

Replace the existing `parseEmptyVideoSize` with this one:

```xml
  <bean id="parseEmptyVideoSize" class="com.celum.imagine.conversion.processing.definition.ConversionProcessStep">
	<property name="conversionProcessExecutorName" value="variable-modification"/>
	<property name="parameters">
	  <set>
		<bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
		  <property name="parameterName" value="TargetVariable"/>
		  <property name="parameterValue" value="ffmpegResizeParameter"/>
		</bean>
		<bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
		  <property name="parameterName" value="Expression"/>
		  <property name="parameterValue" value="$translator[VideoDimensionCroppingTranslator:]"/>
		</bean>
	  </set>
	</property>
  </bean>
```

Now you can set a video download format to use "crop" where desired (needs both width and height to be set).

## Compatibility Matrix

| Video Dimension Translator | CELUM (min. version)  |
| ---------------- | ------ |
| 1.0 - 1.2      | 6.8  |

## Release Notes

#### 1.0
> Release: 2021-05-26

Initial Version

#### 1.1

> Release: 2021-05-28

Added VideoDimensionCroppingTranslator

#### 1.2

> Release: 2021-06-19

Include the video downscaling patch when not in crop-mode

#### 1.3

> Released: 2021-08-02

Make the ExceptionTranslator available for images as well

(breaking: now called VideoOrImageDimensionExceptionTranslator)