$ av1dae

01 — Prerequisites

Requirements

These external binaries must be on $PATH. The program checks them at startup and exits if any are missing:

To build: Go 1.x with module support.

API keys: an OMDb API key (free at omdbapi.com) is required for movie metadata. TVmaze is unauthenticated.

02 — Compile

Build

go build -o av1dae ./cmd/av1dae/

This produces a self-contained binary ./av1dae (cgo is used for the SQLite logger, so it links against the system libc). To skip installing Go and the encoders on the host entirely, build the container instead — §12.

03 — Setup

Configuration

By default the config loads from ~/.config/av1dae/config.yaml. Pass -c /path/to/config.yaml to override.

omdb_api_key: "YOUR_API_KEY_HERE"

encoding:
  dvd:    { crf: 30, preset: 2 }
  bluray: { crf: 29, preset: 3 }
  webdl:  { crf: 30, preset: 3 }
  tvrip:  { crf: 32, preset: 2 }

paths:
  input:     "./input"
  output:    "./output"
  originals: "./originals"
  failed:    "./failed"
  work:      "./work"

Encoding profiles

Each source type carries its own SVT-AV1 quality pair. The type is chosen by a filename token, or guessed from pixel count (see §5).

Field reference

04 — Operate

Running

./av1dae                       # default config, keep originals
./av1dae -d                    # delete originals after success
./av1dae -c /etc/av1dae.yaml   # custom config
./av1dae -c /etc/av1dae.yaml -d

The program runs as a foreground daemon. It scans the input directory on startup and every 15 seconds thereafter.

05 — Input

Filename convention

The base name of each .mkv in paths.input is parsed to decide what metadata to fetch. Three forms are recognized.

5.1 — Movies: IMDb ID

Filename must contain an IMDb tag of the form tt<digits>.

Heat.tt0113277.mkv
some-rip-tt0114369.mkv

→ OMDb is queried for that IMDb ID. Title, release date, and IMDb ID are embedded.

5.2 — Series: TVmaze ID + season/episode

Filename must contain both tvm<digits> (the TVmaze show ID) and s<digits>e<digits> (season/episode). Both are case-insensitive.

Breaking.Bad.tvm169.S01E01.mkv
the-wire.TVM75.s2e5.mkv

→ TVmaze is queried for that show/season/episode. Show name (Collection), episode title, season, episode, airdate, and the show's IMDb ID are embedded.

5.3 — No recognizable tags

If neither pattern matches, encoding still proceeds but the file is treated as having no metadata. The output is named with a random hex string and an .nometadata.mkv suffix.

5.4 — Optional: source media type

Any filename can additionally carry a media-type token (case-insensitive, word-bounded): dvd, bluray, webdl, or tvrip.

Heat.tt0113277.bluray.mkv
some-rip.tvm169.S01E01.webdl.mkv
old.broadcast.tvrip.tt0066026.mkv

The token controls both the ORIGINAL_MEDIA_TYPE metadata tag and which encoding.<type> crf/preset pair is used.

06 — Signature flow

The processing pipeline

For every .mkv in paths.input, these steps run in order. A per-job scratch subdir under paths.work (named after the input base name) holds all intermediates and is deleted unconditionally at the end. Any error sends the source to paths.failed; the work subdir is wiped regardless.

1. Parse filename

   Determines whether this is a movie or series, and what IDs to use.

2. Probe video (ffprobe)

   • Picks the first stream with codec_type=video, regardless of codec. Errors out if there isn't one.
   • Records width, height, and sample aspect ratio (SAR).
   • Detects interlacing via ffmpeg -vf idet -frames:v 400 -an -sn -f null -, parsing the Multi frame detection summary. Interlaced only when TFF+BFF > Progressive; undetermined frames are ignored, a missing line defaults to progressive.

3. Probe stream languages (ffprobe)

   Collects language tags for every audio/subtitle stream so they survive — -map_metadata -1 strips them otherwise.

4. Detect media type

   • Filename token (dvd/bluray/webdl/tvrip) wins if present.
   • Otherwise pixel count: w × h < 600,000 → DVD, else Blu-ray.
   The chosen profile selects the crf/preset pair and is written to ORIGINAL_MEDIA_TYPE.

5. Fetch metadata

   From OMDb or TVmaze per the parsed filename. Failures here are logged but do not abort the encode — the file is just encoded without metadata.

6. Extract audio

   One PCM wav per source audio stream → audio.0.wav, audio.1.wav, … (PCM s16le, 48 kHz). Errors out if there are no audio streams.

7. Encode audio (opusenc)

   Each wav → audio.<n>.opus at --bitrate 128k.

8. Calculate display width from SAR

   Rescale only when there's work to do — zscale is skipped for square-pixel sources (SAR 1:1, N/A, empty, 0:N) and for any SAR whose width rounds back to the source width. When rescaling, width is rounded to the nearest even number (mod-2, preferred by AV1).

