# Linux Video Playback Checklist

Use this checklist on Linux machines where video playback or frame stepping feels
slow or sluggish.

## Baseline Packages

Install or update the common runtime and diagnostic tools:

```bash
sudo apt update
sudo apt full-upgrade
sudo apt install ffmpeg ffprobe vainfo vdpauinfo mesa-utils vulkan-tools
```

Make sure the user has access to GPU render devices:

```bash
sudo usermod -aG render,video $USER
```

Log out and back in after changing groups.

## Tauri / WebKit Runtime

For Debian or Ubuntu systems:

```bash
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1
```

## Intel GPU

For newer Intel integrated GPUs:

```bash
sudo apt install intel-media-va-driver intel-media-va-driver-non-free va-driver-all
```

If VAAPI fails, try launching with:

```bash
LIBVA_DRIVER_NAME=iHD ./sam-tool
```

For older Intel GPUs:

```bash
sudo apt install i965-va-driver
LIBVA_DRIVER_NAME=i965 ./sam-tool
```

## AMD GPU

Use Mesa VAAPI / VDPAU drivers:

```bash
sudo apt install mesa-va-drivers mesa-vdpau-drivers va-driver-all
```

In the app, prefer `VAAPI`.

## NVIDIA GPU

Use the proprietary NVIDIA driver, not Nouveau, for best decode support:

```bash
sudo ubuntu-drivers autoinstall
sudo reboot
```

After reboot:

```bash
nvidia-smi
ffmpeg -hide_banner -hwaccels
```

In the app, prefer `CUDA`. Try `VDPAU` only as a fallback.

## GStreamer / WebKit Video Stack

These packages are useful for WebKit video support, especially if native
`<video>` playback is used:

```bash
sudo apt install \
  gstreamer1.0-libav \
  gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad \
  gstreamer1.0-plugins-ugly \
  gstreamer1.0-vaapi
```

## Verification Commands

Check available acceleration support:

```bash
ffmpeg -hide_banner -hwaccels
vainfo
vdpauinfo
ls -l /dev/dri/renderD*
```

Test VAAPI:

```bash
ffmpeg -v verbose -hwaccel vaapi -vaapi_device /dev/dri/renderD128 -i input.mp4 -f null -
```

Test NVIDIA CUDA:

```bash
ffmpeg -v verbose -hwaccel cuda -i input.mp4 -f null -
```

## App Settings

Recommended hardware decode setting:

- Intel / AMD: `VAAPI`
- NVIDIA: `CUDA`
- Unknown or mixed systems: `auto`
- If unstable: `software`

## WebKit Workaround

On machines where WebKit or the Intel iGPU compositor is the bottleneck, try:

```bash
WEBKIT_DISABLE_COMPOSITING_MODE=1 ./sam-tool
```

This disables WebKit accelerated compositing and can improve playback on some
Linux systems.