Class CommonNVENCSettings

Namespace: VisioForge.Core.Types.FFMPEGEXE

Assembly: VisioForge.Core.dll

Common NVIDIA NVENC hardware encoder settings for FFMPEG.

public class CommonNVENCSettings : BasicVideoSettings

Inheritance

object

IBasicVideoSettings

BasicVideoSettings

CommonNVENCSettings

Derived

H264NVENCSettings

HEVCNVENCSettings

Inherited Members

Examples

var nvencSettings = new CommonNVENCSettings
{
    Encoder = VideoEncoder.H264_NVENC,
    Preset = NVENCPreset.LowLatencyHP,
    RateControl = NVENCRateControl.VBR,
    Bitrate = 6000,
    MaxBitrate = 8000,
    RCLookahead = 32,
    BRefMode = NVENCBRefMode.Middle
};
// Generates: -c:v h264_nvenc -preset llhp -rc vbr -b:v 6M -maxrate 8M -rc-lookahead 32

Remarks

This class provides comprehensive configuration for NVIDIA's NVENC hardware video encoding engine when used through FFMPEG. NVENC is NVIDIA's dedicated hardware encoder present on GeForce GTX 600 series and newer GPUs, offering high-performance H.264 and H.265 encoding with minimal CPU usage.

NVENC encoders in FFMPEG:

h264_nvenc: H.264/AVC encoding using NVIDIA NVENC
hevc_nvenc: H.265/HEVC encoding using NVIDIA NVENC

Key advantages of NVENC:

Hardware acceleration reduces CPU load to near zero
Real-time encoding of multiple streams (varies by GPU model)
Low latency modes for streaming and video conferencing
B-frame support and advanced rate control options

GPU encoding session limits:

GeForce cards: 3 concurrent sessions (driver 378.66+)
Quadro/Tesla cards: Unlimited sessions

Constructors

CommonNVENCSettings()

Initializes a new instance of the VisioForge.Core.Types.FFMPEGEXE.CommonNVENCSettings class.

public CommonNVENCSettings()

Properties

AUD

Gets or sets a value indicating whether to insert Access Unit Delimiters.

public bool AUD { get; set; }

Property Value

bool

Remarks

Access Unit Delimiters (AUD) are NAL units that mark the beginning of access units (complete frames) in the H.264/HEVC bitstream. They aid in stream parsing and synchronization.

FFMPEG option: -aud 1

Purpose:

Clearly marks frame boundaries in the bitstream
Helps decoders resynchronize after errors
Required by some broadcast standards (ATSC, DVB)
Assists in stream splicing and editing

When to enable:

Broadcast workflows requiring standard compliance
Streams that may be concatenated or edited
Transport streams (MPEG-TS) for better compatibility
When debugging stream parsing issues

Impact:

Minimal bitrate increase (few bytes per frame)
No quality or performance impact
Improves stream robustness and compatibility

BAdapt

Gets or sets a value indicating whether adaptive B-frame placement is enabled.

public bool BAdapt { get; set; }

Property Value

bool

Remarks

Adaptive B-frame decision allows NVENC to dynamically choose the optimal number and placement of B-frames based on content analysis when lookahead is enabled. B-frames improve compression by referencing both past and future frames.

FFMPEG option: -b_adapt 0 (to disable)

When true (default):

NVENC analyzes motion and complexity to place B-frames optimally
Better compression efficiency, especially for content with motion
May use 0-2 B-frames as needed per GOP section

When false:

Fixed B-frame pattern based on -bf setting
More predictable frame structure
Lower latency for live applications

Requirements: RCLookahead > 0 for adaptive mode to work For lowest latency streaming, set both BAdapt and B-frames to 0.

BRefMode

Gets or sets B-frame reference mode for hierarchical B-frame structures.

public NVENCBRefMode BRefMode { get; set; }

Property Value

NVENCBRefMode

Remarks

Controls how B-frames can be used as references for other frames, enabling hierarchical B-frame pyramids for better compression efficiency. More complex reference structures improve quality but may impact compatibility.