9. Encode video (ffmpeg → libsvtav1)

   • Filter chain built conditionally: bwdif=mode=0:par=-1:-1 prepended when interlaced; zscale appended only when a rescale is needed. Neither → -vf omitted.
   • Codec libsvtav1, -pix_fmt yuv420p10le, crf/preset from the profile.
   • -svtav1-params film-grain=10:film-grain-denoise=1:scd=1:qm-min=4:qm-max=15:keyint=10s
   • Maps: video 0:v, subtitles 0:s? (optional), one audio per opus file (1:a, 2:a, …). Audio -c:a copy, subtitles -c:s copy.
   • -map_metadata -1 strips global metadata, then language tags are re-applied — audio indexed by output position, so missing-language streams don't shift the index.
   • Container tags: TITLE, DATE_RELEASED, IMDBID, ORIGINAL_MEDIA_TYPE — plus COLLECTION, SEASON, EPISODE, TVMAZE_ID for series. Values unquoted. Output → output.mkv in the work dir.

10. Clean up the work directory

    Intermediates and output.mkv together — once the move below succeeds, or on any failure via deferred cleanup.

11. Rename and move to paths.output

    • Series with a known show name → <show>.S<NN>E<NN>.mkv (no IMDb mapping required).
    • Movie with title + IMDb ID → <title>.<imdbID>.mkv.
    • Anything else → <8-hex>.nometadata.mkv.
    Sanitization keeps a–z A–Z 0–9 - ä ö Ä Ö only.

12. Dispose of the source

    -d set → delete the original; otherwise → move it to paths.originals.

07 — Reference

Output naming examples

08 — Observability

Logs

All logs are written to a SQLite database, logs.db, in the current working directory (not the config paths). Run the program from where you want it to land — in Docker that's the mounted /data. The logs table has columns id, ts, level, message, file, extra.

Live encode progress (encoding … · 47% · 3.2fps · …) prints to stdout only and is deliberately not stored, so it can't flood the database.

09 — Resilience

Failure handling

If any step from probing through encoding through renaming fails:

• The source .mkv is moved to paths.failed (os.Stat-guarded — if the source is already gone the move is skipped and logged; a move error is logged too). This guarantees the source leaves paths.input on every failure path, so the watcher won't retry it next tick.
• The per-job work directory (partial wav/opus/output.mkv) is deleted unconditionally.
• The error is logged to logs.db (level error) with the source path, and printed to stderr.

The watcher continues with the next file; one bad rip won't stop the daemon.

10 — Watcher

Polling behavior

• Input directory is scanned every 15 seconds (clamped to a 10–30 s range).
• Only *.mkv directly in paths.input are picked up — no recursion.
• Files are processed sequentially, one at a time, in the order filepath.Glob returns (alphabetical on Linux).
• Partial-write protection: a file's mtime and size must match on two consecutive scans before processing. A freshly dropped or still-copying file waits at least one full tick (~15 s). Copying a large file straight into paths.input is safe — no need to land it under a different name and mv into place (though that still works and skips the tick delay).
• Failure quarantine: if processFile errors, that file is skipped for 5 minutes (or until its mtime changes — e.g. you replace or touch it). Stops a permanently-broken input from spamming the logs. In-memory only; restarting clears it.

11 — Source map

Project layout

cmd/av1dae/main.go        CLI entrypoint and per-file orchestration
internal/config/          YAML config load + defaults + mkdir
internal/watcher/         Polling loop, media-type detection by pixel count
internal/encoder/         ffprobe/ffmpeg/opusenc wrapper, transcode pipeline
internal/metadata/        Filename parsing, OMDb + TVmaze clients
internal/mover/           File rename/move/delete helpers
internal/logger/          Plain + JSON logging
pkg/types/types.go        Shared structs (Config, Job, Metadata, …)

Runtime directories (from paths.* in the config):

paths.input        Drop new .mkv here; polled every 15 s
paths.output       Finished encodes land here under their final name
paths.originals    Encoded sources end up here (unless -d)
paths.failed       Sources of failed jobs end up here
paths.work         Per-job scratch subdir (basename); wiped per job

12 — Deploy

Deploy with Docker

Run it as a container on your server. ffmpeg, ffprobe, and opusenc are baked into the image, so the only host requirement is Docker — nothing to install, nothing on $PATH.

Quick start

# one-time: create the media tree and your config
mkdir -p media/input media/output media/originals media/failed media/work
cp config.example.yaml config.yaml   # then fill in omdb_api_key

docker compose up -d --build

Drop .mkv files into media/input/; finished encodes appear in media/output/. Follow the logs with docker compose logs -f.

How the volumes map

Two mounts (defined in docker-compose.yml) are all it needs:

What's in the image

Without compose

Same thing with plain docker:

docker build -t av1dae .
docker run -d --name av1dae --restart unless-stopped \
  -v "$PWD/config.yaml:/config/config.yaml:ro" \
  -v "$PWD/media:/data" \
  av1dae