test-engine-live-tools
Small tools and scripts for the EBU test engine platform. These allow for DASH-ing and encoding a live stream.
Installation
The easiest way to install is to use the npm
package. This will give you the latest released version and install all
dependencies (except ffmpeg and MP4Box, you need to provide these yourself):
# npm install test-engine-live-tools
If you wish to use a different version from the Git repository you have to clone the code and install the dependencies using npm. Also, be sure to provide your own MP4Box and ffmpeg binaries, they are not included.
# git clone https://github.com/ebu/test-engine-live-tools.git
# cd test-engine-live-tools
# npm install
Usage
In general, the tool operates by looping an MPEG-2 Transport Stream and providing that to ffmpeg using the segment muxer.
The generated segments are picked up and packaged/fragmented using MP4Box. After all segments for the desired representations
are available they are DASH-ed by MP4Box using the --dash-ctx
option. This generates the MPD for the live stream and keeps
it updated.
A command-line utility is included which allows you to easily stream from the command-line. Usage:
# bin/live-stream [-c config_file] input_file
The config_file
is optional and allows you to create custom settings for your live stream without having to change anything
in the sources. The input_file
is mandatory and it is required that this is currently muxed as a MPEG-2 Transport Stream for
easy looping of the source material. The contents of the file can be either MPEG-2 video/audio or H264/AAC, or most likely
anything else that ffmpeg can extract from a MPEG-2 TS container.
Using different sources
Instead of using a looped MPEG-2 TS file directly, it is also possible to read from other input sources. By specifying an input source using a URL with a protocol, this will be directly passed to ffmpeg to read from that source. This way you can for example ingest video using UDP transport. Example usage:
# bin/live-stream udp://192.168.0.10:1234
In theory any transport protocol supported by your version of ffmpeg is allowed.
Configuration
The default configuration generates one video representation and one audio representation. See lib/config.js
for details.
All parameter configuration is listed as an array of arguments which NodeJS understands. Custom configuration can be created
by creating a valid JSON file containing an object that overrides values of the default configuration. The complete default configuration is:
segmentDir: '/tmp/dash_segment_input_dir' outputDir: '/tmp/dash_output_dir' mp4box: 'MP4Box' ffmpeg: 'ffmpeg' encoding: commandPrefix: '-re' '-i' '-' '-threads' '0' '-y' representations: audio: '-map' '0:1' '-vn' '-acodec' 'aac' '-strict' '-2' '-ar' '48000' '-ac' '2' '-f' 'segment' '-segment_time' '4' '-segment_format' 'mpegts' video: '-map' '0:0' '-vcodec' 'libx264' '-vprofile' 'baseline' '-preset' 'veryfast' '-s' '640x360' '-vb' '512k' '-bufsize' '1024k' '-maxrate' '512k' '-level' '31' '-keyint_min' '25' '-g' '25' '-sc_threshold' '0' '-an' '-bsf' 'h264_mp4toannexb' '-flags' '-global_header' '-f' 'segment' '-segment_time' '4' '-segment_format' 'mpegts' packaging: mp4box_opts: '-dash-ctx' '/tmp/dash_output_dir/dash-live.txt' '-dash' '4000' '-rap' '-ast-offset' '12' '-no-frags-default' '-bs-switching' 'no' '-min-buffer' '4000' '-url-template' '-time-shift' '1800' '-mpd-title' 'MPEG-DASH live stream' '-mpd-info-url' 'http://ebu.io/' '-segment-name' 'live_$RepresentationID$_' '-out' '/tmp/dash_output_dir/live' '-dynamic' '-subsegs-per-sidx' '-1'
You can use this as a basis for your own configuration. Both the ffmpeg command and MP4Box commands are generated
using this configuration. You can add extra representations by overriding the encoding
object.
Please not that some options are required to be able to create a valid live stream. For example: it is required that
we read from stdin using ffmpeg, so -i -
is required. Also it is preferred to read realtime, so -re
is also needed.
The full ffmpeg command is generated by concatenating encoding.commandPrefix
with the configurations in
encoding.represenations
. Output files will be automatically added and you should not specify those yourself.
More example configuration will be added add a later stage.
Caveats / pitfalls
Live streaming using MPEG-DASH is not always easy. To make sure that you are compatible with most DASH clients take extra care to make sure you're always generating closed GOPs, fixed segment durations and constant bit rates and that timing over segments is continuous and identical across representations. The default configuration should do just that, but be sure to keep this in mind.
Requirements
- NodeJS 0.10.x / npm
- ffmpeg binary compiled to taste (recommended: 2.3 or higher)
- MP4Box binary compiled to taste (recommended: r5400 or newer)
License
Available under the BSD 3-clause license.