tessl/pypi-streamlink

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

Overview

Eval results

Files

Session Management

Name: tessl/pypi-streamlink
Author: tessl

The Streamlink session system provides centralized management of plugins, HTTP configuration, and stream extraction. The Streamlink class is the primary interface for advanced usage, while the streams() convenience function provides simple access for basic use cases.

Capabilities

Streamlink Session Class

The main session class that coordinates plugin loading, URL resolution, and stream extraction with configurable options.

class Streamlink:
    def __init__(self, options=None, *, plugins_builtin=True, plugins_lazy=True):
        """
        Initialize a new Streamlink session.
        
        Parameters:
        - options: Custom options dict, Mapping, or Options instance
        - plugins_builtin: Whether to load built-in plugins (default: True)
        - plugins_lazy: Load built-in plugins lazily for faster startup (default: True)
        """

The session manages three key components accessible as properties:

@property
def http(self) -> HTTPSession:
    """HTTPSession instance for HTTP requests"""

@property  
def options(self) -> StreamlinkOptions:
    """Session options with getter/setter mappings"""

@property
def plugins(self) -> StreamlinkPlugins:
    """Plugin management and loading"""

@property
def version(self) -> str:
    """Package version string"""

@property
def localization(self) -> Localization:
    """Localization instance for language support"""

Option Management

Configure session behavior through the options system with validation and type checking.

def set_option(self, key: str, value) -> None:
    """
    Set a session option.
    
    Parameters:
    - key: Option name (underscores converted to hyphens)
    - value: Option value with type validation
    """

def get_option(self, key: str):
    """
    Get current option value.
    
    Parameters:
    - key: Option name
    
    Returns:
    Current option value or None if not set
    """

URL Resolution

Resolve URLs to matching plugins for stream extraction.

def resolve_url(self, url: str, follow_redirect: bool = True) -> tuple[str, type[Plugin], str]:
    """
    Find a plugin that can handle the given URL.
    
    Parameters:
    - url: URL to resolve (https:// added if no scheme)
    - follow_redirect: Whether to follow HTTP redirects (default: True)
    
    Returns:
    Tuple of (plugin_name, plugin_class, resolved_url)
    
    Raises:
    NoPluginError: If no plugin matches the URL
    """

def resolve_url_no_redirect(self, url: str) -> tuple[str, type[Plugin], str]:
    """
    Find a plugin without following redirects.
    
    Parameters:
    - url: URL to resolve
    
    Returns:
    Tuple of (plugin_name, plugin_class, resolved_url)
    
    Raises:
    NoPluginError: If no plugin matches the URL
    """

Stream Extraction

Extract streams from URLs using the resolved plugin.

def streams(self, url: str, options=None, **params) -> dict[str, Stream]:
    """
    Extract streams from URL using matched plugin.
    
    Parameters:
    - url: URL to extract streams from
    - options: Optional Options instance for the plugin
    - **params: Additional parameters passed to plugin.streams()
    
    Returns:
    Dictionary mapping quality names to Stream instances
    
    Raises:
    NoPluginError: If no plugin matches URL
    PluginError: If plugin fails to extract streams
    """

Convenience Function

Simple stream extraction without explicit session management.

def streams(url: str, **params) -> dict[str, Stream]:
    """
    Extract streams using a default Streamlink session.
    
    Parameters:
    - url: URL to extract streams from  
    - **params: Parameters passed to session.streams()
    
    Returns:
    Dictionary mapping quality names to Stream instances
    
    Raises:
    NoPluginError: If no plugin matches URL
    """

Usage Examples

Basic Session Usage

from streamlink import Streamlink

# Create session with custom options
session = Streamlink()
session.set_option('http-timeout', 30)
session.set_option('http-headers', {
    'User-Agent': 'My Custom User Agent'
})

# Configure stream preferences
session.set_option('stream-timeout', 60)
session.set_option('hls-timeout', 60)

# Extract streams
url = "https://www.twitch.tv/example"
streams_dict = session.streams(url)

if streams_dict:
    print("Available streams:")
    for quality, stream in streams_dict.items():
        print(f"  {quality}: {stream}")

URL Resolution

session = Streamlink()

try:
    plugin_name, plugin_class, resolved_url = session.resolve_url(
        "https://www.youtube.com/watch?v=example"
    )
    print(f"Matched plugin: {plugin_name}")
    print(f"Resolved URL: {resolved_url}")
except streamlink.NoPluginError:
    print("No plugin found for this URL")

Plugin Loading Control

# Create session without built-in plugins
session = Streamlink(plugins_builtin=False)

# Load plugins manually
session.plugins.load_builtin()

# Load custom plugins from directory
session.plugins.load_path("/path/to/custom/plugins")

# Check loaded plugins
loaded = session.plugins.get_loaded()
print(f"Loaded {len(loaded)} plugins")

Install with Tessl CLI