Configuration Guide¶

StreamPack offers extensive configuration options to fine-tune your adaptive streaming conversion process. This guide covers all configuration methods and options.

Configuration Methods¶

1. Command Line Arguments¶

Override default settings directly from the command line:

streampack input.mp4 --output output_dir --format hls --bitrates 720p,1080p --preset medium --segment-duration 4

2. Configuration File¶

Create a configuration file for consistent settings across multiple conversions:

# streampack-config.yml
output_format: [hls, dash]
segment_duration: 4
preset: medium
crf: 23
max_workers: 6

bitrate_profiles:
  - name: "360p"
    resolution: [640, 360]
    video_bitrate: 800
    audio_bitrate: 128
  - name: "720p"
    resolution: [1280, 720]
    video_bitrate: 2500
    audio_bitrate: 192
  - name: "1080p"
    resolution: [1920, 1080]
    video_bitrate: 4500
    audio_bitrate: 192

drm:
  enabled: false
  key_server_url: ""
  content_id: ""

Load the configuration file:

streampack input.mp4 --config streampack-config.yml

3. Python API Configuration¶

For programmatic use:

from streampack import MediaConverter, MediaConfig, DRMConfig

# Create configuration
config = MediaConfig(
    segment_duration=4,
    preset='medium',
    crf=23,
    max_workers=6,
    output_formats=['hls', 'dash']
)

# Optional DRM configuration
drm_config = DRMConfig(
    enabled=True,
    key_server_url="https://your-key-server.com",
    content_id="your-content-id"
)

converter = MediaConverter(config=config, drm_config=drm_config)

Configuration Options¶

Output Settings¶

`output_formats`¶

Type: List of strings
Default: ['hls']
Options: hls, dash
Description: Output streaming formats to generate

streampack input.mp4 --format hls,dash

`segment_duration`¶

Type: Integer
Default: 4
Range: 2-10 seconds
Description: Duration of each media segment

streampack input.mp4 --segment-duration 6

Encoding Settings¶

`preset`¶

Type: String
Default: medium
Options: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow
Description: Encoding speed vs quality tradeoff

streampack input.mp4 --preset fast

`crf`¶

Type: Integer
Default: 23
Range: 0-51 (0 = lossless, 51 = worst quality)
Description: Constant Rate Factor for quality control

streampack input.mp4 --crf 20

Performance Settings¶

`max_workers`¶

Type: Integer
Default: Auto-detected (CPU cores)
Description: Number of parallel encoding workers

streampack input.mp4 --workers 4

Bitrate Profiles¶

Custom bitrate profiles allow you to define exact quality levels:

from streampack.config import BitrateProfile

profiles = [
    BitrateProfile("low", (640, 360), 800, 128),
    BitrateProfile("medium", (1280, 720), 2500, 192),
    BitrateProfile("high", (1920, 1080), 4500, 192),
    BitrateProfile("4k", (3840, 2160), 8000, 256),
]

config = MediaConfig(bitrate_profiles=profiles)

DRM Configuration¶

Enable multi-DRM protection:

drm_config = DRMConfig(
    enabled=True,
    key_server_url="https://your-drm-server.com/license",
    content_id="unique-content-identifier",
    widevine_enabled=True,
    playready_enabled=True,
    fairplay_enabled=True,
    key_rotation_period=3600  # seconds
)

Advanced Configuration¶

Hardware Acceleration¶

Configure hardware encoder preferences:

encoder_preferences:
  video:
    - videotoolbox  # macOS
    - nvenc         # NVIDIA
    - qsv           # Intel QuickSync
    - vaapi         # Linux
  audio:
    - aac
    - libfdk_aac

Subtitle Processing¶

Configure subtitle handling:

subtitles:
  enabled: true
  convert_to_webvtt: true
  skip_bitmap_formats: true
  languages: ['en', 'es', 'fr']  # Filter by language codes

Quality Optimization¶

Fine-tune quality settings:

quality:
  adaptive_bitrate: true
  two_pass_encoding: false
  buffer_size_multiplier: 2.0
  max_bitrate_multiplier: 1.5
  gop_size: 48  # Key frame interval

Environment Variables¶

Override settings using environment variables:

export STREAMPACK_MAX_WORKERS=8
export STREAMPACK_PRESET=fast
export STREAMPACK_CRF=20
export STREAMPACK_SEGMENT_DURATION=6

streampack input.mp4

Configuration Validation¶

StreamPack validates all configuration options:

from streampack import MediaConfig

try:
    config = MediaConfig(
        crf=60,  # Invalid: exceeds maximum value
        segment_duration=1  # Invalid: below minimum
    )
except ValueError as e:
    print(f"Configuration error: {e}")

Best Practices¶

For Live Streaming¶

segment_duration: 2
preset: veryfast
max_workers: 2
buffer_size_multiplier: 1.5

For VOD Content¶

segment_duration: 6
preset: medium
two_pass_encoding: true
max_workers: 4

For Mobile-First Content¶

bitrate_profiles:
  - name: "240p"
    resolution: [426, 240]
    video_bitrate: 400
    audio_bitrate: 64
  - name: "480p"
    resolution: [854, 480]
    video_bitrate: 1000
    audio_bitrate: 128

Troubleshooting¶

Common Configuration Issues¶

Encoder not found: Verify FFmpeg installation and hardware support
High memory usage: Reduce max_workers or use faster presets
Poor quality: Adjust crf value or bitrate profiles
Slow encoding: Use faster presets or enable hardware acceleration

Configuration Debugging¶

Enable verbose logging to debug configuration issues:

streampack input.mp4 --verbose --log-level debug

Check current configuration:

streampack --show-config