AVELUNE

CLI guide

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

View source
Documentation navigation

Use

  1. CLI guide

Browser

  1. Browser streaming contract
  2. WebGPU and browser acceleration — Draft Generation 1

Architecture

  1. Codec direction (non-normative)

Development

  1. Independent conformance oracle
  2. Testing Avelune
  3. Avelune document authoring profile
  4. Versioning and compatibility
  5. Avelune web style
  6. Release checklist

Project

  1. IPR / prior-art notes — Draft Generation 1

History

  1. Historical internal Avelune “1.0.0” snapshot (superseded)
On this page
  1. Purpose
  2. Install and encode a first file
  3. Playback
  4. Inspection and maintenance
  5. Raw workflows
  6. Shell completions

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.

Note

Draft status: ALV1 and ALA1 are Draft Generation 1 formats: experimental, unfrozen, and subject to incompatible change while the software is 0.x. This guide is non-normative; the specification files under spec/ are authoritative.

Avelune deliberately does not implement foreign H.264/AV1/AAC/etc. demuxing and decoding. Ordinary encode, decode, and play commands use FFmpeg/ffprobe/ffplay at that boundary, so those executables must be available on PATH.

Install and encode a first file

Build the command-line application from the repository, or install it with the source-install one-liner (requires git and Rust; installs to /usr/local/bin, or ~/.local/bin if not writable):

curl -fsSL https://not-the-ccp.github.io/avelune/install.sh | sh

Building manually:

cargo build --release -p avelune-cli
./target/release/avelune --help

Rust 1.97.1 is the reference toolchain. Ordinary media workflows also require ffmpeg, ffprobe, and ffplay on PATH.

Encode, validate, and decode a first file with the repository-built executable:

./target/release/avelune encode input.mkv output.avl
./target/release/avelune verify output.avl
./target/release/avelune decode output.avl roundtrip.mkv

The examples below call the built binary as avelune; substitute ./target/release/avelune when running from the repository check-out.

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.