Thor Codec Administrator & Developer Guide

This guide is the source-of-truth reference for engineers who deploy, audit, or modify the Thor reference codec. It covers the architecture of the encoder and decoder, every encoder configuration parameter, the bitstream syntax, the security posture of the reference implementation, and the internals you need to land an upstream patch. It complements the User Guide, which focuses on day-to-day usage and the shipped configuration presets.

Thor is a hybrid block-based video codec authored by Cisco Systems for the IETF NETVC working group. The repository contains a reference encoder (Thorenc) and decoder (Thordec) written in portable C99, hand-tuned SIMD kernels for SSE2/SSSE3/SSE4/AVX2 (x86) and NEON (ARM), and 30 preset configuration files that mirror the operating points described in the Thor Internet-Draft. There are no runtime dependencies beyond libm.

1. Architecture Overview

Thor is structured as three top-level source directories:

• common/ — code shared by both encoder and decoder: block-coding helpers, intra and inter prediction, transform/quantisation, deblocking, CDEF, CLPF, weight matrices, frame buffer management, SNR computation, and SIMD abstractions.
• enc/ — encoder-only code: rate-distortion optimisation loop, motion estimation, mode decisions, rate control, bitstream writer.
• dec/ — decoder-only code: bitstream parser, mode dispatcher, inverse transform driver, frame reconstruction loop.

Each binary links a single main() (enc/mainenc.c or dec/maindec.c) plus the relevant common code. The Makefile compiles 80+ .c files into two standalone executables, with common/ shared between them.

High-level encoder pipeline

                +-----------+      +-----------+      +-----------+
  raw YUV  ---> |  Read &   | ---> |  Frame-   | ---> | Per-block |
   (or Y4M)     |  configure|      |  level    |      |  RDO loop |
                | (strings  |      |  setup    |      | (encode_  |
                |  .c)      |      | (mainenc  |      |  block.c) |
                +-----------+      |  .c)      |      +-----------+
                                   +-----------+              |
                                                              v
       +------------+   +------------+   +-----------+   +------------+
       | Bitstream  |<--| Inverse    |<--| In-loop   |<--| Predict +  |
       | (write_    |   | quantise+  |   | filters   |   | transform  |
       |  bits.c +  |   | inverse    |   | (deblock, |   | + entropy  |
       |  putvlc.c) |   | transform  |   |  CDEF,    |   | code coeff |
       +------------+   +------------+   |  CLPF)    |   +------------+
                                         +-----------+

High-level decoder pipeline

                +-----------+      +-----------+      +-----------+
  bitstream --> | initbits_ | ---> | read_seq_ | ---> | decode_   |
                | dec       |      | header /  |      | frame     |
                | (getbits  |      | read_     |      | (decode_  |
                |  .c)      |      | frame_hdr |      |  frame.c) |
                +-----------+      +-----------+      +-----------+
                                                            |
                                                            v
       +------------+   +------------+   +-----------+   +------------+
       | YUV / Y4M  |<--| In-loop    |<--| Inverse   |<--| Per-block  |
       | output     |   | filters    |   | quantise+ |   | mode       |
       | (maindec   |   | (deblock,  |   | inverse   |   | dispatch + |
       |  .c)       |   |  CDEF,     |   | transform |   | predict    |
       +------------+   |  CLPF)     |   +-----------+   | (decode_   |
                        +------------+                   |  block.c)  |
                                                         +------------+

Both pipelines share common/: prediction, transform, kernels, deblocking and SIMD abstractions. The encoder additionally drives an inverse-transform path on its own output to keep the encoder's reconstruction byte-identical with the decoder's output.

Note

The reference implementation is single-threaded by design. There is no tile-level parallelism, no slice-level parallelism, no multi-threaded encoder, and no decoder thread pool. This makes the codec easy to reason about for research but limits throughput; expect ~real-time 1080p30 on a modern x86 core at low-complexity settings.

Component inventory

Technology stack

Data flow for a single encode-decode round trip

