How nuuttisir/tuiwatchers works
Purpose and Entry Point
TuiWatchers is a Go terminal-oriented Twitch client: it authenticates a user, lists followed live channels, launches playback through MPV, and opens a separate terminal for interactive chat. Process startup and top-level dependency wiring are in main.go.
Authentication and Session Persistence
OAuth acquisition, refresh/use of saved credentials, and Twitch authorization interactions are centered in:
• internal/twitch/oauth.go
• internal/tui/auth.go
• internal/storage/storage.go
Persisted token state forms the boundary between local session storage and authenticated Twitch API/EventSub requests.
Twitch Platform Integration
The Twitch integration layer encapsulates HTTP/API client setup, Helix-style data retrieval, OAuth-backed requests, and EventSub/WebSocket-related behavior:
• internal/twitch/client.go
• internal/twitch/api.go
• internal/twitch/eventsub.go
This layer supplies authenticated user/followed-stream data to the UI and chat subscription/control paths, keeping Twitch protocol concerns outside rendering code.
Stream Browser and Playback Flow
The primary UI presents followed channels that are currently live and maps keyboard selection to stream playback:
• internal/tui/streams.go
• internal/tui/styles.go
• main.go
Selecting a channel starts external MPV playback; MPV relies on yt-dlp for stream extraction. These are required host executables rather than Go-managed streaming infrastructure.
Dedicated Chat Terminal
Chat is intentionally separate from the stream-browser UI: the application spawns a Ghostty terminal window for a selected channel, then runs live chat display and message input there:
• internal/chat/terminal.go
• internal/chat/render.go
• internal/chat/input.go
The terminal launcher is a platform/runtime boundary, while rendering and input handle the interactive chat loop.
Chat Events and Emotes
Live chat transport is driven by Twitch WebSocket/EventSub functionality, with incoming messages rendered after emote-aware transformation:
• internal/twitch/eventsub.go
• internal/chat/render.go
• internal/emotes/emotes.go
Outbound text from chat input flows back through the Twitch client; incoming messages flow from Twitch events through emote parsing into terminal rendering.
Material Runtime Dependencies
The binary is a Go module (go.mod) and depends operationally on Twitch services plus local tools: Ghostty for chat windows, MPV for viewing, and yt-dlp for source resolution. Setup-specific dependency expectations are documented in Dependencies.md.
Main entry points: streams.go Live stream browser · client.go Twitch API client · terminal.go Chat terminal launcher · main.go Process wiring
Components 19
Application
- Process wiring · Starts the client and wires top-level flows.
main.go - Authentication UI
internal/tui/auth.go - Live stream browser · Lists followed live channels and handles selection.
internal/tui/streams.go - TUI styles
internal/tui/styles.go - Token storage · Persists OAuth token state locally.
internal/storage/storage.go - Go module
go.mod
Twitch integration
- OAuth flow · Acquires and refreshes user credentials.
internal/twitch/oauth.go - Twitch API client · Owns authenticated HTTP setup and Helix data access.
internal/twitch/client.go - Helix data access · Retrieves authenticated user and followed-stream data.
internal/twitch/api.go - EventSub transport · Receives chat events and supports chat control paths.
internal/twitch/eventsub.go
Chat runtime
- Chat terminal launcher · Spawns a separate Ghostty window for a channel.
internal/chat/terminal.go - Chat input loop
internal/chat/input.go - Chat renderer
internal/chat/render.go - Emote transformer
internal/emotes/emotes.go
External dependencies
- Twitch services
- Ghostty
- MPV · Plays selected streams.
- yt-dlp · Resolves playable stream sources for MPV.
- Dependency guide
Dependencies.md
Connections 23
- Process wiring → Authentication UI: starts
- Process wiring → Live stream browser: starts
- Process wiring → Twitch API client: wires
- Authentication UI → OAuth flow: authenticates with
- OAuth flow → Token storage: loads and saves tokens
- OAuth flow → Twitch services: OAuth authorization
- Twitch API client → Helix data access: provides
- Twitch API client → EventSub transport: authenticates
- Twitch API client → Twitch services: API requests
- Live stream browser → Helix data access: loads followed live channels
- Live stream browser → TUI styles: uses
- Live stream browser → MPV: launches selected stream
- MPV → yt-dlp: extracts stream source
- Live stream browser → Chat terminal launcher: opens chat for channel
- Chat terminal launcher → Ghostty: spawns window
- Chat terminal launcher → Chat renderer: runs
- Chat terminal launcher → Chat input loop: runs
- EventSub transport → Chat renderer: incoming messages
- Chat renderer → Emote transformer: transforms messages
- Chat input loop → Twitch API client: sends chat text
- Dependency guide → Ghostty: documents
- Dependency guide → MPV: documents
- Dependency guide → yt-dlp: documents