diff --git a/README.md b/README.md index 8930489..b5076a5 100644 --- a/README.md +++ b/README.md @@ -2,54 +2,112 @@ > *Digital consciousness stream. Matrix aesthetic · THX-1138 hue.* -A full-screen terminal news ticker that renders live global headlines in large OTF-font block characters with a white-hot → deep green gradient. Headlines auto-translate into the native script of their subject region. Ambient mic input warps the glitch rate in real time. A `--poetry` mode replaces the feed with public-domain literary passages. +A full-screen terminal news ticker that renders live global headlines in large OTF-font block characters with a white-hot → deep green gradient. Headlines auto-translate into the native script of their subject region. Ambient mic input warps the glitch rate in real time. A `--poetry` mode replaces the feed with public-domain literary passages. Live messages can be pushed to the display over [ntfy.sh](https://ntfy.sh). --- ## Run ```bash -python3 mainline.py # news stream -python3 mainline.py --poetry # literary consciousness mode -python3 mainline.py -p # same +python3 mainline.py # news stream +python3 mainline.py --poetry # literary consciousness mode +python3 mainline.py -p # same +python3 mainline.py --firehose # dense rapid-fire headline mode +python3 mainline.py --refresh # force re-fetch (bypass cache) ``` -First run bootstraps a local `.mainline_venv/` and installs deps (`feedparser`, `Pillow`, `sounddevice`, `numpy`). Subsequent runs start immediately. +First run bootstraps a local `.mainline_venv/` and installs deps (`feedparser`, `Pillow`, `sounddevice`, `numpy`). Subsequent runs start immediately, loading from cache. --- ## Config -At the top of `mainline.py`: +All constants live in `engine/config.py`: | Constant | Default | What it does | |---|---|---| | `HEADLINE_LIMIT` | `1000` | Total headlines per session | +| `FEED_TIMEOUT` | `10` | Per-feed HTTP timeout (seconds) | | `MIC_THRESHOLD_DB` | `50` | dB floor above which glitches spike | -| `_FONT_PATH` | hardcoded path | Path to your OTF/TTF display font | -| `_FONT_SZ` | `60` | Font render size (affects block density) | -| `_RENDER_H` | `8` | Terminal rows per headline line | +| `FONT_PATH` | hardcoded path | Path to your OTF/TTF display font | +| `FONT_SZ` | `60` | Font render size (affects block density) | +| `RENDER_H` | `8` | Terminal rows per headline line | +| `SSAA` | `4` | Super-sampling factor (render at 4× then downsample) | +| `SCROLL_DUR` | `5.625` | Seconds per headline | +| `FRAME_DT` | `0.05` | Frame interval in seconds (20 FPS) | +| `GRAD_SPEED` | `0.08` | Gradient sweep speed (cycles/sec, ~12s full sweep) | +| `FIREHOSE_H` | `12` | Firehose zone height (terminal rows) | +| `NTFY_TOPIC` | klubhaus URL | ntfy.sh JSON endpoint to poll | +| `NTFY_POLL_INTERVAL` | `15` | Seconds between ntfy polls | +| `MESSAGE_DISPLAY_SECS` | `30` | How long an ntfy message holds the screen | -**Font:** `_FONT_PATH` is hardcoded to a local path. Update it to point to whatever display font you want — anything with strong contrast and wide letterforms works well. +**Font:** `FONT_PATH` is hardcoded to a local path. Update it to point to whatever display font you want — anything with strong contrast and wide letterforms works well. --- ## How it works -- Feeds are fetched and filtered on startup (sports and vapid content stripped) -- Headlines are rasterized via Pillow into half-block characters (`▀▄█ `) at the configured font size -- A left-to-right ANSI gradient colors each character: white-hot leading edge trails off to near-black +- Feeds are fetched and filtered on startup (sports and vapid content stripped); results are cached to `.mainline_cache_news.json` / `.mainline_cache_poetry.json` for fast restarts +- Headlines are rasterized via Pillow with 4× SSAA into half-block characters (`▀▄█ `) at the configured font size +- A left-to-right ANSI gradient colors each character: white-hot leading edge trails off to near-black; the gradient sweeps continuously across the full scroll canvas - Subject-region detection runs a regex pass on each headline; matches trigger a Google Translate call and font swap to the appropriate script (CJK, Arabic, Devanagari, etc.) using macOS system fonts - The mic stream runs in a background thread, feeding RMS dB into the glitch probability calculation each frame - The viewport scrolls through a virtual canvas of pre-rendered blocks; fade zones at top and bottom dissolve characters probabilistically +- An ntfy.sh poller runs in a background thread; incoming messages interrupt the scroll and render full-screen until dismissed or expired + +--- + +## Architecture + +`mainline.py` is a thin entrypoint (venv bootstrap → `engine.app.main()`). All logic lives in the `engine/` package: + +``` +engine/ + config.py constants, CLI flags, glyph tables + sources.py FEEDS, POETRY_SOURCES, language/script maps + terminal.py ANSI codes, tw/th, type_out, boot_ln + filter.py HTML stripping, content filter + translate.py Google Translate wrapper + region detection + render.py OTF → half-block pipeline (SSAA, gradient) + effects.py noise, glitch_bar, fade, firehose + fetch.py RSS/Gutenberg fetching + cache load/save + ntfy.py NtfyPoller — standalone, zero internal deps + mic.py MicMonitor — standalone, graceful fallback + scroll.py stream() frame loop + message rendering + app.py main(), boot sequence, signal handler +``` + +`ntfy.py` and `mic.py` have zero internal dependencies and can be imported by any other visualizer. --- ## Feeds -~25 sources across four categories: **Science & Technology**, **Economics & Business**, **World & Politics**, **Culture & Ideas**. Add or swap in `FEEDS`. +~25 sources across four categories: **Science & Technology**, **Economics & Business**, **World & Politics**, **Culture & Ideas**. Add or swap feeds in `engine/sources.py` → `FEEDS`. -**Poetry mode** pulls from Project Gutenberg: Whitman, Dickinson, Thoreau, Emerson. +**Poetry mode** pulls from Project Gutenberg: Whitman, Dickinson, Thoreau, Emerson. Sources are in `engine/sources.py` → `POETRY_SOURCES`. + +--- + +## ntfy.sh Integration + +Mainline polls a configurable ntfy.sh topic in the background. When a message arrives, the scroll pauses and the message renders full-screen for `MESSAGE_DISPLAY_SECS` seconds, then the stream resumes. + +To push a message: + +```bash +curl -d "Body text" -H "Title: Alert title" https://ntfy.sh/your_topic +``` + +Update `NTFY_TOPIC` in `engine/config.py` to point at your own topic. The `NtfyPoller` class is fully standalone and can be reused by other visualizers: + +```python +from engine.ntfy import NtfyPoller +poller = NtfyPoller("https://ntfy.sh/my_topic/json?since=20s&poll=1") +poller.start() +# in render loop: +msg = poller.get_active_message() # returns (title, body, timestamp) or None +``` --- @@ -62,7 +120,6 @@ At the top of `mainline.py`: ### Graphics - **Matrix rain underlay** — katakana column rain rendered at low opacity beneath the scrolling blocks as a background layer -- **Animated gradient** — shift the white-hot leading edge left/right each frame for a pulse/comet effect - **CRT simulation** — subtle dim scanlines every N rows, occasional brightness ripple across the full screen - **Sixel / iTerm2 inline images** — bypass half-blocks entirely and stream actual bitmap frames for true resolution; would require a capable terminal - **Parallax secondary column** — a second, dimmer, faster-scrolling stream of ambient text at reduced opacity on one side @@ -75,6 +132,10 @@ At the top of `mainline.py`: - **Persona modes** — `--surveillance`, `--oracle`, `--underground` as feed presets with matching color themes and boot copy - **Synthesized audio** — short static bursts tied to glitch events, independent of mic input +### Extensibility +- **serve.py** — HTTP server that imports `engine.render` and `engine.fetch` directly to stream 1-bit bitmaps to an ESP32 display +- **Rust port** — `ntfy.py` and `render.py` are the natural first targets; clear module boundaries make incremental porting viable + --- *macOS only (system font paths hardcoded). Python 3.9+.*