Skip to main content

Agent guide

Run local video frame extraction through the CLI or MCP.

Chrona gives agents a local CLI and an MCP server. Both tools use the same core rules as the browser editor. The npm package installs native FFmpeg and FFprobe binaries. The CLI reads videos from local paths. Chrona never sends a source video to the website.

First command

npx -y chrona-cli@0.1.0 --json doctor

Requires Node.js 22 or later. The package installs FFmpeg and FFprobe.

01 / Start

Run without a global install

Pin the package version for stable agent runs. npx downloads the package and starts the selected command.

npx -y chrona-cli@0.1.0 --json doctor
npx -y chrona-cli@0.1.0 --json probe ./video.mp4
npx -y chrona-cli@0.1.0 --json extract ./video.mp4 --output frames.zip
  • The npm package installs pinned FFmpeg 6.1.1 and FFprobe binaries for supported systems.
  • Chrona uses a command option before an environment variable.
  • Set `CHRONA_FFMPEG` or `CHRONA_FFPROBE` to override an installed binary.
  • Next, Chrona uses the installed binary before a compatible binary on `PATH`.
  • If npm skips install scripts, Chrona uses compatible binaries on `PATH`.
  • If Chrona cannot run a binary, reinstall the package or pass an explicit path.
  • The binary packages include their GPL-3.0-or-later license files.
  • If you redistribute the binaries, read those license files.

02 / Model

Choose the local surface

Use the CLI for scripts, shells, and direct process control.

Use MCP for tool discovery and typed calls from an agent host.

Use plan files to move edits between the browser, CLI, and MCP.

Use the website only to share a finished ZIP for 24 hours.

Chrona keeps source media on the local machine. A media API moves source media across a network and breaks that rule.

The MCP server adds tool discovery. It calls the same local service as the CLI.

03 / Coverage

Feature parity

Every browser outcome has a CLI command or option.

Browser outcomeAgent action
Open a local videoPass a local path to `probe`, `plan`, `estimate`, or `extract`.
Read video detailsRun `probe`.
Detect solid bordersUse the default `--crop auto` mode.
Trim the start and endUse `--start` and `--end`.
Remove many sectionsRepeat `--cut START..END`.
Keep original timingUse `--fps original`.
Choose a fixed rateUse a decimal or rational value with `--fps`.
Estimate the ZIP sizeRun `estimate`.
Export lossless PNG framesUse `--quality 100`.
Create a smaller ZIPUse `--quality 50` through `--quality 99`.
Inspect frame previewsRun `frame` for any exported frame.
Download the ZIPRun `extract` with a ZIP output path.
Create a 24-hour linkRun `share` on the finished ZIP.
Open a shared ZIPRun `download` on the share link.
Move edit settingsImport or export a version 2 plan.
Cancel active workCancel the CLI process or the MCP tool call.

04 / Reference

Commands

doctor

Check FFmpeg and FFprobe.
npx -y chrona-cli@0.1.0 --json doctor
  • Exit code 3 means that Chrona cannot run a native binary.

probe

Read video details, exact frame times, and the detected border crop.
npx -y chrona-cli@0.1.0 --json probe ./video.mp4
  • Add `--fast` to skip the exact frame timing scan.
  • Add `--no-auto-crop` to skip border detection.

plan

Create a portable versioned plan without writing frames.
npx -y chrona-cli@0.1.0 --json plan ./video.mp4 --start 00:02 --end 00:12 --cut 00:05..00:07 --fps 30000/1001 --quality 80 --write edit.chrona.json
  • The default crop mode is `auto`.
  • Use `--crop none` to keep the full displayed frame.
  • Use `--crop LEFT:TOP:WIDTH:HEIGHT` for an exact crop.

estimate

Estimate frame count and output size from three PNG samples.
npx -y chrona-cli@0.1.0 --json estimate ./video.mp4 --plan edit.chrona.json
  • The estimate uses the plan crop, rate, ranges, and quality.

extract

Write continuous, one-based PNG frames and a manifest.
npx -y chrona-cli@0.1.0 --json --progress json extract ./video.mp4 --plan edit.chrona.json --output frames.zip
  • Use `--dry-run` to inspect the plan and FFmpeg filter.
  • A dry run never creates output files.
  • Use `--overwrite` to replace an existing ZIP or directory.

