ivenos/avxs repository overview

Note: This description is automatically generated from the GitHub repository README⁠.

⁠avxs

avxs is an AV1 encoding service. It watches a folder, splits each video into scenes, encodes them in parallel with SVT-AV1 and writes a finished MKV with audio, subtitles and chapters carried over. It ships as a Docker image and as a Linux AppImage with every tool bundled.

⁠Features

• Scene-based parallel encoding with SVT-AV1⁠ or SVT-AV1-HDR⁠
• Resumes from the last finished chunk after a restart
• Target quality: a CRF per chunk from a CVVDP⁠ score, with optional CAMBI⁠ banding limits (GPU required)
• HDR10, HLG, HDR10+ and Dolby Vision profiles 7 and 8
• Automatic crop, downscale and keyframe interval
• Per-track audio and subtitle rules with language filters

⁠Installation

⁠Docker

services:
  avxs:
    image: ivenos/avxs:latest
    user: "1000:1000"
    volumes:
      - ./input:/input
      - ./output:/output
    restart: unless-stopped

Without user: the container runs as root and its files on the host belong to root.

[target_quality] needs a GPU, nothing else does:

• Intel or AMD: add devices: ["/dev/dri:/dev/dri"] and group_add: ["render"].
• NVIDIA: install the nvidia-container-toolkit⁠ and add a GPU reservation, or run with --gpus all.

The arm64 image has no hardware Vulkan driver.

⁠AppImage

Download the AppImage for your architecture from the latest release⁠ and run it. It watches input/ and output/ in the working directory.

⁠Usage

Every subfolder of the input directory is a profile: one encode.toml and the videos it applies to.

input/
├── movies/
│   ├── encode.toml
│   └── The Movie (2021).mkv
├── anime/
│   ├── encode.toml
│   └── Episode 01.mkv
└── processed/               # sources move here once encoded

output/
├── The Movie (2021).mkv
└── Episode 01.mkv

• Supported extensions: mkv, mp4, mov, avi, ts, m2ts, flv, webm, m4v. Only the first video track is encoded.
• A file whose output already exists is skipped. A file that is still being copied in is picked up once it stops growing.
• Output files are named after the source, so two queued files with the same name wait until one is renamed.
• Work in progress lives in output/.avxs_<name>/. Delete that folder to encode a file from scratch.
• A failure that can clear on its own, such as a typo in the profile, a timeout or a full disk, is retried on the next scan. Any other failure writes a .failed file into that folder, and the video is skipped until you delete it.
• On SIGTERM or SIGINT avxs finishes the current file, then exits.

⁠Environment variables

⁠Configuration

Only encoder is required. Unknown keys are rejected, so a typo fails the profile instead of turning a feature off.

encoder = "svt-av1"

[encoder_params]
preset = 6
crf    = 28

[avxs]
hdr       = true
crop      = true
keyint    = true
scale     = 1080
bit_depth = 10

[audio]
language_whitelist = ["eng"]
mode    = "encode"
codec   = "libopus"
bitrate = { stereo = "192k", "5.1" = "320k", "7.1" = "512k", default = "192k" }

[audio.lossless]
codec   = "flac"
options = { compression_level = 12 }

[subtitles]
language_whitelist = ["eng", "jpn"]

⁠encoder

svt-av1 or svt-av1-hdr. Not needed with avxs.video = "copy".

⁠[encoder_params]

Passed to the encoder as --key value; booleans become 1/0. avxs reads two of them itself: lp (default 6) together with free RAM sets how many chunks encode at once, and crf is the first probe when [target_quality] is set.

⁠[target_quality]

Replaces the fixed crf: avxs probes each chunk at a few CRF values and encodes at the highest one that still holds jod. CVVDP scores in JOD from 0 to 10, where 10 means no visible difference from the source.

[target_quality]
jod = 9.5

• max_encoded_percent wins over jod: a chunk that would grow past it gets a higher CRF, and a warning is logged.
• CAMBI is 0 without banding; Netflix places slightly annoying banding at around 5. max_cambi counts banding the source already has, max_cambi_diff does not.
• If no probe holds every limit, the chunk uses the lowest CRF under max_encoded_percent.

⁠[avxs]

⁠[audio]

• The whitelist matches both spellings (deu and ger). Tracks without a language or tagged und are always kept.
• Re-encoded tracks get the codec added to their title, e.g. English 5.1 (Opus).

[audio.lossless] applies to tracks with a lossless source (dts only as DTS-HD MA). [audio.codec_rules] applies by source codec as ffprobe names it. Both take the keys above except language_whitelist. Unset keys come from [audio], except a non-empty options, which replaces it. A matching codec rule wins over [audio.lossless].

[audio.codec_rules]
opus = { mode = "copy" }
eac3 = { mode = "encode", codec = "libopus", bitrate = "192k" }

⁠[subtitles]

Chapters are always kept.

⁠[scene_detection]