Hardware_Acceleration

Hardware-Accelerated Transcoding

MSP v0.9.0+ introduces Hardware-Accelerated Transcoding support, leveraging GPU encoders to significantly improve transcoding speed and reduce CPU usage.

Overview

When enabled, MSP automatically probes available hardware encoders at startup and selects the best one for your system. If hardware acceleration is unavailable or fails, MSP seamlessly falls back to software encoding (libx264) without interruption.

Supported Hardware Encoders

Encoder	Platform	Hardware	Notes
h264_nvenc	Windows / Linux	NVIDIA GPU	Requires NVIDIA driver
h264_qsv	Windows / Linux / macOS	Intel Quick Sync	Integrated graphics
h264_amf	Windows	AMD GPU	AMD AMF framework
h264_vaapi	Linux	VA-API	VAAPI drivers required
h264_videotoolbox	macOS	Apple VideoToolbox	macOS native API

Configuration

Add the encoding section to your config.json:

{
  "playback": {
    "video": {
      "encoding": {
        "hwAccel": "auto",
        "maxJobs": 0
      }
    }
  }
}

Configuration Options

hwAccel (String)

Hardware acceleration mode. Default: "auto".

• "auto" — Recommended. Auto-probe and use the best available hardware encoder. Falls back to software if none found.
• "none" — Disable hardware acceleration. Always use libx264 software encoding.
• "nvenc" — Force NVIDIA NVENC encoder.
• "qsv" — Force Intel Quick Sync Video encoder.
• "amf" — Force AMD AMF encoder.
• "vaapi" — Force VA-API encoder (Linux only).
• "videotoolbox" — Force Apple VideoToolbox encoder (macOS only).

maxJobs (Integer)

Maximum number of concurrent transcode sessions. Default: 0 (auto).

• 0 — Auto mode:
  • Software encoding: 2 concurrent sessions
  • Hardware encoding: 4 concurrent sessions
• >0 — Manually specify the limit (e.g., 8 for more powerful GPUs)

Behavior

Startup Probe

1. When hwAccel="auto", MSP checks for available hardware encoders.
2. If multiple encoders are present, MSP selects the most efficient one.
3. The selected encoder is logged at startup for debugging.

Runtime Fallback

• If hardware encoding fails during runtime (e.g., GPU driver crash), MSP marks it as unavailable.
• Subsequent requests automatically fall back to software encoding.
• No manual intervention required.

Performance

Hardware acceleration provides:

• Lower CPU Usage: GPU handles the encoding workload.
• Higher Speed: Real-time transcoding even for high-bitrate content.
• More Concurrent Sessions: Default raised from 2 (software) to 4 (hardware).

Examples

Example 1: Auto-Detect (Recommended)

Let MSP choose the best encoder automatically:

{
  "playback": {
    "video": {
      "encoding": {
        "hwAccel": "auto",
        "maxJobs": 0
      }
    }
  }
}

Example 2: Force Specific Encoder

Force NVIDIA NVENC on a multi-GPU system:

{
  "playback": {
    "video": {
      "encoding": {
        "hwAccel": "nvenc",
        "maxJobs": 8
      }
    }
  }
}

Example 3: Disable Hardware Acceleration

Use software encoding only (for debugging or compatibility):

{
  "playback": {
    "video": {
      "encoding": {
        "hwAccel": "none",
        "maxJobs": 2
      }
    }
  }
}

Troubleshooting

Q: How do I know if hardware acceleration is working?

Check the server log at startup. You should see a message like:

[INFO] Hardware encoder enabled: h264_nvenc

Q: Can I force a specific encoder?

Yes, set hwAccel to the desired encoder name (e.g., "nvenc", "qsv").

Q: What if my GPU driver is outdated?

MSP will fail to initialize the hardware encoder and automatically fall back to software encoding. Update your GPU drivers for best results.

Q: Does hardware acceleration affect quality?

Modern hardware encoders (NVENC, QSV, Videotoolbox) provide excellent quality at reasonable bitrates. For most home media streaming scenarios, the quality difference from software encoding is negligible.

Compatibility Notes

• Older Configs: If upgrading from v0.8.x, MSP automatically adds the encoding field with default values (hwAccel="auto", maxJobs=0).
• No GPU Systems: Systems without hardware encoders behave identically to v0.8.x (libx264 fast preset).
• Multi-GPU Systems: MSP selects the primary GPU by default. Use hwAccel to manually specify if needed.