auto-editor

Editing with auto-editor

auto-editor analyzes a media file, marks every timebase section as active (e.g. loud) or inactive (e.g. silent), then applies an action to each. The defaults: keep active sections unchanged, cut inactive ones.

auto-editor path/to/video.mp4          # writes video_ALTERED.mp4
auto-editor video.mp4 -o out.mp4       # choose the output name

Run the installed auto-editor, or ./auto-editor from this repo. auto-editor info FILE shows streams/codecs/duration; --preview prints what would be cut and exits without rendering — use it to sanity-check before a long render.

Record and edit a microphone

Use :mic as the input on macOS, Windows, or Linux. Stop capture gracefully with Ctrl-C; auto-editor then analyzes and edits the recording normally.

auto-editor :mic                                      # → mic_ALTERED.wav
auto-editor :mic --sample-rate 44.1kHz -o trimmed.m4a
auto-editor :mic --edit audio:threshold=6%

All normal edit, action, and rendering options apply. Editor and timeline exports preserve the source capture separately; use the auto-editor-export skill for recording-codec and naming details.

1. Choose what counts as "active" — --edit METHOD

audio:threshold=0.04,stream=all is the default. Threshold takes a 0–1 fraction or a dB value (case-sensitive).

Method	Marks active when…	Key args (defaults)
audio	loudest sample ≥ threshold	threshold=0.04, stream=all
motion	frame-to-frame change ≥ threshold	threshold=0.02, stream=0, width=400, blur=9
blackdetect	frame is mostly black	threshold=0.98, pixel-black=0.10 (wrap in not to cut black)
subtitle/regex	a subtitle line matches pattern	pattern (required), ignore-case=#f
word	a whole word appears in subtitles	value (required), ignore-case=#t
1 / 0	every / no moment is active (keep-all / cut-all)	aliases none / all; a base for manual ranges

auto-editor video.mp4 --edit audio:threshold=0.04
auto-editor video.mp4 --edit audio:-19dB            # dB form
auto-editor video.mp4 --edit motion:threshold=0.02
auto-editor video.mp4 --edit blackdetect            # cut to remove black: --edit "(not blackdetect:0.98)"

Combine streams/methods with boolean operators or, and, xor, not. Inside an operator, give the method an explicit arg in call form (audio:0.04, not bare audio) — a bare method there errors with Bad kind:

auto-editor multi.mov --edit "(or audio:stream=0 audio:threshold=10%,stream=1)"
auto-editor video.mp4 --edit "(or audio:0.03 motion:0.06)"   # threshold is always positional arg 1
auto-editor video.mp4 --edit "(not audio:0.04)"              # invert: keep the quiet parts

Labels — more than just silent vs. loud (--edit:N, --when:N)

Every moment is tagged with an integer label (0–255), and each label has an action. Two labels are built in:

Label	Meaning	Set the membership with	Set the action with (default)
0	silent / inactive	(whatever --edit does not match)	--when-inactive = -w:0 = --when:0 (cut)
1	normal / active	--edit EXPR (i.e. --edit:1 EXPR)	--when-active = -w:1 = --when:1 (nil)

So plain --edit audio is shorthand for --edit:1 audio: matched moments become label 1, the rest stay 0. -w:0/-w:1 are just --when:0/--when:1.

Add custom classes with --edit:N EXPR (N = 2–255) and give each its own action with --when:N ACTION (default nil = keep). Where classes overlap, the higher label wins:

# Cut silence (0) and keep speech (1) as usual, but also zoom wherever there's motion (2)
auto-editor video.mp4 --edit:2 motion:0.02 --when:2 zoom:2
auto-editor video.mp4 -e:2 motion:0.1 -w:2 speed:2        # -e/-w short forms

# Three tiers: cut silence, keep quiet speech at 1x, speed up the loud parts
auto-editor talk.mp4 --edit audio:-30dB --edit:2 audio:-12dB --when:2 speed:1.5

--edit:0 is rejected — label 0 is the implicit silent class; use --when:0 to act on silent moments. (The --edit 1 / --edit 0 values above are unrelated: they set label 1's expression to the all-true / all-false constant.)

2. Set the pace — --margin and --smooth

auto-editor video.mp4 --margin 0.2sec        # default: pad each kept section by 0.2s both sides
auto-editor video.mp4 --margin 0.3s,1.5sec   # 0.3s before, 1.5s after (avoids clipped words)
auto-editor video.mp4 --smooth 0.2s,0.1s     # min-cut 0.2s, min-clip 0.1s (default); --smooth 0 = off

3. Manual edits — range syntax

--cut, --keep, --set-speed, --set-action take START,STOP ranges. Start is inclusive, stop exclusive. Default unit is the timebase; add sec (s/second) for seconds. Vars start/end; negatives count from the end. Ranges combine with automatic edits, or use --edit 0/--edit 1 for manual-only editing.

auto-editor video.mp4 --cut 0,30 -10sec,end    # drop first 30 frames and last 10s
auto-editor video.mp4 --keep 0,30sec           # force-keep first 30s regardless of loudness
auto-editor video.mp4 --set-speed 2,0,30       # SPEED,START,STOP: 2x over frames 0–29
auto-editor video.mp4 --edit 1 --cut 0,5sec    # no auto cuts, just drop first 5s
auto-editor video.mp4 --edit 0 --keep 0,5sec   # keep only the first 5s

4. Reverse the edit — see what gets cut

auto-editor video.mp4 --when-active cut --when-inactive nil   # keep the silence, cut the loud parts

5. Render & file size

auto-editor video.mp4 -c:v hevc -b:v 0       # variable bitrate
auto-editor video.mp4 -b:v 230k              # target a bitrate to shrink the file
auto-editor video.mp4 -crf 23 -preset medium # quality-based encoding
auto-editor video.mp4 --scale 0.5            # halve the resolution
auto-editor video.mp4 -anorm ebu             # EBU R128 loudness normalize (or peak:-3)

Larger-than-expected files are usually a too-high auto bitrate — set -b:v or -crf. auto-editor cache lists/cache clears the analysis cache.

Going further

• Creative effects (speed/zoom/overlays/animations) → auto-editor-effects skill
• Export to Premiere/Resolve/Final Cut, clip-sequence, or .v1/.v2/.v3 timelines → auto-editor-export skill
• Transcribe audio and cut by spoken words → auto-editor-transcribe skill
• Full option list: auto-editor --help or https://auto-editor.com/ref/options.md