FFMPEG option: -b_ref_mode [disabled|each|middle]

Modes:

Disabled: B-frames cannot be referenced (traditional IBBPBBP) Best compatibility, lowest compression gain
Each: Each B-frame can be referenced by others Maximum compression efficiency, complex dependencies
Middle: Only middle B-frame in pyramid can be referenced Balanced compression and complexity

Impact:

5-15% bitrate reduction with hierarchical B-frames
Slightly increased decode complexity
May affect seeking granularity

Recommended: 'Middle' for most use cases, 'Disabled' for maximum compatibility with older decoders.

BluRayCompatibility

Gets or sets a value indicating whether to apply BluRay compatibility constraints.

public bool BluRayCompatibility { get; set; }

Property Value

bool

Remarks

Enables encoding constraints to ensure compatibility with BluRay disc specifications. This affects various encoder parameters to meet BluRay authoring requirements.

FFMPEG option: -bluray-compat 1

BluRay constraints applied:

Maximum bitrate: 40 Mbps for 1080p, 15 Mbps for 720p
Specific level constraints (4.1 for 1080p)
GOP structure requirements (closed GOPs)
Frame rate limitations (23.976, 24, 25, 29.97, 50, 59.94)
Restricted slice and reference frame counts
VBV buffer size compliance

Additional requirements:

Use YUV 4:2:0 color space
8-bit color depth only
Specific aspect ratios (16:9, 4:3)

Note: Enabling this may reduce encoding efficiency but ensures the output can be authored to BluRay without re-encoding.

ConstantQuality

Gets or sets target quality level (0 to 51, 0 means automatic) for constant quality mode.

public int ConstantQuality { get; set; }

Property Value

int

Remarks

Specifies the target quality when using constant quality (CQ) or constrained quality (VBR_MINQP) rate control modes. Lower values mean higher quality.

FFMPEG option: -cq [0-51]

Quality scale:

0: Automatic (encoder decides based on bitrate/preset)
1-18: Visually lossless to excellent quality
19-23: High quality (recommended for most use cases)
24-27: Good quality (balanced size/quality)
28-35: Acceptable quality (smaller files)
36-51: Low quality (maximum compression)

Usage by rate control mode:

With RateControl.CQ: Pure constant quality encoding
With RateControl.VBR_MINQP: Minimum quality guarantee
With other modes: Usually ignored

For streaming, use with VBR_MINQP to ensure minimum quality. For archival, use with CQ mode for consistent quality.

DPBSize

Gets or sets the Decoded Picture Buffer size (0 for automatic).

public int DPBSize { get; set; }

Property Value

int

Remarks

DPB (Decoded Picture Buffer) size determines how many reference frames the encoder can keep in memory for inter-frame prediction. Larger DPB allows more references, improving compression at the cost of memory usage.

FFMPEG option: -dpb_size [frames]

Typical values:

0: Automatic (based on level and resolution)
1-4: Low latency, minimal memory usage
5-8: Balanced quality and memory (common default)
9-16: High quality, more memory required

Constraints:

Limited by H.264/HEVC level specifications
Must not exceed decoder capabilities
Affects both encoder and decoder memory usage

Benefits of larger DPB:

Better motion prediction over longer distances
Improved quality for content with repetitive motion
More effective for high-resolution content

Note: Increasing DPB size has diminishing returns; most benefit comes from the first 4-6 reference frames.

ForcedIDR

Gets or sets a value indicating whether forced keyframes should be IDR frames.

public bool ForcedIDR { get; set; }

Property Value

bool

Remarks

IDR (Instantaneous Decoder Refresh) frames are special I-frames that clear the reference buffer, ensuring no future frames reference frames before the IDR. This guarantees a clean random access point for seeking or stream switching.

FFMPEG option: -forced-idr 1

IDR vs regular I-frames:

IDR frames: Complete refresh, no references to previous frames
Regular I-frames: May reference earlier frames for prediction

When to use:

