docs(graph): Add DSL documentation and examples
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.
This commit is contained in:
219
docs/presets-usage.md
Normal file
219
docs/presets-usage.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user