1. Thorenc reads the configuration via parse_config_params() (recursive over -cf files), then check_parameters() validates ranges.
2. Thorenc opens -if, peeks at the first 256 bytes, and if the magic YUV4MPEG2 is present, parses W/H/F/I/C/A/X tags into the encoder parameters.
3. Thorenc writes a sequence header into the output bitstream (write_sequence_header() — see §8 for syntax) and emits a per-frame header for each frame, followed by mode/coefficient payloads.
4. Thorenc runs an encode-then-reconstruct cycle per block, so its in-memory rec buffer matches what Thordec will produce. PSNR Y/U/V is computed against the original input frame.
5. Thordec reads the bitstream, extracts width/height/bit-depth from the sequence header, allocates frame buffers, and decodes each frame using the same in-loop filters in the same order as the encoder.
6. The decoder writes raw YUV (or Y4M with a .y4m output extension) and prints exhaustive bit-allocation and mode-distribution statistics.

2. System Requirements

Note

Thor's -march=native -mtune=native default makes the build sensitive to the host micro-architecture. For portable distribution, pin to a baseline (ARCH=core2 for legacy x86, ARCH=avx2 for modern x86, ARCH=neon for ARM). The portable C SIMD fallback at common/simd/ compiles when no ARCH flag matches.

Tested toolchains (per upstream issue history)

3. Configuration Reference

Thorenc is driven by 70+ command-line flags, each settable on the command line or inside a -cf config file. Every flag has a hard-coded default in enc/strings.c (parse_config_params()); explicit -cf flags or command-line flags override defaults.

3.1 Configuration file format

; comments start with a semicolon and run to end of line
-flag_name           value                                ; inline comment
-another_flag        "value with spaces"                  ; quoted string
-int_list            1, 2, 3, 4                           ; comma-separated ints
-cf                  another_config.txt                   ; recursive include

The parser at enc/strings.c:read_config_file() skips whitespace, supports double-quoted strings for paths/values containing spaces, and treats ; as a line-comment marker. Flags defined later override earlier ones; command line wins over -cf files.

3.2 File I/O parameters

3.3 Geometry parameters

3.4 QP, lambda, and rate control

Important

-bitrate > 0 together with -num_reorder_pics > 0 aborts with Current rate control doesn't work with frame reordering. The reference rate controller in enc/rc.c does not support hierarchical B frames yet. For variable-bitrate hierarchical encodes, use the -mqp*/-dqp* framework on a single base QP instead.

3.5 Coding tool parameters

3.6 Build-time parameters

The build system reads one environment variable:

There are no other build-time configuration knobs. Compile-time #defines in common/global.h (MAX_QP, MAX_REF_FRAMES, CDEF, NEW_DEBLOCK_FILTER, DYADIC_CODING, etc.) select compile-time variants during research but are not part of the supported configuration surface.

3.7 Annotated walkthrough — a high-efficiency 4K config

-cf config_RA_high_efficiency.txt   ; baseline preset
-width                       3840
-height                      2160
-f                           60
-bitdepth                    10     ; 10-bit internal codec
-input_bitdepth              10     ; 10-bit YUV source
-frame_bitdepth              16     ; (auto-forced) 16-bit frame buffers
-num_reorder_pics            7      ; 8-frame sub-GOP
-max_num_ref                 4      ; up to 4 references per inter block
-intra_period                64     ; intra refresh every 64 frames
-qp                          24     ; aggressive base QP
-max_delta_qp                4      ; per-superblock QP wobble of +-4
-cdef                        1      ; slow but better-quality CDEF
-clpf                        2      ; frame-level CLPF
-qmtx                        1      ; quantisation matrices on
-snrcalc                     1

3.8 Decoder configuration

Thordec has no configuration. Every parameter is read from the bitstream's sequence header (see §8). The only runtime input is the path to the bitstream and an optional output path.

4. Deployment & Scaling

Thor ships as two standalone CLI binaries with no daemon, no socket, no worker pool, and no orchestrator. Deployment patterns reflect those constraints.

4.1 Single-host research deployment

The default. Build on the target host; invoke Thorenc and Thordec directly from shell scripts, Python, or research notebooks.

make -j8 ARCH=avx2
./build/Thorenc -cf config_RA_medium_complexity.txt -if src.yuv \
    -of out.bit -rf rec.yuv -width 1920 -height 1080 -f 30 -n 300 -qp 27
./build/Thordec out.bit out.yuv