True: For HLS/DASH streaming requiring clean segment boundaries
True: When implementing ad insertion points
False: For general encoding where seeking flexibility is less critical

Impact: IDR frames typically require more bits than regular I-frames but provide guaranteed random access points.

GPUIndex

Gets or sets GPU index to use for encoding, starting from zero.

public int GPUIndex { get; set; }

Property Value

int

Remarks

Specifies which NVIDIA GPU to use when multiple GPUs are present in the system. This is crucial for load balancing in multi-GPU setups or when specific GPUs are designated for encoding tasks.

FFMPEG option: -gpu [index]

GPU enumeration:

0: First NVIDIA GPU (default)
1, 2, ...: Additional GPUs in order detected by driver
-1: Auto-select least loaded GPU (if supported)

Use cases:

Dedicated encoding GPU in workstations
Load distribution across multiple GPUs
Avoiding conflict with display GPU

To list available GPUs in FFMPEG: ffmpeg -f lavfi -i nullsrc -c:v h264_nvenc -gpu list -f null -

InitQP_B

Gets or sets initial quantization parameter for B-frames (-1 for auto, 0-51 for manual).

public int InitQP_B { get; set; }

Property Value

int

Remarks

Sets the starting QP for B-frames (bidirectional predicted frames). B-frames typically use higher QP than I/P frames since they're less critical for quality and benefit from predictions from both directions.

FFMPEG option: -init_qpB [value]

Typical QP relationships:

B-frame QP = P-frame QP + 2 to 4 (common default)
Allows more compression on B-frames
Viewers less sensitive to B-frame quality

Strategy:

-1: Let encoder manage (recommended)
Manual: Set 2-4 points higher than InitQP_P
For quality priority: Keep close to P-frame QP
For size priority: Increase gap to P-frame QP

Impact: B-frames are not referenced by other frames, so higher compression here doesn't propagate errors through GOP.

InitQP_I

Gets or sets initial quantization parameter for I-frames (-1 for auto, 0-51 for manual).

public int InitQP_I { get; set; }

Property Value

int

Remarks

Sets the starting QP for I-frames (intra-coded keyframes). I-frames are critical reference frames that don't depend on other frames, so they typically receive the highest quality (lowest QP) allocation.

FFMPEG option: -init_qpI [value]

I-frame importance:

Serve as reference for entire GOP
Quality affects all dependent P/B frames
Random access points for seeking
Usually 10-50% of total bitrate

Recommended strategies:

-1: Automatic based on rate control (recommended)
High quality: Set 3-5 points lower than P-frames
Consistent: Set equal to P-frames
Never set higher than P-frames (degrades entire GOP)

For streaming: Lower I-frame QP improves quality after seek/buffering. For storage: Balance with P/B frames for consistent quality.

InitQP_P

Gets or sets initial quantization parameter for P-frames (-1 for auto, 0-51 for manual).

public int InitQP_P { get; set; }

Property Value

int

Remarks

Sets the starting QP (Quantization Parameter) for P-frames at the beginning of encoding or after scene changes. QP directly controls compression level: lower values = higher quality/bitrate, higher values = lower quality/bitrate.

FFMPEG option: -init_qpP [value]

Values:

-1: Automatic (encoder decides based on rate control)
0-15: Very high quality, large file size
16-25: High quality, typical for high-bitrate encoding
26-35: Medium quality, balanced size/quality
36-51: Lower quality, maximum compression

Use cases:

Set all InitQP values equal for consistent initial quality
Set P-frame QP slightly higher than I-frame for bitrate savings
Leave at -1 for rate control to manage automatically

Note: Only affects initial frames; rate control adjusts QP dynamically afterward based on target bitrate and buffer fullness.

NoSceneCut

Gets or sets a value indicating whether adaptive I-frame insertion at scene cuts is disabled.

public bool NoSceneCut { get; set; }

Property Value

bool

Remarks

When lookahead is enabled, NVENC can detect scene changes and automatically insert I-frames for better quality and seeking. This setting controls that behavior.

