NGINX-based VOD Packager

nginx-vod-module

Join the list of organizations using this video packager project.

For live video streaming, please use Media-Framework.

Features

• On-the-fly repackaging of MP4 files to DASH, HDS, HLS, MSS

• Working modes:

  1. Local - serve locally accessible files (local disk/NFS mounted)
  2. Remote - serve files accessible via HTTP using range requests
  3. Mapped - serve files according to a specification encoded in JSON format. The JSON can pulled from a remote server, or read from a local file

• Adaptive bitrate support

• Playlist support (playing several different media files one after the other) - mapped mode only

• Simulated live support (generating a live stream from MP4 files) - mapped mode only

• Fallback support for file not found in local/mapped modes (useful in multi-datacenter environments)

• Video codecs: H264, H265 (DASH/HLS), AV1 (DASH/HLS), VP8 (DASH), VP9 (DASH)

• Audio codecs: AAC, MP3 (HLS/HDS/MSS), AC-3 (DASH/HLS), E-AC-3 (DASH/HLS), VORBIS (DASH), OPUS (DASH), FLAC (HLS), DTS (HLS)

• Captions support -

  Input:

  1. WebVTT
  2. SRT
  3. DFXP/TTML
  4. CAP (Cheetah)

  Output:

  1. DASH - either a single WebVTT or SMPTE-TT segments (configurable)
  2. HLS - segmented WebVTT (m3u8)
  3. MSS - converted to TTML and packaged in fragmented MP4 (no support for styling)

• Audio only/video only files

• Alternative audio renditions - supporting both:

  1. Generation of manifest with different audio renditions, allowing selection on the client side
  2. Muxing together audio and video streams from separate files / tracks - provides the ability to serve different audio renditions of a single video, without the need for any special support on the client side.

• Track selection for multi audio/video MP4 files

• Playback rate change - 0.5x up to 2x (requires libavcodec and libavfilter)

• Source file clipping (only from I-Frame to P-frame)

• Support for variable segment lengths - enabling the player to select the optimal bitrate fast, without the overhead of short segments for the whole duration of the video

• Clipping of MP4 files for progressive download playback

• Thumbnail capture (requires libavcodec) and resize (requires libswscale)

• Volume map (requires libavcodec) - returns a CSV containing the volume level in each interval

• Decryption of CENC-encrypted MP4 files (it is possible to create such files with MP4Box)

• DASH: common encryption (CENC) support

• MSS: PlayReady encryption support

• HLS: Generation of I-frames playlist (EXT-X-I-FRAMES-ONLY)

• HLS: support for AES-128 / SAMPLE-AES encryption

Limitations

• Track selection and playback rate change are not supported in progressive download

• I-frames playlist generation is not supported when encryption is enabled

• Tested on Linux only

Compilation

Dependencies

In general, if you have the dependencies that are required to build nginx, you should be able to build nginx-vod-module. However, some optional features of this module depend on additional packages. The module detects these packages during configure - if a package is missing, the respective feature will be disabled.

The optional features are:

1. Thumbnail capture & volume map - depend on ffmpeg (3.0 or newer)
2. Audio filtering (for changing playback rate / gain) - depends on ffmpeg (3.0 or newer) and also on libfdk_aac. Due to licensing issues, libfdk_aac is not built into kaltura ffmpeg packages
3. Encryption / decryption (DRM / HLS AES) - depends on openssl
4. DFXP captions - depends on libxml2
5. UTF-16 encoded SRT files - depends on iconv

Build

To link statically against nginx, cd to nginx source directory and execute:

./configure --add-module=/path/to/nginx-vod-module
make
make install

To compile as a dynamic module (nginx 1.9.11+), use:

./configure --add-dynamic-module=/path/to/nginx-vod-module

In this case, the load_module directive should be used in nginx.conf in order to load the module.

Optional recommended settings:

1. --with-file-aio - enable asynchronous I/O support, highly recommended, relevant only to local and mapped modes
2. --with-threads (nginx 1.7.11+) - enable asynchronous file open using thread pool (also requires vod_open_file_thread_pool in nginx.conf), relevant only to local and mapped modes
3. --with-cc-opt="-O3 -mpopcnt" - enable additional compiler optimizations (we saw about 8% reduction in the mp4 parse time and frame processing time compared to the nginx default -O)

Debug settings:

1. --with-debug - enable debug messages (also requires passing debug in the error_log directive in nginx.conf).
2. --with-cc-opt="-O0" - disable compiler optimizations (for debugging with gdb)

C Macro Configurations:

1. --with-cc-opt="-DNGX_VOD_MAX_TRACK_COUNT=256 -mavx2" - increase the maximum track count (preferably to multiples of 64). It's recommended to enable vector extensions (AVX2) as well.

