forked from genewildish/Mainline
David Gwilliam
915598629a
Add comprehensive documentation for the graph-based pipeline DSL: - docs/graph-dsl.md: Complete DSL reference with TOML, Python, and CLI syntax - docs/GRAPH_SYSTEM_SUMMARY.md: Implementation overview and architecture - examples/graph_dsl_demo.py: Demonstrates imperative Python API usage - examples/test_graph_integration.py: Integration test verifying pipeline execution The documentation follows a wiki-like approach with navigable structure: - Overview section explaining the concept - Syntax examples for each format (TOML, Python, CLI) - Node type reference table - Advanced features section - Comparison with old XYZStage approach This provides users with multiple entry points to understand and use the new graph-based pipeline system.
220 lines
5.4 KiB
Markdown
220 lines
5.4 KiB
Markdown
# 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
|