Quality Settings Guide¶

This guide helps you optimize video quality settings in StreamPack for different use cases and target audiences.

Understanding Video Quality¶

Key Quality Metrics¶

CRF (Constant Rate Factor): Controls quality vs file size tradeoff
Bitrate: Data rate for video and audio streams
Resolution: Video dimensions (width x height)
Frame Rate: Frames per second
GOP Size: Group of Pictures interval

Quality vs Performance Tradeoffs¶

Setting	Quality	Speed	File Size
CRF 18	Excellent	Slow	Large
CRF 23	Good	Medium	Medium
CRF 28	Fair	Fast	Small

CRF Guidelines¶

Recommended CRF Values¶

# Ultra High Quality (archival)
crf: 18
preset: slow

# High Quality (streaming)
crf: 20
preset: medium

# Standard Quality (default)
crf: 23
preset: medium

# Lower Quality (mobile/bandwidth limited)
crf: 28
preset: fast

CRF by Content Type¶

Live Action Movies¶

crf: 20-23
preset: medium
gop_size: 48

Animation/Cartoons¶

crf: 18-20  # Animation compresses well
preset: medium
gop_size: 48

Screen Recordings¶

crf: 15-18  # Text needs high quality
preset: medium
gop_size: 24

Sports/Action Content¶

crf: 20-25
preset: fast  # Motion needs faster encoding
gop_size: 24

Bitrate Profiles¶

Standard Profiles¶

from streampack.config import BitrateProfile

# Conservative profiles for limited bandwidth
conservative_profiles = [
    BitrateProfile("240p", (426, 240), 400, 64),
    BitrateProfile("360p", (640, 360), 800, 128),
    BitrateProfile("720p", (1280, 720), 2000, 192),
    BitrateProfile("1080p", (1920, 1080), 4000, 192),
]

# High quality profiles
premium_profiles = [
    BitrateProfile("360p", (640, 360), 1000, 128),
    BitrateProfile("720p", (1280, 720), 3000, 192),
    BitrateProfile("1080p", (1920, 1080), 6000, 256),
    BitrateProfile("1440p", (2560, 1440), 9000, 256),
    BitrateProfile("4K", (3840, 2160), 15000, 256),
]

Adaptive Bitrate Strategy¶

StreamPack automatically creates optimal profiles based on input video:

from streampack import MediaConverter

converter = MediaConverter()

# Analyze input and create adaptive profiles
results = converter.convert(
    'input.mp4',
    'output',
    adaptive_bitrates=True,
    target_bandwidth=5000  # kbps target for highest quality
)

Quality Presets¶

Preset Comparison¶

Preset	Speed	Quality	Use Case
ultrafast	10x	Poor	Real-time streaming
veryfast	5x	Fair	Live streaming
fast	3x	Good	VOD, time-critical
medium	1x	Very Good	Standard VOD
slow	0.5x	Excellent	Premium content
veryslow	0.3x	Best	Archival quality

Preset Recommendations by Use Case¶

Live Streaming¶

preset: veryfast
crf: 25
segment_duration: 2
max_workers: 2

VOD (Video on Demand)¶

preset: medium
crf: 23
segment_duration: 6
two_pass_encoding: false

Premium/Cinema Content¶

preset: slow
crf: 18
segment_duration: 6
two_pass_encoding: true

Mobile-First Content¶

preset: fast
crf: 26
segment_duration: 4
focus_mobile_profiles: true

Hardware Acceleration Impact¶

Quality Differences¶

Hardware encoders typically produce slightly lower quality than software encoders at the same bitrate:

# Software encoding (highest quality)
encoder_type: software
crf: 23

# Hardware encoding (adjust for quality difference)
encoder_type: hardware
crf: 20  # Lower CRF to compensate

Hardware-Specific Settings¶

NVIDIA NVENC¶

encoder: h264_nvenc
preset: medium
crf: 20
b_frames: 2

Apple VideoToolbox¶

encoder: h264_videotoolbox
preset: medium
crf: 20
max_bitrate_multiplier: 1.5

Intel QuickSync¶

encoder: h264_qsv
preset: medium
crf: 20
look_ahead: 1

Audio Quality Settings¶

Audio Bitrate Guidelines¶

Quality Level	Bitrate	Use Case
Low	64 kbps	Mobile, limited bandwidth
Standard	128 kbps	Most streaming content
High	192 kbps	Premium content
Audiophile	320 kbps	Music content, high-end

Audio Configuration¶

from streampack.config import AudioProfile

audio_profiles = [
    AudioProfile(codec='aac', bitrate=128, channels=2, sample_rate=48000),
    AudioProfile(codec='aac', bitrate=192, channels=2, sample_rate=48000),
]

Quality Assessment¶

Objective Quality Metrics¶

StreamPack can calculate quality metrics during conversion:

converter = MediaConverter(
    calculate_metrics=True,
    metrics=['psnr', 'ssim', 'vmaf']
)

results = converter.convert('input.mp4', 'output')
print(f"VMAF Score: {results['quality_metrics']['vmaf']}")

Visual Quality Inspection¶

# Generate quality comparison
streampack input.mp4 --output test_output --crf 18,23,28 --compare-quality

Platform-Specific Optimization¶

YouTube/Social Media¶

crf: 20
preset: medium
bitrate_profiles:
  - name: "1080p60"
    resolution: [1920, 1080]
    framerate: 60
    video_bitrate: 8000
    audio_bitrate: 192

Netflix/Premium Streaming¶

crf: 18
preset: slow
two_pass_encoding: true
hdr_support: true

Mobile Apps¶

crf: 25
preset: fast
bitrate_profiles:
  - name: "480p"
    resolution: [854, 480]
    video_bitrate: 1200
    audio_bitrate: 96

Quality Troubleshooting¶

Common Quality Issues¶

Blurry/Soft Video¶

Decrease CRF value (18-20)
Use slower preset
Check source resolution

Artifacts/Blocking¶

Lower CRF value
Increase bitrate
Adjust GOP size

Large File Sizes¶

Increase CRF value (25-28)
Use faster preset
Optimize bitrate profiles

Poor Motion Handling¶

Reduce GOP size
Use faster preset for live content
Increase frame rate

Quality Testing Workflow¶

Test with sample clips:

streampack sample.mp4 --duration 30 --crf 18,23,28 --output test_quality

Compare results:

streampack --compare test_quality/crf_18 test_quality/crf_23 test_quality/crf_28

Measure quality metrics:

from streampack.utils import calculate_quality_metrics

metrics = calculate_quality_metrics('original.mp4', 'encoded.mp4')
print(f"PSNR: {metrics['psnr']:.2f} dB")
print(f"SSIM: {metrics['ssim']:.4f}")

Best Practices¶

Quality Optimization Workflow¶

Analyze source material
Choose appropriate preset
Set CRF based on content type
Test with sample clips
Adjust based on target bandwidth
Validate with quality metrics

Quality-Performance Balance¶

# Balanced configuration for most use cases
quality_config = MediaConfig(
    crf=23,
    preset='medium',
    two_pass_encoding=False,
    adaptive_bitrates=True,
    hardware_acceleration='auto'
)

Quality Monitoring¶

# Monitor quality during batch processing
def quality_callback(file_path, metrics):
    if metrics['vmaf'] < 85:
        print(f"⚠️  Low quality detected in {file_path}: VMAF {metrics['vmaf']}")

converter = MediaConverter(quality_callback=quality_callback)