FFMPEG option: -no-scenecut 1

When false (default):

NVENC analyzes frames for scene changes
Inserts I-frames at scene boundaries for better quality
Improves seeking accuracy in the encoded file
May cause slight bitrate spikes at scene changes

When true:

I-frames only inserted at fixed GOP intervals
More predictable bitrate and GOP structure
Required for some streaming protocols with strict GOP requirements
May reduce quality at scene transitions

Note: Only effective when RCLookahead > 0

NonRefP

Gets or sets a value indicating whether automatic insertion of non-reference P-frames is enabled.

public bool NonRefP { get; set; }

Property Value

bool

Remarks

Non-reference P-frames are predicted frames that are not used as references for other frames. They can be dropped without affecting subsequent frame decoding, making streams more resilient to packet loss.

FFMPEG option: -nonref_p 1

Benefits:

Improved error resilience for streaming (frames can be dropped)
Slightly better compression (fewer reference frames to store)
Reduced decoder complexity and memory usage

How it works:

Some P-frames marked as non-reference
Following frames cannot reference these frames
Creates natural recovery points in the stream

Ideal for:

Streaming over unreliable networks
Live broadcasts where frame drops are preferable to buffering
Mobile streaming with variable bandwidth

Note: May slightly reduce quality as fewer references are available.

Preset

Gets or sets the NVENC encoding preset that balances quality and performance.

public NVENCPreset Preset { get; set; }

Property Value

NVENCPreset

Remarks

NVENC presets control the trade-off between encoding speed and compression efficiency. Unlike CPU encoders, NVENC presets mainly affect quality rather than speed, as the hardware encoder operates at a fixed performance level.

Common presets (from fastest/lowest quality to slowest/highest quality):

P1 (fastest): Lowest quality, maximum performance
P2-P6: Progressively higher quality
P7 (slowest): Maximum quality, may impact real-time performance
LowLatencyHP: Optimized for streaming with B-frames disabled
LowLatencyHQ: Higher quality low-latency mode

FFMPEG mapping: -preset [p1|p2|...|p7|slow|medium|fast|hp|hq|ll|llhp|llhq]

For live streaming, use LowLatencyHP or LowLatencyHQ. For file encoding where latency doesn't matter, use P5-P7 for best quality.

QP

Gets or sets constant quantization parameter for CQP rate control (-1 auto, 0-51 manual).

public int QP { get; set; }

Property Value

int

Remarks

When using Constant QP (CQP) rate control mode, this sets a fixed quantization parameter for all frames. Unlike other rate control modes, CQP doesn't target a specific bitrate but maintains consistent quality.

FFMPEG option: -qp [value] (with -rc constqp)

Quality levels:

0: Lossless (if supported by profile)
1-15: Visually lossless to excellent
16-23: High quality (recommended range)
24-30: Good quality, reasonable file sizes
31-40: Acceptable quality, smaller files
41-51: Low quality, maximum compression

Use cases:

Quality-critical encoding where bitrate can vary
Intermediate files for further processing
Benchmarking and encoder testing
When consistent visual quality matters more than file size

Note: Produces highly variable bitrate; not suitable for streaming.

RCLookahead

Gets or sets number of frames to look ahead for rate-control (from 0 to Int32.Max).

public int RCLookahead { get; set; }

Property Value

int

Remarks

Lookahead enables the encoder to analyze future frames before making bitrate decisions, resulting in better quality and more consistent bitrate. This is especially effective for scenes with varying complexity.

FFMPEG option: -rc-lookahead [frames]

Recommended values:

0: Disabled (lowest latency, suitable for real-time streaming)
16-32: Good balance for most content
32-60: Maximum quality for VOD content

Impact:

Higher values improve quality but increase latency and memory usage
Enables better scene change detection and adaptive B-frame placement
Works best with VBR rate control modes

Note: Lookahead frames are buffered in GPU memory, so very high values may cause issues on GPUs with limited VRAM.

RateControl

Gets or sets the rate control algorithm for bitrate management.

