Skip to content

Latest commit

 

History

History
397 lines (243 loc) · 11.3 KB

README.md

File metadata and controls

397 lines (243 loc) · 11.3 KB
Raw

Build Status

Video Processing CLI

A command line tool that hides the complexity of ffmpeg to produce a Dynamic Adaptive Streaming over HTTP (DASH) playlist from a video source.

features

  • Extract video metadata
  • Generate thumbnail (or cover image) from a video file
  • Generate low resolution version of a video file
  • Generate a DASH manifest for video streaming
  • Generate a HLS playlist for video streaming

supported Operating Systems

  • Windows
  • Debian based Linux distributions, e.g. Debian, Ubuntu
  • MacOS (on Intel)

The binaries are generated for 64 bit version of the OS

Getting started

Installation

Requirements

In order to use the video-processing-cli you need

The binaries can be added to the shell/command line PATH or in a bin folder. The bin folder must be in the same working directory where the video-processing-cli will be executed.

Grab the video-processing-cli binary

Prebuilt binaries are available for Windows, MacOS and Linux. All binaries are for 64bit architecture.

Binaries are automatically built for each tagged release. Download the latest master binaries

Alternatively a docker image is available, see Usage via Docker.

Download FFMPEG and Shaka Packager executables

Download or install FFMPEG and Shaka Packager on your system. Installation procedure may vary depending on the Operating System, but you can download a standalone binary from https://ffmpeg.org/download.html. Once downloaded place the binaries in the bin directory.

The Video Processing Cli can download binaries from a mirror site by executing

$ video-processing-cli fetch:binaries

This will attempt to download a standalone, statically linked, version of FFMPEG, FFPROBE and Shaka Packager for your operating system. The downloaded version requires a 64bit architecture and is not compatible with ARM or Apple Silicon.

Usage

via Executable file

Once grabbed the binary file, and saved as video-processing-cli, you can run it on the shell/command prompt

$ video-processing-cli <command>

where <command> is one of the available commands.

To get the help message with all the available commands, use

$ video-processing-cli --help

If you already know the <command>, but not its parameters you could use

$ video-processing-cli <command> --help
# e.g. video-processing-cli details --help

and the list of available arguments and options for the specified command will be listed

via Docker image

A packaged version, in the form of a Docker image, is available. The image is hosted at docker.klink.asia

docker pull docker.klink.asia/images/video-processing-cli:latest

The image is configured with the video-processing-cli executable as the entry point. The working directory is /video-processing-cli.

Running

docker run --rm docker.klink.asia/images/video-processing-cli:latest

will output the help message.

To execute the other commands mount a volume with your videos and use one of the available commands

docker run --rm -v "./source:/video-processing-cli/videos" \ 
                   docker.klink.asia/images/video-processing-cli:latest <command>

Available commands

details (or info)

Extract information about a video file. Extracted information includes codecs, resolution, duration,...

details <file>

The command is also available with the alias info.

Arguments

  • file the path of the video file

Output

The output will be written on the standard output in a multi-line fashion

Errors

In case of processing error a message will be written on standard error.

A typical error might be "File not found" if the specified file path contains an error.

Example

$ video-processing-cli details video.mp4

The output is similar to

video.mp4
QuickTime / MOV (mov,mp4,m4a,3gp,3g2,mj2)
duration 0:00:28.148300
size 60.267055 Mibyte
bitrate 17.960469 Mbit/s
video h264 1920x1080
audio aac 48 KHz

thumbnail

Extract information about a video file. Extracted information includes codecs, resolution, duration,...

thumbnail <file> <output_path>

Arguments

  • file the video file path
  • output_path the existing folder in which the thumbnail will be saved

Options

  • --format <format> the format of the thumbnail, available formats are png and jpg
  • --out <name> the name (with extension) of the file thumbnail

Output

The output will be written, by default, in a file named with the original video name and with extension png.

Errors

In case of processing error a message will be written on standard error.

Example

$ video-processing-cli thumbnail ./videos/video.mp4 ./videos/covers/

