# RK1 media stack

This directory builds an ARM64-only Kodi/GBM appliance stack for an RK3588
running Armbian Debian 13 (Trixie) with the Rockchip vendor 6.1 kernel. All
third-party inputs are immutable Git commits recorded in `sources.lock.json`.
The result is a Debian package whose custom libraries and programs live under
`/opt/rkmedia`; it does not replace Debian's FFmpeg or Kodi packages.

## Why the compatibility MPP and RGA branches are pinned

The current `kodi-rockchip-deb` recipe uses nyanmisaka's `jellyfin-mpp` and
`jellyfin-rga` branches. FFmpeg-Rockchip 8.1 checks for MPP package version
1.3.9 and the `mpp_buffer_sync_begin_f` symbol, and checks the RGA APIs
`c_RkRgaBlit` and `querystring`. These exact branches satisfy that interface.
The official Rockchip MPP/RGA heads inspected when this lock was generated are
recorded as reference metadata, but are deliberately not substituted into the
matched build without a complete hardware regression run.

## Build

Run this on an aarch64 Debian Trixie installation. The native build is large and
can take several hours.

```sh
sudo ./scripts/install-build-deps.sh --install
./scripts/build-media.sh
```

Outputs are written to `out/` by default:

- `rk1-media-stack_<version>_arm64.deb`
- an unpacked `stage/` tree for inspection
- cloned, detached source trees and component build directories

Useful options:

```sh
./scripts/fetch-sources.sh --dest /path/to/sources
./scripts/build-media.sh --source-dir /path/to/sources --work-dir /path/to/work --output-dir /path/to/output --jobs 8
./scripts/build-media.sh --no-fetch
```

Set `RKMEDIA_ALLOW_UNSUPPORTED_HOST=1` only for development. Packages built on
anything other than Trixie are unsupported because their generated shared
library dependencies will describe the build host, not the target image.

## Fast candidate repack

For image composition and hardware validation, the pinned July 2026 upstream
Trixie package can be deterministically repacked in a few minutes instead of
performing the multi-hour native compile:

```sh
./scripts/repack-upstream-deb.sh
```

The script downloads the exact asset in `upstream-deb.lock.json`, verifies its
size and SHA-256 before extraction, removes approximately 270 MB of static
FFmpeg archives and all development pkg-config files, and emits the same
`rk1-media-stack` package format. Kodi remains at `/usr/local`, its compiled
prefix. FFmpeg, FFprobe, MPP, RGA, dav1d, and display-info move under
`/opt/rkmedia`; the launcher supplies the corresponding library path.

Use `--deb PATH` to repack an already-downloaded copy without network access.
The prebuilt asset is reproducible as an input but its original recipe used
moving source branches; its verified asset digest, rather than reconstructed
Git commit guesses, is the provenance boundary.

## Install and operate

Install with APT so runtime dependencies are resolved:

```sh
sudo apt install ./rk1-media-stack_<version>_arm64.deb
sudo systemctl enable --now kodi-rk.service
```

The package creates a locked `kodi` system account, grants it only the existing
`video`, `render`, `audio`, and `input` group memberships, and gives it persistent
state under `/var/lib/kodi`. Kodi takes DRM master on tty1, so a display manager
or another program holding the KMS device must not be active.

The service is enabled during package configuration but is not started inside
an image-build chroot. Edit `/etc/rkmedia/kodi.env` for supported environment
overrides, then restart `kodi-rk.service`.

The following commands are exposed without replacing system FFmpeg:

```sh
ffmpeg-rk -hide_banner -decoders
ffmpeg-rk -hide_banner -encoders
ffmpeg-rk -hide_banner -filters
ffprobe-rk media-file.mkv
```

Expected hardware entries include `h264_rkmpp`, `hevc_rkmpp`, `vp9_rkmpp`,
`av1_rkmpp`, `mjpeg_rkmpp`, and the `scale_rkrga`, `vpp_rkrga`, and
`overlay_rkrga` filters. Runtime access is provided through conservative udev
rules for the DRM, dma-heap, RGA, IEP, VPU, and MPP device nodes.

## Boundaries

- The package does not install or select the kernel, device tree, Panthor
  overlay, Mesa, firmware, or bootloader. Those belong to the parent image.
- The package does not claim HDMI link, HDR, passthrough, or codec acceptance;
  those require testing on the actual RK1/carrier/TV combination.
- Kodi is pinned to a mainline commit because the current Rockchip GBM work is
  newer than a stable Kodi release. Update the lock only as a tested set.