diff --git a/README.md b/README.md index d264a17..abf7e83 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Javicle - a JSON Video Composition Language -JVCL (pronounced "Javicle") is a JSON DSL for audio/video transformations. +JVC (pronounced "Javicle") is a JSON DSL for audio/video transformations. Under the hood, it's all shell commands: `ffmpeg`, `mediainfo` and so on. -JVCL provides higher-level semantics for working with these lower level tools. +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 @@ -15,7 +15,7 @@ that requires some deep research into [ffmpeg filter arcana](https://ffmpeg.org/ffmpeg-filters.html) and before I know it, the day is done. -I created JVCL to make it really easy to do the most common things people +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. @@ -30,7 +30,7 @@ With ffmpeg and bash, you might do something like this: ffmpeg -i /tmp/my/source.mp4 -ss ${i} -t $((i+INCR)) /tmp/my/slice_${i}_$((i+INCR)).mp4 done ``` -With JVCL, you'd write this spec file and save it to a file +With JVC, you'd write this spec file and save it to a file (for example `my-spec.jvc`): ```json { @@ -45,47 +45,47 @@ With JVCL, you'd write this spec file and save it to a file ``` and then run it like this: ```shell script -jvcl my-spec.jvc +jvc my-spec.jvc ``` -Yes, the JVCL is longer, but I think many would agree it is easier to read +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.** -JVCL is designed for readability and maintainability. JVCL will continue to +JVC is designed for readability and maintainability. JVC will continue to evolve towards greater coverage of the full capabilities of ffmpeg. -# Who is JVCL not for? -If you like GUIs, JVCL is probably not for you. +# Who is JVC not for? +If you like GUIs, JVC is probably not for you. -JVCL is not a replacement for Final Cut Pro or even iMovie. +JVC is not a replacement for Final Cut Pro or even iMovie. -# Who is JVCL for? -JVCL is for people who like CLIs and automation. +# Who is JVC for? +JVC is for people who like CLIs and automation. -JVCL is for people with relatively simple video composition needs (for now), +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 `jvcl`, it will automatically build the JVCL jar file +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 JVCL -Learn more about [running `jvcl`](docs/running.md) and other useful tools. +# Running JVC +Learn more about [running `jvc`](docs/running.md) and other useful tools. -# JVCL Concepts +# JVC Concepts Learn about [Assets and Operations](docs/concepts.md), the core concepts -of JVCL. +of JVC. # Supported Operations -Today, JVCL supports several basic operations. +Today, JVC supports several basic operations. -For each operation listed below, the header links to an example from the JVCL +For each operation listed below, the header links to an example from the JVC test suite. ### [add-silence](src/test/resources/tests/test_add_silence.jvc) diff --git a/bin/jaddsilence b/bin/jaddsilence index 7cdd4b0..7a83271 100755 --- a/bin/jaddsilence +++ b/bin/jaddsilence @@ -13,7 +13,7 @@ # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -. "${SCRIPT_DIR}"/jvcl_common +. "${SCRIPT_DIR}"/jvc_common IN_FILE="${1?no video-file provided}" OUT_FILE="${2?no out-file provided}" @@ -38,4 +38,4 @@ echo " } ] } -" | "${SCRIPT_DIR}"/jvcl ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc ${JVC_OPTIONS} diff --git a/bin/jconcat b/bin/jconcat index f7a4815..93a42a0 100755 --- a/bin/jconcat +++ b/bin/jconcat @@ -13,7 +13,7 @@ # Shell wildcards will match files in non-deterministic order, meaning that # your combined file will be assembled out of order. # -# If you are combining files that were split with `jvcl` (or `jsplit`), then +# If you are combining files that were split with `jvc` (or `jsplit`), then # sorting them by time (oldest first) is sufficient. # # For example, do this: @@ -26,7 +26,7 @@ # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -. "${SCRIPT_DIR}"/jvcl_common +. "${SCRIPT_DIR}"/jvc_common OUT_FILE="${1?no out-file provided}" shift @@ -63,4 +63,4 @@ done) } ] } -" | "${SCRIPT_DIR}"/jvcl -z ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc -z ${JVC_OPTIONS} diff --git a/bin/jletterbox b/bin/jletterbox index 22fcb8a..50ab80c 100755 --- a/bin/jletterbox +++ b/bin/jletterbox @@ -16,7 +16,7 @@ # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -. "${SCRIPT_DIR}"/jvcl_common +. "${SCRIPT_DIR}"/jvc_common IN_FILE="${1?no in-file provided}" OUT_FILE="${2?no out-file provided}" @@ -43,4 +43,4 @@ echo " } ] } -" | "${SCRIPT_DIR}"/jvcl ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc ${JVC_OPTIONS} diff --git a/bin/jmergeaudio b/bin/jmergeaudio index daa01e9..2d065e4 100755 --- a/bin/jmergeaudio +++ b/bin/jmergeaudio @@ -14,7 +14,7 @@ # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -. "${SCRIPT_DIR}"/jvcl_common +. "${SCRIPT_DIR}"/jvc_common VIDEO_FILE="${1?no video-file provided}" AUDIO_FILE="${2?no audio-file provided}" @@ -40,4 +40,4 @@ echo " } ] } -" | "${SCRIPT_DIR}"/jvcl ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc ${JVC_OPTIONS} diff --git a/bin/jrmtrack b/bin/jrmtrack index bc8b2a2..890168d 100755 --- a/bin/jrmtrack +++ b/bin/jrmtrack @@ -14,7 +14,7 @@ # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -. "${SCRIPT_DIR}"/jvcl_common +. "${SCRIPT_DIR}"/jvc_common IN_FILE="${1?no in-file provided}" OUT_FILE="${2?no out-file provided}" @@ -41,4 +41,4 @@ echo " } ] } -" | "${SCRIPT_DIR}"/jvcl ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc ${JVC_OPTIONS} diff --git a/bin/jscale b/bin/jscale index 42ba6cb..4357e84 100755 --- a/bin/jscale +++ b/bin/jscale @@ -16,7 +16,7 @@ # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -. "${SCRIPT_DIR}"/jvcl_common +. "${SCRIPT_DIR}"/jvc_common IN_FILE="${1?no in-file provided}" OUT_FILE="${2?no out-file provided}" @@ -43,7 +43,7 @@ if [[ -z "${HEIGHT}" ]] ; then } ] } -" | "${SCRIPT_DIR}"/jvcl ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc ${JVC_OPTIONS} else echo " { @@ -63,5 +63,5 @@ else } ] } -" | "${SCRIPT_DIR}"/jvcl ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc ${JVC_OPTIONS} fi \ No newline at end of file diff --git a/bin/jsplit b/bin/jsplit index f7bfc64..4a79cd1 100755 --- a/bin/jsplit +++ b/bin/jsplit @@ -14,7 +14,7 @@ # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -. "${SCRIPT_DIR}"/jvcl_common +. "${SCRIPT_DIR}"/jvc_common IN_FILE="${1?no in-file provided}" OUT_DIR="${2?no out-dir provided}" @@ -46,4 +46,4 @@ echo " } ] } -" | "${SCRIPT_DIR}"/jvcl ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc ${JVC_OPTIONS} diff --git a/bin/jtrim b/bin/jtrim index 1ac969e..bdae897 100755 --- a/bin/jtrim +++ b/bin/jtrim @@ -13,7 +13,7 @@ # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -. "${SCRIPT_DIR}"/jvcl_common +. "${SCRIPT_DIR}"/jvc_common IN_FILE="${1?no in-file provided}" OUT_FILE="${2?no out-file provided}" @@ -38,4 +38,4 @@ echo " } ] } -" | "${SCRIPT_DIR}"/jvcl ${JVCL_OPTIONS} +" | "${SCRIPT_DIR}"/jvc ${JVC_OPTIONS} diff --git a/bin/jvcl b/bin/jvc similarity index 58% rename from bin/jvcl rename to bin/jvc index bf962a2..1872e46 100755 --- a/bin/jvcl +++ b/bin/jvc @@ -1,30 +1,30 @@ #!/bin/bash # -# Run JVCL on a spec +# Run JVC on a spec # # Usage: # -# jvcl [-t temp-dir] [-n] spec-file +# jvc [-t temp-dir] [-n] spec-file # -# spec-file : the JVCL to run. If omitted, read a spec from stdin +# spec-file : the JVC to run. If omitted, read a spec from stdin # -# -t temp-dir : where to write generated assets. If omitted, jvcl will +# -t temp-dir : where to write generated assets. If omitted, jvc will # create a new temporary directory # # -n : print commands that would have been run, but don't # actually run anything # -# Note: If the JVCL jar does not exist, it will be built from source. +# Note: If the JVC jar does not exist, it will be built from source. # The first time you run it, it might take a long time to start up. # SCRIPT="${0}" SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)" -JVCL_SKIP_ENV_VAR_HELP=1 -. "${SCRIPT_DIR}"/jvcl_common +JVC_SKIP_ENV_VAR_HELP=1 +. "${SCRIPT_DIR}"/jvc_common DEBUG="" -if [[ -n "${JVCL_DEBUG}" ]] ; then +if [[ -n "${JVC_DEBUG}" ]] ; then DEBUG="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005" fi -java -cp "${JVCL_JAR}" ${DEBUG} jvcl.main.Jvcl "${@}" +java -cp "${JVC_JAR}" ${DEBUG} jvc.main.Jvc "${@}" diff --git a/bin/jvcl_common b/bin/jvc_common similarity index 63% rename from bin/jvcl_common rename to bin/jvc_common index 2593323..2aad1cb 100755 --- a/bin/jvcl_common +++ b/bin/jvc_common @@ -27,13 +27,13 @@ function handle_help_request() { break fi done <"${1}" - if [[ -z "${JVCL_SKIP_ENV_VAR_HELP}" ]] ; then + if [[ -z "${JVC_SKIP_ENV_VAR_HELP}" ]] ; then echo "# Environment Variables # -# JVCL_SCRATCH_DIR : Use this as the scratch directory +# JVC_SCRATCH_DIR : Use this as the scratch directory # Default is to create a new temp directory # -# JVCL_NO_EXEC : If set to anything, print the commands that would +# JVC_NO_EXEC : If set to anything, print the commands that would # have run but do not execute anything # " @@ -53,41 +53,41 @@ elif [[ ${JAVA_VERSION} -lt 11 ]] ; then die "Java 11 (or higher) not installed (java -version check failed)" fi -JVCL_DIR="$(cd "$(dirname "${0}")"/.. && pwd)" -JVCL_JAR="$(find "${JVCL_DIR}"/target -type f -name "jvcl-*-prod.jar" | head -1)" -if [[ -z "${JVCL_JAR}" ]] ; then +JVC_DIR="$(cd "$(dirname "${0}")"/.. && pwd)" +JVC_JAR="$(find "${JVC_DIR}"/target -type f -name "jvc-*-prod.jar" | head -1)" +if [[ -z "${JVC_JAR}" ]] ; then # Ensure maven is installed if [[ -z "$(which mvn)" ]] ; then - die "Maven not installed (mvn command not found on PATH), cannot build JVCL jar" + die "Maven not installed (mvn command not found on PATH), cannot build JVC jar" fi # Build and install utility library - pushd "${JVCL_DIR}"/utils/cobbzilla-utils || die "Error changing directories to ${JVCL_DIR}/utils/cobbzilla-utils" + pushd "${JVC_DIR}"/utils/cobbzilla-utils || die "Error changing directories to ${JVC_DIR}/utils/cobbzilla-utils" mvn -DskipTests=true clean install || die "Error building cobbzilla-utils library" popd || die "popd error" - # Build jvcl uberjar - pushd "${JVCL_DIR}" || die "Error changing directories to ${JVCL_DIR}" - mvn -DskipTests=true -Puberjar clean package || die "Error building JVCL jar" + # Build jvc uberjar + pushd "${JVC_DIR}" || die "Error changing directories to ${JVC_DIR}" + mvn -DskipTests=true -Puberjar clean package || die "Error building JVC jar" popd || die "popd error" - JVCL_JAR="$(find "${JVCL_DIR}"/target -type f -name "jvcl-*-prod.jar" | head -1)" - if [[ -z "${JVCL_JAR}" ]] ; then - die "No JVCL jar file found after successful build" + JVC_JAR="$(find "${JVC_DIR}"/target -type f -name "jvc-*-prod.jar" | head -1)" + if [[ -z "${JVC_JAR}" ]] ; then + die "No JVC jar file found after successful build" fi fi SCRATCH_DIR="" NO_EXEC="" -if [[ -z "${JVCL_SKIP_ENV_VAR_HELP}" ]] ; then - if [[ -n "${JVCL_SCRATCH_DIR}" ]] ; then - SCRATCH_DIR="--temp-dir ${JVCL_SCRATCH_DIR}" +if [[ -z "${JVC_SKIP_ENV_VAR_HELP}" ]] ; then + if [[ -n "${JVC_SCRATCH_DIR}" ]] ; then + SCRATCH_DIR="--temp-dir ${JVC_SCRATCH_DIR}" fi - if [[ -n "${JVCL_NO_EXEC}" ]] ; then + if [[ -n "${JVC_NO_EXEC}" ]] ; then NO_EXEC="--no-exec" fi fi -JVCL_OPTIONS="${SCRATCH_DIR} ${NO_EXEC}" +JVC_OPTIONS="${SCRATCH_DIR} ${NO_EXEC}" handle_help_request "${0}" "${1}" diff --git a/docs/complex_example.md b/docs/complex_example.md index 2a2d916..13325b0 100644 --- a/docs/complex_example.md +++ b/docs/complex_example.md @@ -2,13 +2,13 @@ Here is a complex example using multiple assets and operations. Note that comments, which are not usually legal in JSON, are allowed in -JVCL files. +JVC files. If you have other JSON-aware tools that need to read JVLC files, you may not want to use this comment syntax. The `asset` and `operation` JSON objects also support a `comment` field, which can be used as well. -Doug C: I promise these will always be just comments; jvcl will never +Doug C: I promise these will always be just comments; jvc will never use [comments as parsing directives or otherwise break interoperability](https://web.archive.org/web/20120507155137/https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) (note: disable javascript to view this link) ```js diff --git a/docs/concepts.md b/docs/concepts.md index 85ecb71..bf7aaca 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,12 +1,12 @@ # Concepts -In JVCL the main concepts are assets and operations. +In JVC the main concepts are assets and operations. ## Assets Assets are your media files: generally image, audio and video files. All assets have a name and a path. -Input assets are defined using the `assets` array of a JVCL spec. +Input assets are defined using the `assets` array of a JVC spec. For input assets, the path can be a file or a URL. URL-based assets will be downloaded to the scratch directory. This can be overridden using the `dest` property on the asset. diff --git a/docs/running.md b/docs/running.md index 5f58962..bb8e368 100644 --- a/docs/running.md +++ b/docs/running.md @@ -1,12 +1,12 @@ -# Running JVCL +# Running JVC -## The `jvcl` Script -The `bin/jvcl` script is the primary way to transform video assets with JVCL. +## The `jvc` Script +The `bin/jvc` script is the primary way to transform video assets with JVC. ## Operation-specific scripts There are other scripts in [`bin`](../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. +a JVC spec, use one of these tools. For example, to extract the first 5 seconds of a video: ```shell script @@ -18,65 +18,65 @@ All commands accept a `-h` / `--help` option, use this to print usage informatio jscale -h ``` -## JVCL Spec Files -A JVCL spec is just a regular JSON file that happens to contain a single JSON object, +## JVC Spec Files +A JVC 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. +When you run `jvc` on a spec file, it will load the `assets`, then perform the `operations` in order. Learn more about [Assets and Operations](concepts.md) -Unlike most JSON, comments *are* allowed in JVCL spec files: +Unlike most JSON, comments *are* allowed in JVC spec files: * A line comment starts with `//` and continue to the end of the line * A multi-line block starts with `/*` and ends with `*/` -## Writing a JVCL Spec +## Writing a JVC Spec The easiest way to write a spec is to copy one of the [test specs](../src/test/resources/tests) and edit it. -There examples for every JVCL operation. +There examples for every JVC operation. -## Executing a JVCL Spec +## Executing a JVC Spec To execute a spec stored in the file `my-spec.json`, you would run: ```shell script -jvcl my-spec.jvc +jvc my-spec.jvc ``` or use stdin: ```shell script -cat my-spec.jvc | jvcl +cat my-spec.jvc | jvc ``` ## Command Line Options #### 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 +in the spec file. By default, JVC 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: ```shell script -jvcl -t /some/tempdir my-spec.json +jvc -t /some/tempdir my-spec.json ``` When using the other tools in `bin`, you can set the scratch directory via the -`JVCL_SCRATCH_DIR` environment variable. If the `JVCL_SCRATCH_DIR` references a +`JVC_SCRATCH_DIR` environment variable. If the `JVC_SCRATCH_DIR` references a directory that does not exist, it will be created. #### 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. ```shell script -jvcl -n my-spec.json # will not run any ffmpeg commands +jvc -n my-spec.json # will not run any ffmpeg commands ``` -Note that this breaks JVCL operations that require information from any assets created by +Note that this breaks JVC operations that require information from any assets created by previous operations: since the command did not actually run, the intermediate asset was never created. When using the other tools in `bin`, you can set the "no exec" flag via the -`JVCL_NO_EXEC` environment variable. If the `JVCL_NO_EXEC` is non-empty, then -the script will pass the `-n` flag when it calls `jvcl` and commands will +`JVC_NO_EXEC` environment variable. If the `JVC_NO_EXEC` is non-empty, then +the script will pass the `-n` flag when it calls `jvc` and commands will be printed out instead of actually being run. #### Help -To view a list of all `jvcl` command-line options, run `jvcl -h` or `jvcl --help` +To view a list of all `jvc` command-line options, run `jvc -h` or `jvc --help` # What's Next? -Learn about [Assets and Operations](concepts.md), the core concepts of JVCL. +Learn about [Assets and Operations](concepts.md), the core concepts of JVC. diff --git a/pom.xml b/pom.xml index effeb71..bb6e51a 100644 --- a/pom.xml +++ b/pom.xml @@ -54,7 +54,7 @@ javicle is available under the Apache License, version 2: http://www.apache.org/ maven-shade-plugin 2.1 - jvcl-${project.version}-prod + jvc-${project.version}-prod @@ -65,7 +65,7 @@ javicle is available under the Apache License, version 2: http://www.apache.org/ - jvcl.main.Jvcl + jvc.main.Jvc