sideline/docs/presets-usage.md

Presets Usage Guide

Overview

The sideline branch introduces a new preset system that allows you to easily configure different pipeline behaviors. This guide explains the available presets and how to use them.

Available Presets

1. upstream-default

Purpose: Matches the default upstream Mainline operation for comparison.

Configuration:

• Display: Terminal (not pygame)
• Camera: Scroll mode
• Effects: noise, fade, glitch, firehose (classic four effects)
• Positioning: Mixed mode
• Message Overlay: Disabled (matches upstream)

Usage:

python -m mainline --preset upstream-default --display terminal

Best for:

• Comparing sideline vs upstream behavior
• Legacy terminal-based operation
• Baseline performance testing

2. demo

Purpose: Showcases sideline features including hotswappable effects and sensors.

Configuration:

• Display: Pygame (graphical display)
• Camera: Scroll mode
• Effects: noise, fade, glitch, firehose, hud (with visual feedback)
• Positioning: Mixed mode
• Message Overlay: Enabled (with ntfy integration)

Features:

• Hotswappable Effects: Effects can be toggled and modified at runtime
• LFO Sensor Modulation: Oscillator sensor provides smooth intensity modulation
• Visual Feedback: HUD effect shows current effect state and pipeline info
• Mixed Positioning: Optimal balance of performance and control

Usage:

python -m mainline --preset demo --display pygame

Best for:

• Exploring sideline capabilities
• Testing effect hotswapping
• Demonstrating sensor integration

3. demo-base / demo-pygame

Purpose: Base presets for custom effect hotswapping experiments.

Configuration:

• Display: Terminal (base) or Pygame (pygame variant)
• Camera: Feed mode
• Effects: Empty (add your own)
• Positioning: Mixed mode

Usage:

python -m mainline --preset demo-pygame --display pygame

4. Other Presets

• poetry: Poetry feed with subtle effects
• firehose: High-speed firehose mode
• ui: Interactive UI mode with control panel
• fixture: Uses cached headline fixtures
• websocket: WebSocket display mode

Positioning Modes

The --positioning flag controls how text is positioned in the terminal:

# Relative positioning (newlines, good for scrolling)
python -m mainline --positioning relative --preset demo

# Absolute positioning (cursor codes, good for overlays)
python -m mainline --positioning absolute --preset demo

# Mixed positioning (default, optimal balance)
python -m mainline --positioning mixed --preset demo

Pipeline Stages

Upstream-Default Pipeline

1. Source Stage: Headlines data source
2. Viewport Filter: Filters items to viewport height
3. Font Stage: Renders headlines as block characters
4. Camera Stages: Scrolling animation
5. Effect Stages: noise, fade, glitch, firehose
6. Display Stage: Terminal output

Demo Pipeline

1. Source Stage: Headlines data source
2. Viewport Filter: Filters items to viewport height
3. Font Stage: Renders headlines as block characters
4. Camera Stages: Scrolling animation
5. Effect Stages: noise, fade, glitch, firehose, hud
6. Message Overlay: Ntfy message integration
7. Display Stage: Pygame output

Command-Line Examples

Basic Usage

# Run upstream-default preset
python -m mainline --preset upstream-default --display terminal

# Run demo preset
python -m mainline --preset demo --display pygame

# Run with custom positioning
python -m mainline --preset demo --display pygame --positioning absolute

Comparison Testing

# Capture upstream output
python -m mainline --preset upstream-default --display null --viewport 80x24

# Capture sideline output
python -m mainline --preset demo --display null --viewport 80x24

Hotswapping Effects

The demo preset supports hotswapping effects at runtime:

• Use the WebSocket display to send commands
• Toggle effects on/off
• Adjust intensity values in real-time

Configuration Files

Built-in Presets

Location: engine/pipeline/presets.py (Python code)

User Presets

Location: ~/.config/mainline/presets.toml or ./presets.toml

Example user preset:

[presets.my-custom-preset]
description = "My custom configuration"
source = "headlines"
display = "terminal"
camera = "scroll"
effects = ["noise", "fade"]
positioning = "mixed"
viewport_width = 100
viewport_height = 30

Sensor Configuration

Oscillator Sensor (LFO)

The oscillator sensor provides Low Frequency Oscillator modulation:

[sensors.oscillator]
enabled = true
waveform = "sine"  # sine, square, triangle, sawtooth
frequency = 0.05   # 20 second cycle (gentle)
amplitude = 0.5    # 50% modulation

Effect Configuration

Effect intensities can be configured with initial values:

[effect_configs.noise]
enabled = true
intensity = 1.0

[effect_configs.fade]
enabled = true
intensity = 1.0

[effect_configs.glitch]
enabled = true
intensity = 0.5

Troubleshooting

No Display Output

• Check if display backend is available (pygame, terminal, etc.)
• Use --display null for headless testing

Effects Not Modulating

• Ensure sensor is enabled in presets.toml
• Check effect intensity values in configuration

Performance Issues

• Use --positioning relative for large buffers
• Reduce viewport height for better performance
• Use null display for testing without rendering