DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Administrator Manual

Installation

Obvilously, the first step is to install the extension.

Next you should include the static TypoScript template in your preferred template record. With the following TypoScript constants you can define which files should be loaded in the frontend:

plugin.tx_html5mediaelements.settings {
        # Include the built-in jQuery
        includeJquery = 1

        # Include the JavaScript of the plugin
        includeJs = 1

        # Include the CSS file of the plugin
        includeCss = 1
}

Of course you can set the storagePid and the various fluid template paths as well.

Task configuration

If you want to use the automatic conversion with ffmpeg, make sure that ffmpeg and ffprobe are installed on your server. Also make sure that the _cli_scheduler backend user has permission to write to the file storage in which you keep your media files.

Next, create a new scheduler task:

  • Class: Extbase CommandController Task
  • CommandController Command: Html5mediaelements OptimizeMedia: optimizeMedia
  • Don't allow parallel execution!

After saving the new task, new options become available:

  • Set ffmpegPath to the full path of the ffmpeg binary (try which ffmpeg on the terminal)
  • Set ffprobePath to the full path of the ffprobe binary (try which ffprobe on the terminal)
  • The tempPath can probably stay the same
  • If you want to be notified on conversion errors, set errorEmail to your preferred email address
  • If you want to be notified when a conversion was successful, set successEmail to your preferred email address

Notifications

The notification content can be configured with page TSconfig (see also: EXT:html5mediaelements/Configuration/TSconfig/tsconfig.txt):

tx_html5mediaelements {
        # Email notification content
        notification {
                success {
                        subject = Media files converted successfully
                        message (
The following media files have been converted to web-friendly formats:

###MEDIAFILES###

If you want to embed the converted files, just enter the TYPO3 backend.

###SIGNATURE###
)
                        mediafiles = * ###TITLE### (###UID###)
                        signature =
                }
                error {
                        subject = Error while converting media files
                        message (
An error occured while converting the following media files:

###MEDIAFILES###

During the conversion the following error occured:

###ERROR###

###SIGNATURE###
)
                        mediafiles = * ###TITLE### (###UID###)
                        signature =
                }
        }
}

The following markers are available in message:

  • ###SIGNATURE###: Email signature provided with signature option
  • ###MEDIAFILES###: A list of media files that have been converted, each rendered with the mediafiles option

For error messages these extra markers are available:

  • ###ERROR###: Error message
  • ###ERROR_FILE###: File in which the error occured
  • ###ERROR_LINE###: Line in which the error occured

Media encoding configuration

The automatic media conversion is based on a library called PHP Video Toolkit version 2. The library provides various options for the audio, video and image generation. Some of those options can be set in page TSconfig to adjust encoding parameters of the web-friendly media files.

The default configuration looks like this (see also: EXT:html5mediaelements/Configuration/TSconfig/tsconfig.txt):

tx_html5mediaelements {
        # Poster image format
        poster {
                filename = ###NAME###.jpg
                format = Jpeg

                height =
                width =
                quality =
        }

        # Web-friendly audio formats
        audio {
                mp3 {
                        filename = ###NAME###.mp3
                        format = Mp3

                        audio {
                                enabled = 1
                                codec =
                                bitrate =
                                quality =
                                sampleFrequency =
                                channels =
                                volume =
                        }
                }

                ogg {
                        filename = ###NAME###.oga
                        format = Oga
                }
        }

        # Web-friendly video formats
        video {
                mp4 {
                        filename = ###NAME###.mp4
                        format = Mp4

                        audio {
                                enabled = 1
                                codec =
                                bitrate =
                                quality =
                                sampleFrequency =
                                channels =
                                volume =
                        }

                        video {
                                enabled = 1
                                codec =
                                height =
                                width =
                                aspectRatio =
                                frameRate =
                                maxFrames =
                                bitrate =
                                pixelFormat =
                                quality =
                                h264 {
                                        preset =
                                        tune =
                                        profile = main
                                }
                        }
                }
                webm {
                        filename = ###NAME###.webm
                        format = Webm
                }
                ogv {
                        filename = ###NAME###.ogv
                        format = Ogg
                }
        }
}

All options except for the filename can be left out, as you can see for ogg, webm and ogv. Just to be safe, you can define the file format explicitly with the format option, but if you leave it out, the library will decide based on the provided file extension.

The filename option allows the following markers:

  • ###NAME###: Original filename without the file extension
  • ###EXTENSION###: The file extension without leading dot
  • ###UID###: The UID of the FAL file record
  • ###SHA1###: The SHA1 hash of the original file
  • ###HASH###: The FAL identifier hash of the file
  • ###UNIQUE###: A MD5-hashed (semi-)unique string to obfuscate the file name

All other options correspond directly to the options of the library:

Image options

poster.

  • height: ImageFormat::setVideoDimensions()
  • width: ImageFormat::setVideoDimensions()
  • quality: ImageFormat::setVideoQuality()

Audio options

audio.

  • enabled: AudioFormat::enableAudio() and AudioFormat::disableAudio()
  • codec: AudioFormat::setAudioCodec()
  • bitrate: AudioFormat::setAudioBitrate()
  • quality: AudioFormat::setAudioQuality()
  • sampleFrequency: AudioFormat::setAudioSampleFrequency()
  • channels: AudioFormat::setAudioChannels()
  • volume: AudioFormat::setVolume()

Video options

video.

  • enabled: VideoFormat::enableVideo() and VideoFormat::disableVideo()
  • codec: VideoFormat::setVideoCodec()
  • height: VideoFormat::setVideoDimensions()
  • width: VideoFormat::setVideoDimensions()
  • aspectRatio: VideoFormat::setVideoAspectRatio()
  • frameRate: VideoFormat::setVideoFrameRate()
  • maxFrames: VideoFormat::setVideoMaxFrames()
  • bitrate: VideoFormat::setVideoBitrate()
  • pixelFormat: VideoFormat::setVideoPixelFormat()
  • quality: VideoFormat::setVideoQuality()
  • h264.preset: VideoFormat_H264::setH264Preset()
  • h264.tune: VideoFormat_H264::setH264Tune()
  • h264.profile: VideoFormat_H264::setH264Profile()

Adding new encoding configurations

If you want to extend the default configuration to include other formats, the backend forms should be adjusted accordingly by using page TSconfig:

# TCA adjustments for media formats
TCEFORM.tx_html5mediaelements_domain_model_mediaoptimized.format.types {
        1.addItems {
                newVideoFormat = My new video format
        }

        2.addItems {
                newAudioFormat = My new audio format
        }
}