The output is a file called video.png in the ./videos/covers/ folder.

process

Generates a DASH manifest for "streaming" a video file.

While generating the playlist it also generates different downscaled versions of the original video files. This downscaled versions will be used by the player to select the appropriate stream to play. More information on the processing can be found in the Video Processing section.

The original video file will not be touched or moved.

process <file> <output_path>

Arguments

  • file the video file path
  • output_path the existing folder in which the artifacts will be saved

Output

The output is a set of video files whose name is the same of the original video, but suffixed with the frame height and a mpd file named the same as the source video.

Errors

In case of processing error a message will be written on standard error.

Example

$ video-processing-cli process ./videos/video.mp4 ./videos/

fetch:binaries

Download the statically linked binaries for FFMPEG and Shaka Packager.

Output

Binary files will be saved in ./bin

Errors

In case of processing error a message will be written on standard error.

Example

$ video-processing-cli fetch:binaries

transcode

Transcode a video to a different format/resolution according to the selected preset.

The original video file will not be touched or moved.

transcode [--preset auto] <file> [output_path]

Arguments

  • file the video file path
  • output_path the existing folder in which the transcoded video will be saved

Options

  • -p, --preset [name] the preset to use, default auto

Output

The output is a video file, whose name is the same of the original video suffixed with the name of the preset, e.g. ./videos/video-720.mp4.

Errors

In case of processing error a message will be written on standard error.

Example

$ video-processing-cli transcode -p V720 ./videos/video.mp4 ./videos/

pack

Pack different video resolutions into a DASH playlist for streaming.

pack [--name mpd_name] [--out folder] <files>

Arguments

  • files the video files to use for playback

Options

  • -o, --out [path] the folder in which the playlist and elaborated videos should be saved
  • -n, --name [name] the name to use for the MPD playlist file

Output

The output is a MPD file, followed by a variant numbers of mp4 files containing the splitted video and audio tracks, that are referenced for streaming. The original video files will not be touched or moved.

Errors

In case of processing error a message will be written on standard error.

Example

$ video-processing-cli pack --name video ./videos/video-360.mp4 ./videos/video-540.mp4

Video Processing

The main aim of the processing pipeline is to generate a manifest for a video player, respecting the DASH and HLS specifications, to enable the playback of the video file on different devices and according to the available bandwidth.

The first part of the pipeline take the video file and produce downscaled versions of it. The number of downscaled versions depends on the original resolution of the video source.

In general the output are 1080p (Full HD), 720p (HD Ready), 540p and 360p for mobile with constrained bandwidth. In case the video source is not Full HD, it will not be upscaled and the maximum resolution for the video will be the same of the closest preset, e.g. if the video has a 840px height, the final height will be 720px. The aspect ratio is respected.

After the conversion the DASH playlist manifest is generated with a 3 seconds segment duration, so the player can switch the video from one resolution to the other every 3 seconds.

In the DASH playlist audio and video streams are separated.

Development

The development of the video-processing-cli is done in NodeJS. The dependencies are managed via NPM.

Before adding some code pull in all the dependencies

$ npm install

Building

the cross platform binary

Distributable binary files are generated via PKG.

To generate an executable file for Windows, Linux and MacOS use

npm run production

This will generate three executables in the /dist folder. Each one will have a suffix based on the operating system it targets.

the Docker image

You can build the Docker image via

docker build -t video-processing-cli .

The image is built via a multi-stage build, therefore Docker >= 17.05 is required.

Running unit tests

To prevent regressions in some areas of the code, we use unit tests based on Jest. Everytime you change something is encouraged to execute (and complement) the unit tests.

You can run unit tests in two ways: all the test suite or in watch mode based on changed files.

To run all the unit tests execute

npm run test

To continuously run the unit tests based on changed files execute

npm run test:watch

Contributing

Thank you for considering contributing to the Video Processing CLI!

The contribution guide is not available yet, but in the meantime you can still submit Pull Requests.

License

This project is licensed under the MIT license, see LICENSE.txt.

Credits

The video used in the tests is Aerial shot of mountain and ocean