Tip

For reproducible research, fix ARCH to a baseline (e.g., core2) and document toolchain version (gcc --version) alongside every result. Floating-point reduction order on -march=native builds can drift across CPU vendors and produce ~0.01 dB PSNR differences.

4.2 Batch farm — fan-out via shell

Thor is single-threaded per process, so horizontal scaling means running multiple Thorenc processes in parallel. GNU parallel is the cleanest driver:

ls inputs/*.yuv | parallel -j $(nproc) \
  './build/Thorenc -cf config_RA_medium_complexity.txt \
      -if {} -of out/{/.}.bit -rf out/{/.}_rec.yuv \
      -width 1920 -height 1080 -f 30 -qp 32 -n 300 \
      > out/{/.}.log 2>&1'

The encoder uses ~250 MB of RSS at 1080p with default settings, scaling roughly linearly with frame area. Plan for (num_jobs * 250 MB) + OS overhead at 1080p, or (num_jobs * 1 GB) at 4K.

Note

Do not run more parallel jobs than you have physical cores. Thor saturates a single core; oversubscription costs throughput because of SIMD register-file pressure and cache contention. With AVX2 builds in particular, 1 process per physical core (not hyperthread) is the throughput sweet spot.

4.3 Containerisation

A single-stage Dockerfile is sufficient for the binaries:

FROM ubuntu:22.04 AS build
RUN apt-get update && apt-get install -y build-essential bash git
RUN git clone https://github.com/cisco/thor.git /thor
WORKDIR /thor
RUN make -j$(nproc) ARCH=avx2

FROM ubuntu:22.04
COPY --from=build /thor/build/Thorenc /usr/local/bin/Thorenc
COPY --from=build /thor/build/Thordec /usr/local/bin/Thordec
COPY --from=build /thor/config_*.txt /etc/thor/
ENTRYPOINT ["Thorenc"]

4.4 Scaling limits

5. Operations

The reference codec has no daemon, no logs, no metrics endpoint. Operations boils down to "watch stdout and stderr from each Thorenc/Thordec invocation."

5.1 Standard stdout/stderr

Per-frame, the encoder writes one stdout line of the form:

   12 P   30      28591    34.2811  39.1450  39.7902    0   1   2   3 |   12   11   10    9

Columns: frame_num, frame type (I/P/B), QP, total frame bits, PSNR-Y, PSNR-U, PSNR-V, then the chosen reference indices, then the display frame numbers of those references.

After the run, the encoder prints aggregate bit/byte counts, average PSNR per channel, and the realised bitrate in kbps.

The decoder writes one stdout line per decoded frame:

decode_frame_num=  12 display_frame_num=   9 input_file_size=    3829512 bitcnt=    421376

After the run, it prints exhaustive bit-allocation, mode-distribution, size-distribution, super-mode, and reference-index statistics.

5.2 Health checks for batch jobs

For a batch farm, the canonical "encode succeeded" check is:

1. Thorenc exit code is 0.
2. -of file exists and is non-empty.
3. The trailing summary line is present in stdout.
4. (Optional) Thordec out.bit /tmp/test.yuv && cmp /tmp/test.yuv rec.yuv to confirm the decoder agrees.

Tip

Drive make check in CI after every patch. The check.sh harness already encodes, decodes, and cmps four resolutions; a pass gives you reasonable assurance no regression slipped in. Pair with valgrind (make check test-valgrind=1) on a slower CI lane to catch memory-safety regressions.

5.3 Operational checklist for a release

• [ ] make clean && make -j$(nproc) completes with no warnings under gcc and clang.
• [ ] make check test-valgrind=0 passes for at least four configs: config_LDB_low_complexity.txt, config_LDB_high_efficiency.txt, config_RA_medium_complexity.txt, config_HDB16_high_efficiency.txt.
• [ ] make check test-valgrind=1 passes for at least one config (slow but catches leaks).
• [ ] PSNR Y/U/V at QP 32 on a known reference clip is within ±0.05 dB of the previous release.
• [ ] Total bitrate at QP 32 on the same clip is within ±1% of the previous release.

5.4 Common operational errors

6. Performance

Thor is hand-tuned C99 with a v64/v128/v256 SIMD abstraction over native SSE/AVX2/NEON intrinsics, and a portable C fallback. Performance varies by configuration and hardware.

6.1 Encoder hot paths

The dominant cost in encoder time is mode/RDO search:

Tip

For real-time constrained encoding, the canonical preset is config_LDB_low_complexity.txt -encoder_speed 2 -snrcalc 0 -cdef 3. Disabling -snrcalc removes a per-frame full-frame walk; setting -encoder_speed 2 reduces RDO search depth across all coding decisions.

6.2 Decoder cost model

Decoder cost scales mostly with bitrate (more coded bits = more VLC parsing) and pixel rate (more pixels = more inverse transform / motion compensation work). It is significantly cheaper than the encoder. The hot paths are:

• decode_block_lbd() / decode_block_hbd() — per-block residual reconstruction. Branch-heavy.
• Inverse transform (common/transform.c).
• Motion compensation (common/inter_prediction.c — 6-tap luma, 4-tap chroma).
• In-loop filters: deblock → CDEF → CLPF in decode_frame.c.

6.3 Tuning knobs for throughput

6.4 Benchmarking methodology

Thor's per-frame stdout already reports PSNR Y/U/V and frame size in bits. To produce an RD curve:

for qp in 22 27 32 37; do
    ./build/Thorenc -cf config_RA_high_efficiency.txt \
        -if src_1920x1080.yuv -of /dev/null -width 1920 -height 1080 \
        -f 30 -n 300 -qp $qp \
        2>&1 | tee log_qp${qp}.txt
done

# Extract avg-PSNR-Y and bitrate for each QP
for qp in 22 27 32 37; do
    psnr=$(grep -E "Average" log_qp${qp}.txt | awk '{print $3}')
    rate=$(grep -E "Bitrate" log_qp${qp}.txt | awk '{print $2}')
    echo "qp=$qp psnr=$psnr rate=$rate"
done

Plot rate vs. PSNR; compare with x265 / libaom output on the same source at matching QP/CRF for a fair RD comparison.

7. Security

The Thor reference implementation is research-grade software. It is not hardened against adversarial input and should not be exposed to untrusted bitstreams without sandboxing. Cisco published the codec under a permissive 2-clause BSD license to advance video coding research; it does not include the input validation, fuzz infrastructure, or defensive coding that a production decoder requires.

Warning

Treat Thordec as you would a research C parser: assume any attacker-controlled .bit file can crash, hang, or corrupt memory in the decoding process. Run it inside a process boundary (bwrap --ro-bind, Docker, gVisor, seccomp-bpf) before parsing bitstreams from untrusted sources.

7.1 Known security issues

The upstream issue tracker explicitly lists several memory-safety problems in the reference decoder, all unresolved as of commit 18de8f9:

7.2 Input validation posture

Encoder: validates parameters in enc/strings.c:check_parameters(). The checks cover positive frame counts, multiple-of-8 dimensions, max_num_ref in [1, 4], max_delta_qp < 8, sub-GOP power-of-two with dyadic coding, sub-GOP divisibility of HQperiod and intra_period, encoder_speed = 2 when sync = 1, mutual exclusivity of bitrate and reordering, log2_sb_size in [6, 7], qmtx_offset in [-32, 31], subsample in {400, 420, 422, 444}, and bitdepth/input_bitdepth in {8, 10, 12}. The encoder calls fatalerror() and exits on violation.

Decoder: trusts the bitstream. The sequence header is read with get_flc(width_bits, stream) calls and clamped only for log2_sb_size (via clip(...) against MIN_BLOCK_SIZE/MAX_SB_SIZE). Width, height, max_num_ref, num_reorder_pics, and other fields are trusted as-is. This is the root cause of issues #30, #36–#40.

7.3 Recommended hardening for production use

If you must run Thor decode on untrusted bitstreams:

• Sandbox the process. Use seccomp-bpf to drop syscalls beyond read/write/mmap/munmap/exit_group. Run inside a minimal Docker container with read-only root and no network.
• Wall-clock cap. Wrap with timeout 60s ./build/Thordec ... to bound parser-spin attacks (issue #30).
• Memory cap. ulimit -v 1048576 (1 GB virtual memory) bounds malloc-bomb attempts.
• Filesystem cap. Run from a tmpfs with a strict size limit; the decoder can be coerced to write large outputs.
• Pre-parse with a hardened decoder. Validate the sequence header with a custom fuzzer-hardened parser before passing the bitstream to Thordec.

7.4 Recommended fuzz-test recipe

Use AFL or libFuzzer over Thordec's entry point:

# Build with AFL
CC=afl-gcc make -j8 ARCH=core2

# Seed corpus: a few small known-good .bit files
mkdir -p corpus
./build/Thorenc -cf config_LDB_low_complexity.txt \
    -if seed_640x360_30.yuv -of corpus/seed.bit \
    -width 640 -height 360 -f 30 -n 5 -qp 32

# Fuzz
afl-fuzz -i corpus -o findings -- ./build/Thordec @@ /dev/null

Caution

Fuzz output will produce crashes within minutes. The decoder's lack of defensive bounds checking means ~every malformed bitstream that survives the sequence header to reach a per-frame parse is a potential crash. Triaging crashes requires manual reduction; do not assume a crash is unique without afl-cmin and afl-tmin.

7.5 Untrusted-input handling rules of thumb

8. Developer Internals

8.1 Repository layout

thor/
├── Makefile               GNU make build
├── README.md              Brief usage hint
├── LICENSE                2-clause BSD
├── check.sh               Round-trip test driver
├── config_*.txt           30 preset configurations
├── build/                 Output dir (Makefile creates Thorenc/Thordec here)
├── common/                Shared code
│   ├── common_block.c/h   Block-level helpers, MV prediction, deblock
│   ├── common_block_hbd.c High-bit-depth variant
│   ├── common_frame.c/h   Frame buffer alloc/read/write
│   ├── common_frame_hbd.c HBD variant
│   ├── common_kernels.c/h Shared SIMD kernels (SAD/SSE/transform/MC/CDEF)
│   ├── common_kernels_gen.c    Generated HBD kernel templates
│   ├── common_kernels_hbd.c    HBD kernels
│   ├── common_tables.c    Static tables (zigzag, VLC, QM)
│   ├── global.h           MAX_QP, MAX_SB_SIZE, feature switches
│   ├── intra_prediction.c/h    Intra mode generators
│   ├── intra_prediction_hbd.c
│   ├── inter_prediction.c/h    6-tap luma, 4-tap chroma MC, OBMC
│   ├── inter_prediction_hbd.c
│   ├── simd.c/h           Portable SIMD entry points
│   ├── simd/              v64/v128/v256 wrappers (arm/c/x86)
│   ├── snr.c/h            PSNR Y/U/V
│   ├── snr_hbd.c
│   ├── temporal_interp.c/h     Synthetic interpolated reference frames
│   ├── temporal_interp_hbd.c
│   ├── transform.c/h      Forward + inverse DCT/DST
│   ├── types.h            Shared typedefs
│   └── wt_matrix.c/h      Quantisation matrix tables
├── dec/                   Decoder-only code
│   ├── decode_block.c/h
│   ├── decode_block_hbd.c
│   ├── decode_frame.c/h
│   ├── getbits.c/h        Bitstream reader (FLC)
│   ├── getvlc.c/h         VLC decoder
│   ├── maindec.c/h        main(); CLI = Thordec infile [outfile]
│   └── read_bits.c/h      Sequence header, frame header, block syntax parse
├── enc/                   Encoder-only code
│   ├── enc_kernels.c/h
│   ├── enc_kernels_gen.c
│   ├── enc_kernels_hbd.c
│   ├── encode_block.c/h
│   ├── encode_block_hbd.c
│   ├── encode_frame.c/h
│   ├── encode_frame_hbd.c
│   ├── encode_tables.c    Static encoder-only tables
│   ├── mainenc.c/h        main(); 70+ flag CLI; sub-GOP scheduling
│   ├── putbits.c/h        Bitstream writer (FLC)
│   ├── putvlc.c/h         VLC encoder
│   ├── rc.c/h             Per-superblock rate controller
│   ├── strings.c/h        parse_config_params, check_parameters
│   └── write_bits.c/h     Sequence header, frame header, block syntax write
└── scripts/
    └── lbd_to_hbd.sh      bash script to generate _hbd.c from _lbd.c

8.2 Bitstream syntax — sequence header

The sequence header is a fixed-length payload at the start of every bitstream, written by enc/write_bits.c:write_sequence_header() and read by dec/read_bits.c:read_sequence_header(). Field widths are bits.

Note

The subsample encoding is unusual. The 2-bit code maps as follows: bit 0 = (subsample & 4) == 4 (i.e. 4:?:?), bit 1 (when set with bit 0) selects 422 vs 444. The mapping 0=400, 1=420, 2=422, 3=444 is reconstructed in the decoder by (code & 1) * 20 + (code & 2) * 22 + ((code & 3) == 3) * 2 + 400.

8.3 Bitstream syntax — frame header

Written by enc/write_bits.c:write_frame_header() and read by dec/read_bits.c:read_frame_header().

8.4 Transform and quantisation

Block-coded residuals go through:

1. Forward transform (common/transform.c). Uses block-size-adaptive DCT/DST. Quantisation block size capped at MAX_QUANT_SIZE = 16 regardless of coding-block size.
2. Quantisation with optional per-block weight matrices (common/wt_matrix.c). NUM_QM_LEVELS = 12, WEIGHT_SHIFT = 6, INV_WEIGHT_SHIFT = 6.
3. Zigzag scan (zigzag16, zigzag64, zigzag256 tables in enc/encode_tables.c for 4x4, 8x8, 16x16 quant blocks).
4. VLC entropy code (enc/putvlc.c). Two coefficient modes: level-mode (CABAC-free fixed-length levels) and run-mode (run-length over zero coefficients).

The decoder mirrors this: VLC decode → inverse zigzag → inverse quantise (with QM if signalled) → inverse transform → add to predictor.

8.5 Motion estimation and compensation

• Motion compensation uses a 6-tap luma filter and a 4-tap chroma filter with quarter-pel precision (from common/inter_prediction.c). For high-bit-depth, the same filter taps run through common/inter_prediction_hbd.c.
• Up to 4 reference frames simultaneously (MAX_REF_FRAMES = 33 is the buffer cap; max_num_ref = 4 is the per-block cap).
• Skip mode allows up to MAX_NUM_SKIP = 2 candidates (LIMITED_SKIP define).
• Merge mode allows up to MAX_NUM_MERGE = 2 candidates.
• Synthetic interpolated references (when -interp_ref 1/2): build a virtual frame between two real references via common/temporal_interp.c:interpolate_frames(), signal it with ref_idx = -1.

8.6 In-loop filters

Three filters run in this order on each reconstructed frame:

1. Deblocking filter (common/common_block.c:deblock_frame_y() / deblock_frame_uv()). Toggled by -deblocking (default on). The NEW_DEBLOCK_FILTER, NEW_DEBLOCK_TEST, NEW_MV_TEST, and MODIFIED_DEBLOCK_TEST compile-time flags are all on by default.
2. CDEF (Constrained Directional Enhancement Filter). Per-superblock primary + secondary direction-aware filter inherited from AV1 research. Strength selection encoded via 4+1+2 bits per superblock. CDEF_BLOCKSIZE = 64, CDEF_PRI_STRENGTHS = 16, CDEF_SEC_STRENGTHS = 4.
3. CLPF (Constrained Low-Pass Filter). Optional follow-on filter with per-superblock or per-frame strength control. Strength capped by -max_clpf_strength (default 4).

8.7 Frame management — sub-GOP scheduling

enc/mainenc.c outer loop iterates over the input file in chunks of sub_gop = num_reorder_pics + 1 frames. Inside each chunk it picks frame types and reference structures:

• -num_reorder_pics 0: pure P-frame coding (and forced I at intra_period boundaries). Reference is always the most recent encoded frame, optionally a high-quality anchor every HQperiod frames.
• -num_reorder_pics > 0 with -dyadic_coding 1: hierarchical B with a dyadic structure. Sub-GOP sizes 2/4/8/16 (powers of two). The first frame of each sub-GOP is a P-frame; remaining frames are B-frames at b_level = log2(coded_phase + 1). Each B-level gets its own QP multiplier (mqpB0..mqpB3) and offset (dqpB0..dqpB3).
• -num_reorder_pics > 0 with -dyadic_coding 0: flat B coding (uniform QP across all B-frames).

The display ↔ coding order remap is in enc/encode_tables.c:dyadic_reorder_display_to_code[]. The decoder follows the same schedule by reading display_frame_num from each frame header and reordering its MAX_REORDER_BUFFER = 32 slot output buffer.

Note

The encoder removes duplicate references in mainenc.c after picking them — when two slots in ref_array[] resolve to the same frame number, the duplicate is dropped, so num_ref may shrink at runtime below max_num_ref. The encoder also drops references that crossed the most recent intra boundary (last_intra_frame_num) to preserve random-access semantics.

8.8 Code patterns and conventions

• HBD/LBD code duplication. Each high-bit-depth source file has a matching low-bit-depth source. The HBD versions are partially generated from the LBD versions via scripts/lbd_to_hbd.sh, which preprocesses #define SAMPLE and template-style macros. The TEMPLATE(name) macro in mainenc.c / maindec.c selects between _lbd and _hbd symbol pairs at runtime based on decoder_info.bitdepth == 8.
• No dynamic dispatch. Function pointers are used for SIMD kernels but not for codec tools. Tool toggling happens at the bitstream-syntax level (e.g., pb_split in the sequence header) and is read into fields of enc_params / decoder_info_t.
• Single-file main()s. Both mainenc.c and maindec.c hold the full encode/decode loop in a single main() — no abstract encoder/decoder objects. This is intentional for research readability.
• C99 with restrict. The codec uses restrict heavily on pointer parameters in inner loops to enable autovectorisation. With Visual Studio 2015, a compatibility shim #define restrict __restrict lives in common/global.h.
• static const tables. All large lookup tables (VLC, zigzag, weight matrices, intra mode predictors) are static const in common/common_tables.c and enc/encode_tables.c.

8.9 Testing strategy

• make check drives check.sh, which:
  1. Generates random YUV files at four resolutions (1920x1080, 1280x720, 640x480, 640x360) — or uses files passed via test-files=.
  2. Encodes each with the supplied config preset.
  3. Decodes the resulting bitstream.
  4. cmps the decoder output against the encoder's reconstructed buffer. A mismatch reports the offending frame number and exits.
• Optionally wraps each Thorenc and Thordec invocation in valgrind --leak-check=full --max-stackframe=5000000 --error-exitcode=123 (set test-valgrind=1).
• There is no unit-test suite. All testing is end-to-end round-trip.

8.10 Potential improvements (from upstream issue tracker)

8.11 Contributing guide

1. Fork the upstream repository.
2. Make changes in a topic branch off master.
3. Build with both gcc and clang at ARCH=core2 and ARCH=avx2 (and ARCH=neon if you have ARM hardware).
4. Run make check against at least two presets (LDB + RA).
5. Run make check test-valgrind=1 against one preset.
6. Verify that PSNR / bitrate doesn't regress on a known reference clip.
7. Open a pull request describing the change. Include the affected bitstream-syntax fields if any.

Note

Bitstream-changing patches must update both enc/write_bits.c and dec/read_bits.c in the same commit — otherwise the encoder and decoder disagree and check.sh will report mismatches. The make check step in CI catches this.

9. Integration Points

Thor is designed as a standalone CLI tool, but its file-based interface makes it integration-friendly.

9.1 Input integration

9.2 Output integration

9.3 No public C API

Thor does not expose a library API. There is no libthor.a, no libthor.so, no public header. The only programmatic interface is the CLI. Embedding Thor in a streaming pipeline means invoking the CLI as a subprocess.

9.4 No daemon / no network

Thor has no server mode, no socket interface, no HTTP API. Process lifecycle is one-shot per invocation. Running it under a job scheduler (systemd, Kubernetes Jobs, AWS Batch, Slurm) is the canonical deployment pattern.

9.5 Process boundary contract

Both binaries return exit code 0 on success, non-zero on any error.

Important

Both binaries call exit(1) (encoder via fatalerror() → abort() in some paths; decoder via rferror() → exit(1)) on any failure. They do not flush partial output on error. A wrapper script must clean up partial -of/-rf files itself.