guidecurrent

CLI guide

Encode, decode, inspect, verify, and maintain Avelune media from the command line.

Purpose

avelune is the command-line front end to the one canonical Avelune implementation. There is no runtime reference/production backend selector; the independent oracle belongs to development and conformance tests.

Run avelune <command> --help for the authoritative option list.

Ordinary media

Avelune deliberately does not implement foreign H.264/AV1/AAC/etc. demuxing and decoding. Ordinary encode, decode, and play use FFmpeg/ffprobe/ffplay at that boundary.

avelune encode input.mkv output.avl
avelune verify output.avl
avelune decode output.avl roundtrip.mkv

Useful encode options include --seconds, --size, --video-q, --audio-q, --epoch, and --preset fast|balanced|quality. Quantizer values are experimental codec knobs, not CRF values or bitrate targets. Ordinary audio encoding defaults to q=1.

Playback

avelune play movie.avl

This is a convenience transcode/ffplay path. The browser player is the indexed Range/local-file integration and should be used when evaluating Avelune’s streaming model.

Inspection and maintenance

avelune inspect movie.avl
avelune verify movie.avl
avelune frames movie.avl
avelune reindex input.avl reindexed.avl
avelune repair damaged.avl recovered.avl

verify runs the same declared-stream-aware canonical session decoder used by other integrations. If the CLI output workflow sees multiple video or multiple audio streams, it rejects the ambiguous selection rather than silently combining them.

reindex rebuilds the front index from intact packets. repair additionally attempts packet-magic resynchronization; it is best-effort recovery, not forensic repair software.

Raw workflows

avelune raw encode-y4m input.y4m output.avl --q 96 --preset balanced
avelune raw decode-y4m input.avl output.y4m
avelune raw encode-audio input.wav output.avl --q 1
avelune raw decode-audio input.avl output.s16le

Draft Generation 1 video raw input/output is 8-bit 4:2:0 Y4M. Raw decoded audio is interleaved signed 16-bit little-endian PCM.

Shell completions

avelune completions bash > avelune.bash
avelune completions zsh > _avelune
avelune completions fish > avelune.fish

Completion scripts are generated from the same typed Clap command model as --help.