How jeromebanks/twiddle works
Twiddle is a terminal radio and local-gig discovery app, with audio playback, Sonos controls, and a music visualizer. The main workflows are dial → station now-playing and artist details → playback, and scene → venue shows → band identification → music preview. Sonos diagnostics and relay playback are separate capabilities. App excerpts document injected service boundaries; README documents several other capabilities, but unsampled implementation wiring is left out.
Main entry points: dial/app.py Station browser · scene/app.py Show browser · screen.py Visualizer screen · output.py Dial output
Components 25
Radio dial
- Dial command
src/twiddle/dial/cli.py - Station browser
src/twiddle/dial/app.py - Now-playing feed
src/twiddle/dial/feed.py - Station adapters
src/twiddle/stations/fetchers - Artist enrichment
src/twiddle/dial/enrich.py - Station artwork
src/twiddle/dial/art.py
Gig finder
- Scene command
src/twiddle/scene/cli.py - Show browser
src/twiddle/scene/app.py - Venue calendars
src/twiddle/scene/sources - Band identity
src/twiddle/scene/bands.py - Genre guesses
src/twiddle/scene/genre.py - Music previews
src/twiddle/scene/players.py
Playback and Sonos
- Dial output
src/twiddle/dial/output.py - Speaker playback
src/twiddle/play.py - Sonos controls
src/twiddle/control_cli.py - Spotify operations
src/twiddle/spotify_ops.py - Local audio relay
src/twiddle/relay.py
Music visualizer
- Visualizer screen
src/twiddle/viz/screen.py - Audio tap source
src/twiddle/viz/source.py - Audio capture
src/twiddle/viz/tap.py - Signal analysis
src/twiddle/viz/analysis.py - Visualizer modes
src/twiddle/viz/modes
Other components
- Listener
- Venue websites
- Sonos speaker
Connections 27
- Listener → Dial command: starts radio
- Dial command → Station browser: opens browser
- Station browser → Now-playing feed: requests updates
- Now-playing feed → Station adapters: fetches listings
- Station browser → Artist enrichment: looks up artists
- Station browser → Station artwork: loads artwork
- Station browser → Dial output: controls output
- Listener → Scene command: starts shows
- Scene command → Show browser: opens browser
- Show browser → Venue calendars: loads shows
- Venue calendars → Venue websites: fetches calendars
- Show browser → Band identity: identifies bands
- Show browser → Genre guesses: guesses genres
- Show browser → Music previews: requests previews
- Listener → Sonos controls: runs commands
- Sonos controls → Speaker playback: controls speakers
- Dial output → Speaker playback: plays media
- Speaker playback → Sonos speaker: streams audio
- Dial output → Spotify operations: manages Spotify
- Spotify operations → Local audio relay: uses relay
- Local audio relay → Sonos speaker: serves audio
- Station browser → Visualizer screen: opens on keypress
- Show browser → Visualizer screen: opens on keypress
- Visualizer screen → Audio tap source: selects audio
- Visualizer screen → Audio capture: captures stream
- Visualizer screen → Signal analysis: analyzes signal
- Visualizer screen → Visualizer modes: renders mode