Troubleshooting

Common issues and their solutions.

Connection Issues

Unable to connect to server

Symptom: Connection refused or timeout. Checks:

1. Reachability: Can you ping the Mac’s IP from the client?
2. Firewall: Ensure the macOS firewall allows incoming TCP connections to vtremoted (port 5555).
3. Port: Verify vtremoted is running and listening on 0.0.0.0 (not just localhost).

Auth Failure

Symptom: Server closes connection immediately with an error. Solution: Ensure the token on the client matches the server’s --token.

Performance Issues

Low Throughput / Dropped Frames

Symptom: Encoding speed is below real-time or choppy. Solutions:

• Network: Use wired LAN (1GbE+). Wi-Fi is often too unstable for raw frame streaming.
• Optimization:
  • Increase in-flight frames: -vt_remote_inflight 32
  • Or let it adapt: -vt_remote_inflight auto
  • Use Transcode mode (-vt_remote_transcode) to reduce network load.
• Compression: Ensure wire compression is enabled. Default is LZ4. Override with -vt_remote_wire_compression lz4|zstd|none, or use auto to pick based on resolution/FPS.

High Latency

Symptom: Delay in live streaming. Solution: Use -realtime 1 on the client to tell the server to prioritize latency over throughput.

Build & Installation

“Codec not found”

Cause: FFmpeg build used does not include the remote codecs. Solution:

• Ensure you are running the ffmpeg binary from ffmpeg/.
• Reconfigure with --enable-videotoolbox-remote.

Linux build fails in FFmpeg x86 assembly

Symptom: The build fails in an FFmpeg x86 assembly file, or the error mentions nasm, yasm, or an unsupported x86 instruction. Checks:

1. Confirm you are building on 64-bit Linux:

   uname -m
   

   Supported Linux release artifacts target x86_64, not 32-bit i686.

2. Install current assemblers:

   nasm -v
   yasm --version
   

3. Clean and rebuild after installing them:

   make clean-ffmpeg
   make build-ffmpeg
   

4. If the failure persists, confirm it is isolated to x86 assembly with the compatibility fallback:

   make clean-ffmpeg
   make build-ffmpeg FFMPEG_DISABLE_X86ASM=1
   

FFMPEG_DISABLE_X86ASM=1 appends --disable-x86asm. It can reduce FFmpeg performance, so use it as a diagnostic or compatibility fallback rather than the default build.

macOS Build Fails

Error: videotoolbox requested, but not all dependencies are satisfied. Solution:

• Ensure Xcode command line tools are active: xcode-select -p.
• Build with SDK path explicitly:

  SDKROOT="$(xcrun --sdk macosx --show-sdk-path)" make build-ffmpeg
  

Verify a running macOS server after upgrade

Symptom: Multiple vtremoted processes are running, or a LaunchAgent and LaunchDaemon point at different binaries. Solution:

1. Check the packaged binary:

   vtremoted --version
   

2. Check launchd state:

   launchctl print "gui/$(id -u)/com.davelindon.vtremoted"
   

   For a system LaunchDaemon, use:

   sudo launchctl print system/com.davelindon.vtremoted
   

3. Check listeners and process paths:

   pgrep -fl vtremoted
   lsof -nP -iTCP:5555 -sTCP:LISTEN
   

4. If using the Makefile install path, rebuild, reinstall, restart, and verify with:

   make install-vtremoted-restart VTREMOTED_LISTEN=<MAC_PRIVATE_IP>:5555
   

Encoding/Decoding

Slow HEVC 10-bit Encoding

Context: 10-bit HEVC is compute-intensive. Expect ~200 fps at 1080p and ~60 fps at 4K on Apple Silicon (loopback). Over a real network, throughput depends on bandwidth and latency. Diagnosis: If max_inflight stays low (e.g., < 5), the bottleneck is the Mac’s hardware encoder, not the network.