tessl/pypi-streamlink

Command-line utility and Python library for extracting video streams from various streaming services

Overview

Eval results

Files

Options and Configuration

Name: tessl/pypi-streamlink
Author: tessl

Streamlink's options system provides flexible configuration for HTTP behavior, stream preferences, and plugin settings. The system supports default values, type validation, and getter/setter mappings for advanced option handling.

Capabilities

Options Base Class

The core Options class provides key-value storage with defaults and automatic key normalization.

class Options(dict):
    def __init__(self, defaults=None):
        """
        Initialize options with optional defaults.
        
        Parameters:
        - defaults: Dictionary of default option values
        
        Note: Option keys are normalized by replacing "_" with "-"
        """

    def get(self, key: str):
        """
        Get option value with getter mapping support.
        
        Parameters:
        - key: Option name (normalized automatically)
        
        Returns:
        Option value after applying any getter mapping
        """

    def set(self, key: str, value) -> None:
        """
        Set option value with setter mapping support.
        
        Parameters:
        - key: Option name (normalized automatically)  
        - value: Option value (processed by setter mapping if defined)
        """

    def update(self, options) -> None:
        """
        Update multiple options from dict, Mapping, or Options instance.
        
        Parameters:
        - options: Source of option updates
        """

    def clear(self) -> None:
        """Reset all options to their default values"""

    @property
    def defaults(self) -> dict:
        """Dictionary of default option values"""

Streamlink Session Options

The StreamlinkOptions class extends Options with mappings for Streamlink-specific configuration.

Key option categories include:

HTTP Configuration:

http-proxy - HTTP/HTTPS proxy URL
http-timeout - Request timeout in seconds
http-headers - Dictionary of HTTP headers
http-cookies - Cookie jar or cookie dictionary
http-ssl-verify - SSL certificate verification
http-disable-dh - Disable Diffie-Hellman key exchange

Stream Configuration:

stream-timeout - Stream read timeout
stream-retry-max - Maximum retry attempts
stream-retry-open - Retry attempts for opening streams
hls-timeout - HLS segment timeout
hls-segment-attempts - HLS segment retry attempts
dash-manifest-reload-attempts - DASH manifest reload attempts

Network Configuration:

ipv4 - Force IPv4 connections
ipv6 - Force IPv6 connections
interface - Network interface to bind to

Plugin Configuration:

plugin-dir - Additional plugin directories
plugin-timeout - Plugin execution timeout

Argument Classes

Classes for defining command-line arguments with validation and type conversion.

class Argument:
    """
    Definition of a command-line argument with validation.
    
    Supports all argparse.ArgumentParser.add_argument() parameters
    plus additional validation and transformation options.
    """

class Arguments:
    """
    Collection of Argument instances for command-line parsing.
    
    Provides methods for adding arguments and generating
    argparse-compatible argument definitions.
    """

Usage Examples

Basic Options Usage

from streamlink.options import Options

# Create options with defaults
opts = Options({
    'timeout': 30,
    'retries': 3,
    'quality': 'best'
})

# Get values
timeout = opts.get('timeout')  # 30
retries = opts.get('retries')   # 3

# Set values (key normalization)
opts.set('max_retries', 5)     # Same as 'max-retries'
opts.set('max-retries', 5)     # Direct key

# Update multiple options
opts.update({
    'timeout': 60,
    'user_agent': 'Custom Agent'
})

# Reset to defaults
opts.clear()

Session Options Configuration

import streamlink

session = streamlink.Streamlink()

# HTTP configuration
session.set_option('http-timeout', 30)
session.set_option('http-headers', {
    'User-Agent': 'Custom Streamlink Client',
    'Referer': 'https://example.com'
})

# Proxy configuration  
session.set_option('http-proxy', 'http://proxy.example.com:8080')

# SSL configuration
session.set_option('http-ssl-verify', False)  # Disable SSL verification

# Stream configuration
session.set_option('stream-timeout', 60)
session.set_option('hls-timeout', 30)
session.set_option('stream-retry-max', 5)

