# 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:**
```bash
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:**
```bash
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:**
```bash
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:

```bash
# 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

```bash
# 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

```bash
# 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:
```toml
[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:

```toml
[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:

```toml
[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