public NVENCRateControl RateControl { get; set; }

Property Value

NVENCRateControl

Remarks

Rate control determines how NVENC distributes bits across frames to achieve target bitrate or quality. Different modes suit different use cases:

CQ (Constant Quantizer): Fixed quality per frame, variable bitrate FFMPEG: -rc constqp -qp [value]
VBR (Variable Bitrate): Varies bitrate based on complexity, best quality FFMPEG: -rc vbr -b:v [target] -maxrate [max] -bufsize [buffer]
CBR (Constant Bitrate): Fixed bitrate for streaming compatibility FFMPEG: -rc cbr -b:v [bitrate] -bufsize [bitrate*2]
VBR_MINQP: VBR with minimum quality guarantee FFMPEG: -rc vbr_minqp -qmin [min] -qmax [max]

For streaming use CBR or capped VBR. For local storage or VOD, use VBR or CQ for optimal quality. CBR requires appropriate bufsize setting.

SpatialAQ

Gets or sets a value indicating whether Spatial Adaptive Quantization is enabled.

public bool SpatialAQ { get; set; }

Property Value

bool

Remarks

Spatial AQ adjusts quantization parameters within each frame based on spatial complexity and visual importance. It allocates more bits to detailed areas (edges, textures) and fewer bits to flat regions (sky, walls).

FFMPEG option: -spatial-aq 1

Benefits:

Improves perceived quality by preserving detail where it matters
Reduces bits in areas where compression artifacts are less visible
Particularly effective for content with mixed complexity

Best for:

General video content with varying detail levels
Gaming content with HUD elements and gameplay areas
Presentations with text and graphics

May not be ideal for:

Content requiring uniform quality (medical imaging)
Very low bitrate encoding where every bit counts

Use with SpatialAQStrength to control the intensity of adjustments.

SpatialAQStrength

Gets or sets Spatial AQ strength from 1 (subtle) to 15 (aggressive), default 8.

public int SpatialAQStrength { get; set; }

Property Value

int

Remarks

Controls how aggressively Spatial Adaptive Quantization adjusts quality across different regions of the frame. Higher values create more dramatic differences between detailed and flat areas.

FFMPEG option: -aq-strength [1-15]

Value guidelines:

1-3: Subtle adjustments, nearly uniform quality
4-6: Mild adaptation, good for high-quality encoding
7-9: Moderate adaptation, balanced for most content (default: 8)
10-12: Strong adaptation, visible quality differences
13-15: Aggressive adaptation, maximum bit savings

Choosing values:

Lower for professional/broadcast content
Medium for general streaming and storage
Higher for low-bitrate scenarios where bit savings are critical

Note: Only effective when SpatialAQ is enabled. Higher values may cause visible quality variations in flat areas like skies or walls.

StrictGOP

Gets or sets a value indicating whether strict GOP sizing is enforced.

public bool StrictGOP { get; set; }

Property Value

bool

Remarks

Strict GOP mode ensures consistent Group of Pictures structure by preventing adaptive I-frame insertion and maintaining exact GOP boundaries. This creates predictable segment sizes for streaming protocols.

FFMPEG option: -strict_gop 1

What it enforces:

Exact GOP size (no early I-frames at scene cuts)
Consistent bitrate distribution across GOPs
Predictable random access points
Fixed segment durations for HLS/DASH

When to use:

HLS/DASH streaming requiring exact segment durations
Broadcast workflows with fixed GOP requirements
When consistent chunk sizes are critical

Trade-offs:

May reduce quality at scene changes
Less optimal bit distribution
Cannot adapt to content complexity

Often used with: ForcedIDR for clean segment boundaries.

Surfaces

Gets or sets number of concurrent surfaces for encoder pipeline [0..64].

public int Surfaces { get; set; }

Property Value

int

Remarks

Surfaces represent the number of frame buffers NVENC can use for its encoding pipeline. More surfaces allow better pipelining and can improve throughput, especially for high resolution or high framerate content.

FFMPEG option: -surfaces [number]