# Quality preferences
session.set_option('stream-sorting-excludes', ['audio_only', '160p'])

# Get current options
timeout = session.get_option('http-timeout')
headers = session.get_option('http-headers')

Advanced HTTP Configuration

import requests

session = streamlink.Streamlink()

# Configure HTTP session with custom settings
session.set_option('http-timeout', 45)
session.set_option('http-headers', {
    'User-Agent': 'Mozilla/5.0 (compatible; Streamlink)',
    'Accept-Language': 'en-US,en;q=0.9'
})

# Cookie handling
cookie_jar = requests.cookies.RequestsCookieJar()
cookie_jar.set('session_id', 'abc123', domain='example.com')
session.set_option('http-cookies', cookie_jar)

# SSL configuration for problematic sites
session.set_option('http-ssl-verify', '/path/to/custom/ca-bundle.crt')
session.set_option('http-ssl-cert', ('/path/to/client.crt', '/path/to/client.key'))

# Network interface binding
session.set_option('interface', '192.168.1.100')  # Bind to specific IP

Stream Quality Configuration

session = streamlink.Streamlink()

# Stream sorting and filtering
session.set_option('stream-sorting-excludes', [
    'audio_only',    # Exclude audio-only streams
    '160p', '240p'   # Exclude low-quality streams
])

# HLS-specific options
session.set_option('hls-segment-stream-data', True)
session.set_option('hls-segment-attempts', 3)
session.set_option('hls-segment-timeout', 10)
session.set_option('hls-timeout', 60)

# DASH-specific options  
session.set_option('dash-manifest-reload-attempts', 3)

# Retry configuration
session.set_option('stream-retry-max', 5)
session.set_option('stream-retry-open', 3)

Plugin-Specific Options

# Set options that plugins can access
session.set_option('twitch-disable-ads', True)
session.set_option('youtube-api-key', 'your-api-key')
session.set_option('http-headers', {
    'X-Custom-Header': 'value'
})

# Options with validation and transformation
from streamlink.options import Options

plugin_opts = Options({
    'quality': 'best',
    'username': None,
    'password': None
})

# Plugin can access these through self.options
plugin_opts.set('quality', '720p')
plugin_opts.set('username', 'user@example.com')

Custom Options with Validation

from streamlink.options import Options

class CustomOptions(Options):
    # Custom getter mapping
    _MAP_GETTERS = {
        'custom-timeout': lambda self, key: max(1, self.get(key, 30))
    }
    
    # Custom setter mapping  
    _MAP_SETTERS = {
        'custom-timeout': lambda self, key, value: setattr(self, key, int(value))
    }

# Usage
opts = CustomOptions({'custom-timeout': 15})
opts.set('custom-timeout', '45')  # Converted to int
timeout = opts.get('custom-timeout')  # Minimum value enforced

Options in Configuration Files

# Load options from configuration file
import json

with open('streamlink_config.json') as f:
    config = json.load(f)

session = streamlink.Streamlink()

# Apply configuration
for key, value in config.items():
    session.set_option(key, value)

# Example config file format:
config_example = {
    "http-timeout": 30,
    "http-headers": {
        "User-Agent": "Custom Client"
    },
    "stream-retry-max": 3,
    "hls-segment-attempts": 5
}

Environment Variable Integration

import os

session = streamlink.Streamlink()

# Use environment variables for sensitive options
if os.getenv('HTTP_PROXY'):
    session.set_option('http-proxy', os.getenv('HTTP_PROXY'))

if os.getenv('STREAMLINK_HTTP_TIMEOUT'):
    session.set_option('http-timeout', int(os.getenv('STREAMLINK_HTTP_TIMEOUT')))

# Plugin credentials from environment
twitch_token = os.getenv('TWITCH_OAUTH_TOKEN')
if twitch_token:
    session.set_option('twitch-oauth-token', twitch_token)

Install with Tessl CLI