Commands

The coreav command has one subcommand per job. Each page here shows the command’s --help text, as the command prints it.

Command	What it does
`probe`	Describes an MP4, MOV, Matroska, WebM or MPEG-TS file as JSON.
`check`	Checks a file against an upload policy and prints the verdict.
`chapters`	Prints the QuickTime chapter list of an MP4 or MOV file.
`clip`	Cuts a keyframe-aligned clip of an MP4 or MOV file.
`split`	Splits an MP4 or MOV file at keyframes into MP4 segments.
`join`	Joins MP4 or MOV files that share a codec configuration.
`remux`	Rewrites MP4, MOV, Matroska or WebM as MP4 with the movie header first.
`sanitize`	Rewrites an MP4 or MOV file without its metadata.
`extract-audio`	Copies the AAC track of an MP4 or MOV file into M4A.
`extract-subtitles`	Writes the text subtitles of an MP4 or MOV file as WebVTT.
`decode-audio`	Decodes a FLAC or MP3 track to WAV.
`hls`	Serves an MP4 or MOV file as HLS.
`ffprobe`	Experimental. Runs an `ffprobe` command line.
`ffmpeg`	Runs an `ffmpeg -c copy` command line.
`thumbnail`	Writes an image of the frame at a time. Builds with a decoder backend only.
`transcode`	Re-encodes the video to H.264 in MP4. Builds with a decoder backend only.

Only decode-audio, thumbnail and transcode decode anything, and only transcode encodes. The other commands copy the coded data as it is.

Inputs

An input is a local file. In native builds, the commands that read one media file (probe, check, clip, split, extract-audio, remux, sanitize, extract-subtitles and chapters) also read an https:// URL, by byte ranges, never downloading the whole file (remote media).

Outputs

A command that writes a file writes it under a temporary name and renames it into place, so a failed run leaves no partial output.
A command refuses to overwrite an existing file unless you pass --force, and never writes over its input.
Most commands take - as the output, for standard output. The JSON summary then goes to standard error.
Each JSON document names its schema, such as coreav.probe/1. The schemas are in docs/schema.

Exit statuses

Status	Meaning
0	Success. For `check`, the file is accepted.
1	The file was rejected: unsupported, damaged or not allowed. For `check`, the verdict is on standard output.
2	Usage error: bad arguments or an invalid policy.
3	I/O error: a missing file, an unreadable URL or an unwritable output.
4	`coreav ffprobe` or `coreav ffmpeg` refused a command line it does not implement (strict-safe mode).
141	Standard output was closed by its reader, as in `coreav probe input.mp4 \| head`.

Errors

On exit status 1 and 3, standard error holds one JSON object (coreav.error/1), except a rejection by check, whose verdict is on standard output:

{"kind":"unsupported_container","limit":null,"message":"not an ISO base media or QuickTime file","offset":null,"schema":"coreav.error/1"}

kind is stable and meant for programs. message is for people. Usage errors are plain text that starts with error:.

Global options

The coreav command: memory-safe probing of MP4/MOV, Matroska, WebM and MPEG transport stream files, local or at an HTTP(S) URL; clipping, splitting, joining, sanitizing, audio, subtitle and chapter extraction and HLS packaging of MP4/MOV files; remuxing of all of them to MP4; decoding of their audio to WAV; and upload policy checks

Usage: coreav [OPTIONS] <COMMAND>

Commands:
  probe              Describe an MP4, MOV, Matroska or WebM file as JSON
  clip               Cut a keyframe-aligned clip of an MP4/MOV file to MP4, without re-encoding
  split              Split an MP4/MOV file at keyframes into MP4 segments, without re-encoding. Together the segments hold every packet of the kept streams exactly once
  check              Check an MP4, MOV, Matroska or WebM file against an upload policy and print the verdict as JSON
  extract-audio      Copy the AAC audio track of an MP4/MOV file into an M4A file, without re-encoding
  decode-audio       Decode an audio track of an MP4/MOV, Matroska or WebM file to a WAV file (FLAC, MP3)
  remux              Rewrite an MP4/MOV, Matroska or WebM file as MP4 with the movie header first (faststart), without re-encoding
  extract-subtitles  Write the text subtitles (mov_text: 3GPP timed text or QuickTime text) of an MP4/MOV file as WebVTT
  chapters           Print the QuickTime chapter list of an MP4/MOV file as JSON
  sanitize           Rewrite an MP4/MOV file as MP4 without its metadata (location, device, dates), keeping only allowlisted boxes, without re-encoding
  join               Join MP4/MOV files that share a codec configuration into one MP4, without re-encoding
  hls                Serve an MP4/MOV file as HLS with fragmented MP4 (CMAF) segments, without re-encoding
  ffprobe            Experimental. Runs an ffprobe command line: ffprobe's own options, a supported subset. With --strict-safe (COREAV_STRICT_SAFE=1), for untrusted input, anything else is refused with exit status 4; without it, anything else runs the ffprobe program on PATH, FFmpeg's C code (docs/design/compat-cli.md). Values can differ from ffprobe's for MP4/MOV and MPEG-TS; Matroska/WebM agree on 98% or more of files for 99 of 101 keys (docs/measurements/compat-ffprobe.md). `coreav` run as `ffprobe` does the same
  ffmpeg             Runs an ffmpeg stream-copy command line (-c copy) with CoreAV's own writers: remuxing to MP4, clipping, segmenting and audio extraction to M4A, with ffmpeg's stream selection. With --strict-safe (COREAV_STRICT_SAFE=1), for untrusted input, anything else is refused with exit status 4; without it, anything else runs the ffmpeg program on PATH, FFmpeg's C code (docs/design/compat-cli.md). `coreav` run as `ffmpeg` does the same
  help               Print this message or the help of the given subcommand(s)

Options:
      --strict-safe  For services that read untrusted input: `coreav ffprobe` and `coreav ffmpeg` never run FFmpeg in place of a command that is not native, and refuse it (exit status 4), as COREAV_STRICT_SAFE=1 does. Without it, such a command runs the ffmpeg or ffprobe program found on PATH (or named by COREAV_FALLBACK), which is FFmpeg's C code
  -h, --help         Print help
  -V, --version      Print version

How this reference stays in agreement with the help

The help text on each page is generated from the command’s --help. A test, crates/coreav-cli/tests/docs_site.rs, runs every command’s --help and fails when a page’s text differs, or when a command has no page. CI runs it in the default build and in a build with a decoder backend.

Overview

Inspect

Cut and rewrite

Extract and decode

Serve

FFmpeg command lines

Builds with a decoder backend

Commands

Commands

Inputs

Outputs

Exit statuses

Errors

Global options

How this reference stays in agreement with the help

​Commands

​Inputs

​Outputs

​Exit statuses

​Errors

​Global options

​How this reference stays in agreement with the help

Commands

Inputs

Outputs

Exit statuses

Errors

Global options

How this reference stays in agreement with the help