Javicle - a JSON Video Composition Language

Javicle (JVC for short) is a JSON DSL for audio/video transformations.

Under the hood, it’s all shell commands: ffmpeg, mediainfo and so on.

JVC provides higher-level semantics for working with these lower level tools.

Motivation

I don’t do much video editing, so I’ve never bothered to learn iMovie or any graphical video editor. My editing needs are usually pretty simple, so I bust out ffmpeg and get it done.

But it seems like every time, there is at least one wrinkle in my requirements that requires some deep research into ffmpeg filter arcana and before I know it, the day is done.

I created JVC to make it really easy to do the most common things people usually do to videos: splitting, concatenating, letterboxing, overlaying one video onto another, and so on.

A Quick Example

Suppose you have one video that is five minutes long, and you want to split it into five videos, each one minute long.

With ffmpeg and bash, you might do something like this:

    INCR=60
    for ((i=0;i<300;i=(i+INCR))); do
      ffmpeg -i /tmp/my/source.mp4 -ss ${i} -t $((i+INCR)) /tmp/my/slice_${i}_$((i+INCR)).mp4
    done

With JVC, you’d write this spec file and save it to a file (for example my-spec.jvc):

{
  "assets": [ {"name": "src", "path": "/tmp/my/source.mp4"} ],
  "operations": [{
      "operation": "split",
      "creates": "src_split_files",
      "source": "src",
      "interval": "60"
  }]
}

and then run it like this:

jvc my-spec.jvc

Yes, the JVC is longer, but I think many would agree it is easier to read and maintain.

As the number of media assets and operations grows, hand-crafted shell scripts with magical ffmpeg incantations become ever more inscrutable.

JVC is designed for readability and maintainability. JVC will continue to evolve towards greater coverage of the full capabilities of ffmpeg.

Who is JVC not for?

If you like GUIs, JVC is probably not for you.

JVC is not a replacement for Final Cut Pro or even iMovie.

Who is JVC for?

JVC is for people who like CLIs and automation.

JVC is for people with relatively simple video composition needs (for now), since the range of operations supported is limited.

Requirements

• Java 11
• Maven 3

The first time you run jvc, it will automatically build the JVC jar file from sources, using maven and javac. This takes a little time but only needs to be done once.

Running JVC

Learn more about running jvc and other useful tools.

JVC Concepts

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

Supported Operations

Today, JVC supports several basic operations.

For each operation listed below, the header links to an example from the JVC test suite.

add-silence

Add a silent audio track to a video asset.

concat

Concatenate audio/video assets together into one asset.

ken-burns

Transform still images into video via a fade-pan (aka Ken Burns) effect.

letterbox

Transform a video from one size to another size, maintaining the aspect ratio of the video and adding letterboxes on the sides or top/bottom. Handy for embedding mobile videos into other screen formats.

merge-audio

Merge an audio asset into the audio track of a video asset.

overlay

Overlay one asset onto another.

remove-track

Remove a track from a video asset.

scale

Scale a video asset from one size to another. Scaling can be proportional or anamorphic.

split

Split an audio/video asset into multiple assets of equal time lengths.

trim

Trim audio/video; crop a section of an asset, becomes a new asset.

Complex Example

Here is a long, complex example that uses every operation.

What’s with the name?

A cross between a javelin and an icicle? JSON and a miracle? Something with positive connotations? I really don’t like naming things.