validate

Validate frame names, manifest data, and PNG dimensions.
npx -y chrona-cli@0.1.0 --json validate ./frames.zip
  • The command accepts a ZIP or an extracted directory.

frame

Copy one full-size PNG from a ZIP or directory.
npx -y chrona-cli@0.1.0 --json frame ./frames.zip 42 --write frame-42.png
  • Use this command for visual inspection or vision model input.

share

Upload a finished ZIP and create a 24-hour link.
npx -y chrona-cli@0.1.0 --json share ./frames.zip
  • This command validates the ZIP before upload.
  • Use `--app-url` or `CHRONA_APP_URL` to target another Chrona deployment.
  • The command never uploads the source video.

download

Download and validate a shared ZIP.
npx -y chrona-cli@0.1.0 --json download https://chrona.fyi/artifacts/TOKEN --output frames.zip
  • Use `--overwrite` to replace an existing ZIP.

schema

Print the plan or manifest JSON Schema.
npx -y chrona-cli@0.1.0 --json schema plan
  • Use `schema manifest` for the extraction manifest.

mcp

Run the MCP server over standard input and output.
npx -y chrona-cli@0.1.0 mcp
  • The server exposes each CLI outcome as a typed tool.

05 / Inputs

Options

Global options

--json
Write one JSON result to standard output.
--progress tty|json|none
Write progress to standard error.
--quiet
Hide the human result.

Native tools

--ffmpeg-path PATH
Override the installed FFmpeg executable.
--ffprobe-path PATH
Override the installed FFprobe executable.

Edit and output options

--start TIME
Set the retained start.
--end TIME
Set the retained end.
--cut START..END
Remove one half-open range. Repeat this option for more cuts.
--fps MODE
Use original timing, the detected rate, a decimal rate, or a rational rate.
--crop MODE
Use auto, none, or LEFT:TOP:WIDTH:HEIGHT.
--quality 50..100
Set the PNG detail and output dimensions.
--archive zip|directory
Write a ZIP or a directory.
--output PATH
Set the output path.

Extraction options

--plan PATH
Read a versioned plan. Use a source path with browser plans.
--dry-run
Show the work without creating output.
--overwrite
Replace an existing output.
--png-depth 8|16|auto
Set the PNG channel depth.
--compression 0..9
Set lossless PNG compression effort.
--keep-temp
Keep temporary frames for debugging.

Sharing

--app-url URL
Use another Chrona website for sharing.

06 / Automation

JSON contract

  • Place `--json` before or after the command.
  • A successful command writes one JSON value to standard output.
  • A failed command writes one JSON error to standard output.
  • Use `--progress json` for JSON Lines on standard error.
  • Chrona never prompts in JSON mode.
  • Paths in JSON results are absolute paths.

07 / Interchange

Portable plans

  • Plan schema version 2 stores retained source ranges, rate, crop, quality, and archive type.
  • Browser plans include source file size and duration.
  • Chrona rejects a plan after the source size or duration changes.
  • CLI plans can include local input and output paths.
  • Browser exports omit local paths.
  • Run `schema plan` to get the complete JSON Schema.
npx -y chrona-cli@0.1.0 --json plan ./video.mp4 --write edit.chrona.json
npx -y chrona-cli@0.1.0 --json extract ./video.mp4 --plan edit.chrona.json

08 / Tool protocol

MCP server

Add this server to an MCP host. The host starts a pinned npx process.

{
  "mcpServers": {
    "chrona": {
      "command": "npx",
      "args": ["-y", "chrona-cli@0.1.0", "mcp"]
    }
  }
}
doctorprobe_videocreate_planestimate_outputextract_framesvalidate_outputread_frameshare_archivedownload_archive

09 / Recovery

Exit codes

0Success
2Invalid command or missing choice
3Missing FFmpeg or FFprobe
4Invalid or unsupported input
5Extraction or processing failure
6Output validation failure
7Share or download failure

One release, two local interfaces

  • Pin the package version in scripts and MCP settings.
  • The website and npm package come from the same repository release.
  • The npm package includes the CLI, MCP server, schemas, native tools, and shared core rules.
  • The browser app does not require the npm package.
Open editor