performance improvement

sam-tool-tauri/docs/LINUX_VIDEO_PLAYBACK_CHECKLIST.md

@@ -0,0 +1,137 @@
+# 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.