javicle/docs/running.md

Running JVCL

The jvcl Script

The bin/jvcl script is the primary way to transform video assets with JVCL.

Operation-specific scripts

There are other scripts in bin that perform a single operation using command-line arguments. If you need to do a quick operation and don’t want to write a JVCL spec, use one of these tools.

For example, to extract the first 5 seconds of a video:

jtrim /tmp/input-file.mp4 /tmp/output-5s.mp4 0 5

All commands accept a -h / --help option, use this to print usage information:

jscale -h

JVCL Spec Files

A JVCL spec is just a regular JSON file that happens to contain a single JSON object, whose properties are assets and operations.

When you run jvcl on a spec file, it will load the assets, then perform the operations in order.

Learn more about Assets and Operations

Unlike most JSON, comments are allowed in JVCL spec files:

• A line comment starts with // and continue to the end of the line
• A multi-line block syntax starts with /* and ends with */

Writing a JVCL Spec

The easiest way to write a spec is to copy one of the test specs and edit it.

There examples for every JVCL operation.

Executing a JVCL Spec

To execute a spec stored in the file my-spec.json, you would run:

jvcl my-spec.jvcl

or use stdin:

cat my-spec.jvcl | jvcl

Scratch Directory

Output assets will be placed in the scratch directory, unless otherwise specified in the spec file. By default, JVCL will create a new temporary directory to use as the scratch directory. You can set the scratch directory explicitly using the -t or --temp-dir option:

jvcl -t /some/tempdir my-spec.json

Dry Run

Use the -n or --no-exec option to print out the commands that would have been run, but do not actually run anything.

jvcl -n my-spec.json         # will not run any ffmpeg commands

Note that this breaks JVCL operations that require information from any assets created by previous operations: since the command did not actually run, the intermediate asset was never created.

Help

To view a list of all jvcl command-line options, run jvcl -h or jvcl --help

What’s Next?

Learn about Assets and Operations, the core concepts of JVCL.