Recommended values:

0: Auto (let NVENC decide based on resolution and settings)
8-16: Good for 1080p content
32-48: Recommended for 4K or high framerate encoding
64: Maximum value for extreme cases

Higher values increase GPU memory usage but can improve performance by allowing more frames to be processed in parallel. The optimal value depends on resolution, framerate, and GPU memory available.

TemporalAQ

Gets or sets a value indicating whether Temporal Adaptive Quantization is enabled.

public bool TemporalAQ { get; set; }

Property Value

bool

Remarks

Temporal AQ adjusts quality based on temporal characteristics, allocating more bits to static or slow-moving areas that viewers focus on, and fewer bits to fast-moving regions where detail is less perceptible.

FFMPEG option: -temporal-aq 1

How it works:

Analyzes motion between frames
Increases quality for static/slow areas (faces, text, backgrounds)
Reduces quality for fast motion (less noticeable during playback)

Particularly effective for:

Video conferencing (static speaker, moving background)
Gameplay with static HUD and moving game world
Security footage with areas of interest

Works best when combined with:

Spatial AQ for comprehensive adaptive quantization
Lookahead for better motion analysis
VBR rate control for quality flexibility

WeightedPrediction

Gets or sets a value indicating whether weighted prediction is enabled.

public bool WeightedPrediction { get; set; }

Property Value

bool

Remarks

Weighted prediction improves compression efficiency for scenes with brightness changes (fades, flashes) by applying weights to reference frames. This allows better prediction of frames during illumination changes.

FFMPEG option: -weighted_pred 1

How it works:

Analyzes brightness changes between frames
Applies scaling factors to reference frames
Significantly improves fade/flash compression
Small benefit for normal content

Most effective for:

Fade in/out transitions
Flash photography effects
Day/night transitions
Scenes with changing lighting

Performance impact:

Slightly increases encoder complexity
Minimal impact on decode performance
Can reduce bitrate by 5-20% for applicable scenes

Compatible with all rate control modes and presets.

ZeroLatency

Gets or sets a value indicating whether zero latency mode is enabled.

public bool ZeroLatency { get; set; }

Property Value

bool

Remarks

Zero latency mode configures NVENC for minimal encoding delay by disabling frame reordering and B-frames. Essential for real-time applications where every millisecond counts.

FFMPEG option: -tune zerolatency (or -preset llhp/llhq)

What it does:

Disables B-frames (no bidirectional prediction)
Disables frame reordering buffer
Minimizes lookahead and RC buffers
Forces immediate frame output

Use cases:

Live streaming with sub-second latency requirements
Video conferencing and remote desktop
Cloud gaming and interactive applications
Real-time broadcasting

Trade-offs:

20-30% higher bitrate for same quality (no B-frames)
Less efficient rate control (no lookahead)
May conflict with other settings (BAdapt, RCLookahead)

Table of Contents

Class CommonNVENCSettings

Inheritance

Derived

Inherited Members

Examples

Remarks

Constructors

CommonNVENCSettings()

Properties

AUD

Property Value

Remarks

BAdapt

Property Value

Remarks

BRefMode

Property Value

Remarks

BluRayCompatibility

Property Value

Remarks

ConstantQuality

Property Value

Remarks

DPBSize

Property Value

Remarks

ForcedIDR

Property Value

Remarks

GPUIndex

Property Value

Remarks

InitQP_B

Property Value

Remarks

InitQP_I

Property Value

Remarks

InitQP_P

Property Value

Remarks

NoSceneCut

Property Value

Remarks

NonRefP

Property Value

Remarks

Preset

Property Value

Remarks

QP

Property Value

Remarks

RCLookahead

Property Value

Remarks

RateControl

Property Value

Remarks

SpatialAQ

Property Value

Remarks

SpatialAQStrength

Property Value

Remarks

StrictGOP

Property Value

Remarks

Surfaces

Property Value

Remarks

TemporalAQ

Property Value

Remarks

WeightedPrediction

Property Value

Remarks

ZeroLatency