Unify hardware decoding through DecoderOptions

[mcuadros]

Summary

• Route hardware acceleration through the normal Decoder and DecoderOptions.
• Discover compatible hardware decoders and device configurations from FFmpeg capabilities.
• Prefer platform-native devices while allowing automatic software fallback or required hardware mode.
• Propagate decoder options through network and image-sequence constructors.
• Expose decoder selection and fallback diagnostics through VideoDecoderInfo.
• Reuse automatically created hardware devices by device type.
• Extend the PureGo bindings and ABI layout checks required for codec and hardware configuration discovery.
• Add policy, ownership, lifecycle, fallback, and stress coverage.

Behavior

DecoderOptions.Hardware controls video hardware acceleration:

• nil keeps software decoding.
• &HWDecoderConfig{} enables automatic platform-aware selection with software fallback.
• HardwareAccelerationRequired returns ErrHardwareAccelerationUnavailable instead of falling back.
• HardwareAccelerationDisabled explicitly requests software decoding.
• Caller-provided HWDevice values are borrowed; automatically created devices are owned by the decoder.

Frames returned by the regular decoder API remain CPU-accessible. GPU-backed frames are transferred to reusable system memory, while wrapper decoders that already return CPU-backed frames avoid that transfer.

VideoDecoderInfo reports pending, selected, active, and fallback states because some FFmpeg accelerators initialize lazily during the first decode operation.

Breaking changes

The separate HWDecoder API and NewHWDecoder constructor are removed. Hardware acceleration now uses the regular decoder:

decoder, err := ffmpeg.NewDecoder(path, &ffmpeg.DecoderOptions{
    Hardware: &ffmpeg.HWDecoderConfig{},
})

Specialized constructors now receive normal decoder options separately from their specific configuration:

ffmpeg.NewNetworkDecoder(url, decoderOptions, protocolOptions)
ffmpeg.NewNetworkDecoderContext(ctx, url, decoderOptions, protocolOptions)
ffmpeg.NewImageSequenceDecoder(sequenceConfig, decoderOptions)

This keeps stream selection, probing, raw FFmpeg options, and hardware policy consistent across decoder entry points.

Validation

• go test ./...
• go test -race ./...
• go vet ./...
• golangci-lint 1.64.8
• Windows amd64/arm64 cross-compilation
• Darwin amd64/arm64 cross-compilation
• Android API 33 arm64/amd64 cross-compilation
• ABI layout validation against FFmpeg 6.0.1, 6.1.6, 7.0.3, 7.1.5, 8.0.3, 8.1.2, and 9.0.1
• Runtime decoding tests across the supported FFmpeg release families
• ASan/UBSan validation with FFmpeg 6.1.6, 7.1.5, and 8.1.2
• Repeated automatic-selection lifecycle stress
• Physical Android playback with MediaCodec active, including audio, pause, seek, loop, fallback diagnostics, and A/V synchronization

Network option merging and cancellation routing are covered deterministically. The test suite does not depend on an external streaming service.