Installation

RHEL/CentOS 6/7 RPM

# rpm -ihv http://installrepo.kaltura.org/releases/kaltura-release.noarch.rpm
# yum install kaltura-nginx

Debian/Ubuntu deb package

Ubuntu NOTE: before trying to install kaltura-nginx, you must also make sure the multiverse repo is enabled

For Debian Wheezy [7], Debian Jessie [8], Ubuntu 14.04 and 14.10, add this repo:

# wget -O - http://installrepo.kaltura.org/repo/apt/debian/kaltura-deb-curr.gpg.key|apt-key add -
# echo "deb [arch=amd64] http://installrepo.kaltura.org/repo/apt/debian propus main" > /etc/apt/sources.list.d/kaltura.list

For Ubuntu 16.04, 16.10 add this repo:

# wget -O - http://installrepo.kaltura.org/repo/apt/xenial/kaltura-deb-curr-256.gpg.key|apt-key add -
# echo "deb [arch=amd64] http://installrepo.kaltura.org/repo/apt/xenial propus main" > /etc/apt/sources.list.d/kaltura.list

For Ubuntu 20.04 add this repo:

# wget -O - http://installrepo.kaltura.org/repo/aptn/focal/kaltura-deb-256.gpg.key|apt-key add -
# echo "deb [arch=amd64] http://installrepo.kaltura.org/repo/aptn/focal quasar main" > /etc/apt/sources.list.d/kaltura.list

Then install the kaltura-nginx package:

# apt-get update
# apt-get install kaltura-nginx

If you wish to make use of the following features:

• Thumbnail capture
• Playback rate change - 0.5x up to 2x

You will also need to install the kaltura-ffmpeg (>= 3.1) package.

URL structure

Basic URL structure

The basic structure of an nginx-vod-module URL is: http://<domain>/<location>/<fileuri>/<filename>

Where:

• domain - the domain of the nginx-vod-module server
• location - the location specified in the nginx conf
• fileuri - a URI to the mp4 file:
  • local mode - the full file path is determined according to the root / alias nginx.conf directives
  • mapped mode - the full file path is determined according to the JSON received from the upstream / local file
  • remote mode - the mp4 file is read from upstream in chunks
  • Note: in mapped & remote modes, the URL of the upstream request is http://<upstream>/<location>/<fileuri>?<extraargs> (extraargs is determined by the vod_upstream_extra_args parameter)
• filename - detailed below

Multi URL structure

Multi URLs are used to encode several URLs on a single URL. A multi URL can be used to specify the URLs of several different MP4 files that should be included together in a DASH MPD for example.

The structure of a multi URL is: http://<domain>/<location>/<prefix>,<middle1>,<middle2>,<middle3>,<postfix>.urlset/<filename>

The sample URL above represents 3 URLs:

• http://<domain>/<location>/<prefix><middle1><postfix>/<filename>
• http://<domain>/<location>/<prefix><middle2><postfix>/<filename>
• http://<domain>/<location>/<prefix><middle3><postfix>/<filename>

The suffix .urlset (can be changed using vod_multi_uri_suffix) indicates that the URL should be treated as a multi URL. For example - the URL http://example.com/hls/videos/big_buck_bunny_,6,9,15,00k.mp4.urlset/master.m3u8 will return a manifest containing:

• http://example.com/hls/videos/big_buck_bunny_600k.mp4/index.m3u8
• http://example.com/hls/videos/big_buck_bunny_900k.mp4/index.m3u8
• http://example.com/hls/videos/big_buck_bunny_1500k.mp4/index.m3u8

URL path parameters

The following parameters are supported on the URL path:

• clipFrom - an offset in milliseconds since the beginning of the video, where the generated stream should start. For example, .../clipFrom/10000/... will generate a stream that starts 10 seconds into the video.
• clipTo - an offset in milliseconds since the beginning of the video, where the generated stream should end. For example, .../clipTo/60000/... will generate a stream truncated to 60 seconds.
• tracks - can be used to select specific audio/video tracks. The structure of the parameter is: v<id1>-v<id2>-a<id1>-a<id2>... For example, .../tracks/v1-a1/... will select the first video track and first audio track. The default is to include all tracks.
• shift - can be used to apply a timing shift to one or more streams. The structure of the parameter is: v<vshift>-a<ashift>-s<sshift> For example, .../shift/v100/... will apply a forward shift of 100ms to the video timestamps.

Filename structure

The structure of filename is: <basename>[<seqparams>][<fileparams>][<trackparams>][<langparams>].<extension>

Where:

• basename + extension - the set of options is packager specific (the list below applies to the default settings):
  • dash - manifest.mpd
  • hds - manifest.f4m
  • hls master playlist - master.m3u8
  • hls media playlist - index.m3u8
  • mss - manifest
  • thumb - thumb-<offset>[<resizeparams>].jpg (offset is the thumbnail video offset in milliseconds)
  • volume_map - volume_map.csv
• seqparams - can be used to select specific sequences by id (provided in the mapping JSON), e.g. master-sseq1.m3u8.
• fileparams - can be used to select specific sequences by index when using multi URLs. For example, manifest-f1.mpd will return an MPD only from the first URL.
• trackparams - can be used to select specific audio/video tracks. For example, manifest-a1.f4m will return an F4M containing only the first audio stream of each sequence. The default is to include the first audio and first video tracks of each file. The tracks selected on the file name are AND-ed with the tracks selected with the /tracks/ path parameter. v0/a0 select all video/audio tracks respectively. The a/v parameters can be combined with f/s, e.g. f1-v1-f2-a1 = video1 of file1 + audio1 of file2, f1-f2-v1 = video1 of file1 + video1 of file2.
• langparams - can be used to filter audio tracks/subtitles according to their language (ISO639-3 code). For example, master-leng.m3u8 will return only english audio tracks.
• resizeparams - can be used to resize the returned thumbnail image. For example, thumb-1000-w150-h100.jpg captures a thumbnail 1 second into the video, and resizes it to 150x100. If one of the dimensions is omitted, its value is set so that the resulting image will retain the aspect ratio of the video frame.

Mapping response format

When configured to run in mapped mode, nginx-vod-module issues an HTTP request to a configured upstream server in order to receive the layout of media streams it should generate. The response has to be in JSON format.

This section contains a few simple examples followed by a reference of the supported objects and fields. But first, a couple of definitions:

1. Source Clip - a set of audio and/or video frames (tracks) extracted from a single media file
2. Generator - a component that can generate audio/video frames. Currently, the only supported generator is the silence generator.
3. Filter - a manipulation that can be applied on audio/video frames. The following filters are supported:

• rate (speed) change - applies to both audio and video
• audio volume change
• mix - can be used to merge several audio tracks together, or to merge the audio of source A with the video of source B

4. Clip - the result of applying zero or more filters on a set of source clips
5. Dynamic Clip - a clip whose contents is not known in advance, e.g. targeted ad content
6. Sequence - a set of clips that should be played one after the other.
7. Set - several sequences that play together as an adaptive set, each sequence must have the same number of clips.

Simple mapping

The JSON below maps the request URI to a single MP4 file:

{
	"sequences": [
		{
			"clips": [
				{
					"type": "source",
					"path": "/path/to/video.mp4"
				}
			]
		}
	]
}

When using multi URLs, this is the only allowed JSON pattern. In other words, it is not possible to combine more complex JSONs using multi URL.

Adaptive set

As an alternative to using multi URL, an adaptive set can be defined via JSON:

{
	"sequences": [
		{
			"clips": [
				{
					"type": "source",
					"path": "/path/to/bitrate1.mp4"
				}
			]
		},
		{
			"clips": [
				{
					"type": "source",
					"path": "/path/to/bitrate2.mp4"
				}
			]
		}
	]
}

Playlist

The JSON below will play 35 seconds of video1 followed by 22 seconds of video2:

{
	"durations": [ 35000, 22000 ],
	"sequences": [
		{
			"clips": [
				{
					"type": "source",
					"path": "/path/to/video1.mp4"
				},
				{
					"type": "source",
					"path": "/path/to/video2.mp4"
				}
			]
		}
	]
}

Filters

The JSON below takes video1, plays it at x1.5 and mixes the audio of the result with the audio of video2, after reducing it to 50% volume:

{
	"sequences": [
		{
			"clips": [
				{
					"type": "mixFilter",
					"sources": [
						{
							"type": "rateFilter",
							"rate": 1.5,
							"source": {
								"type": "source",
								"path": "/path/to/video1.mp4"
							}
						},
						{
							"type": "gainFilter",
							"gain": 0.5,
							"source": {
								"type": "source",
								"path": "/path/to/video2.mp4",
								"tracks": "a1"
							}
						}
					]
				}
			]
		}
	]
}

Continuous live

The JSON below is a sample of a continuous live stream (=a live stream in which all videos have exactly the same encoding parameters). In practice, this JSON will have to be generated by some script, since it is time dependent. (see test/playlist.php for a sample implementation)

{
	"playlistType": "live",
	"discontinuity": false,
	"segmentBaseTime": 1451904060000,
	"firstClipTime": 1451917506000,
	"durations": [83000, 83000],
	"sequences": [
		{
			"clips": [
				{
					"type": "source",
					"path": "/path/to/video1.mp4"
				},
				{
					"type":