-
Notifications
You must be signed in to change notification settings - Fork 0
macOS App Guide
roto31 edited this page Mar 21, 2026
·
3 revisions
Complete guide to using the EXStreamTV macOS menu bar application.
- Overview
- Installation
- First Launch
- Menu Bar Interface
- Server Management
- AI Configuration
- Native Video Player
- Channel Switcher
- Notifications
- Settings
- Keyboard Shortcuts
- Troubleshooting
The EXStreamTV macOS app provides:
- Menu Bar Control: Quick access to server controls from the menu bar
- Native Video Player: Watch channels directly in the app with PiP support
- Channel Switcher: Quick channel navigation with keyboard shortcuts
- AI Integration: Configure and manage AI providers
- System Notifications: Alerts for server events and AI suggestions
- Launch at Login: Start automatically with your Mac
Requirements:
- macOS 13.0 (Ventura) or later
- Python 3.10+ with EXStreamTV installed
- FFmpeg for streaming
- Download
EXStreamTV-Installer.dmg - Open the DMG file
- Drag EXStreamTV to Applications folder
- Launch from Applications or Spotlight
cd EXStreamTVApp
swift build -c release
cp -r .build/release/EXStreamTVApp.app /Applications/When you first launch EXStreamTV, the Onboarding Wizard guides you through setup:
- Checks for Python and FFmpeg dependencies
- Shows installation status
- Offers to run the install script if dependencies are missing
Choose your AI configuration:
| Option | Description |
|---|---|
| Cloud AI | Uses Groq's free cloud service. Recommended for most users. |
| Local AI | Runs on your Mac with Ollama. Works offline. |
| Hybrid | Cloud primary with local fallback. Best reliability. |
| Skip | Configure AI later in Settings. |
- Set the server port (default: 8411)
- Choose data directory location
- Start the server
Connect your media libraries (optional):
- Plex Media Server
- Jellyfin
- Emby
- Local folders
Create your first channel:
- AI-Assisted: Let AI help create a channel
- Manual: Configure everything yourself
- Import M3U: Import existing playlist
- Summary of your configuration
- Link to open the web dashboard
The EXStreamTV icon appears in your macOS menu bar.
| Icon | Meaning |
|---|---|
| TV icon (gray) | Server stopped |
| TV icon (green) | Server running |
| TV icon with number | Active stream count |
Click the menu bar icon to see:
- Server Status: Running/Stopped with uptime
- Start/Stop Button: Control the server
- Quick Actions: Open Web UI, Dashboard, Channels
- Active Streams: List of current streams
- Settings Gear: Open preferences
- Click the menu bar icon
- Click Start Server
- Wait for "Server running" status
Or use keyboard shortcut: Cmd+Shift+S
- Click the menu bar icon
- Click Stop Server
Enable in Settings to start the server automatically when the app launches.
The app can automatically restart the server when your Mac wakes from sleep. Enable in Settings > General.
Configure AI providers in Settings > AI tab.
- Provider Type: Choose Cloud, Local, or Hybrid
- Cloud Service: Select Groq, SambaNova, or OpenRouter
- API Key: Enter your provider's API key
- Click Get Free API Key to open the provider's website
- Sign up and create an API key
- Paste the key in the API Key field
- Click Validate & Save
- Select Local AI as provider type
- Ensure Ollama is running (green status)
- Select a model from the dropdown
- Models are auto-recommended based on your RAM
The app shows:
- Green checkmark: AI configured and working
- Orange warning: Configuration incomplete
- Test button: Send a test request
Watch channels directly in the app with the native video player.
- Go to Channels in the web dashboard
- Click Play on a channel
- Select "Open in App" (or it opens automatically)
| Control | Action |
|---|---|
| Play/Pause | Click center button or press Space |
| Mute | Click speaker icon or press M |
| Volume | Drag slider or use scroll |
| Fullscreen | Click expand icon or press F |
| Picture in Picture | Click PiP icon |
- Click the PiP icon in the player controls
- The video floats above other windows
- Click again to exit PiP
The player shows current stream quality (1080p, 720p, etc.) in the bottom right.
Quickly switch between channels using the overlay.
- Press Cmd+G to open the channel switcher
- Or click Channels in the menu bar popover
| Key | Action |
|---|---|
| Up/Down Arrow | Navigate channels |
| Enter | Select channel |
| 0-9 | Type channel number to jump |
| Escape | Close switcher |
- Cmd+Up Arrow: Previous channel
- Cmd+Down Arrow: Next channel
Type a channel number (e.g., "12") to jump directly. The switcher waits 1.5 seconds for additional digits, then switches.
EXStreamTV sends macOS notifications for important events.
| Event | Description |
|---|---|
| Server Started | Server is running and ready |
| Server Stopped | Server has stopped |
| Server Error | An error occurred |
| Stream Started | A channel started playing |
| AI Fix Found | AI troubleshooting found solutions |
Go to Settings > Notifications:
- Enable notifications: Master toggle
- Server started/stopped: Startup notifications
- Server errors: Error alerts
- Stream started: Playback notifications
When streams are active, the dock icon shows a badge with the count.
To disable: Go to Settings > Notifications and disable dock badge.
Access settings via:
- Click gear icon in menu bar popover
- Press Cmd+,
- Menu: EXStreamTV > Settings
| Setting | Description |
|---|---|
| Start server on launch | Auto-start when app opens |
| Restart after sleep | Restart server after Mac wakes |
| Launch at login | Start app when you log in |
| Setting | Description |
|---|---|
| Port | Server port (default: 8411) |
| Python Path | Path to Python executable |
| Server Path | Path to EXStreamTV directory |
Configure AI providers. See AI Configuration.
Configure notification preferences. See Notifications.
| Setting | Description |
|---|---|
| Debug mode | Enable verbose logging |
| Log level | Set logging verbosity |
| Health check interval | Server monitoring frequency |
| Reset settings | Restore defaults |
| Shortcut | Action |
|---|---|
| Cmd+G | Open channel switcher |
| Cmd+Up | Channel up |
| Cmd+Down | Channel down |
| Cmd+, | Open Settings |
| Cmd+Q | Quit app |
| Shortcut | Action |
|---|---|
| Space | Play/Pause |
| M | Mute/Unmute |
| F | Toggle fullscreen |
| Esc | Exit fullscreen/Close |
| Shortcut | Action |
|---|---|
| Up/Down | Navigate |
| Enter | Select |
| 0-9 | Jump to channel |
| Esc | Close |
- Check macOS version (requires 13.0+)
- Right-click app > Open (bypasses Gatekeeper first time)
- Check Console.app for crash logs
- Check Python path in Settings > Server
- Verify EXStreamTV is installed:
python -c "import exstreamtv" - Check if port is in use:
lsof -i :8411 - View logs in Settings > Advanced > Open Logs Folder
Run the install script:
- Click "Run Install Script" in Welcome step
- Or run manually:
./scripts/install_macos.sh
- Check Settings > AI shows green status
- Verify API key is entered correctly
- For local AI, ensure Ollama is running
- Click "Test" to verify connection
- Check Settings > Notifications are enabled
- Verify macOS notification permissions:
- System Settings > Notifications > EXStreamTV
- Ensure FFmpeg is installed
- Check the channel has valid content
- Try the web player as alternative
To restart the setup wizard:
- Go to Settings > Advanced
- Click "Reset All Settings"
- Restart the app
- AI Setup Guide - Detailed AI configuration
- Quick Start Guide - Create your first channel
- Installation Guide - Platform-specific setup
Last Revised: 2026-03-20
Getting Started
Guides
- AI-Setup
- Channel-Creation-Guide
- Local-Media
- Hardware-Transcoding
- macOS-App-Guide
- Navigation-Guide
- Streaming-Stability
- Advanced-Scheduling
Reference
- API-Reference
- System-Design
- Architecture-Diagrams
- Pattern-Refactor-Sources
- ADR-Channel-Manager-Database
- EXStreamTV-UI-Architecture
- Architecture
- Streaming-Internals
- HDHomeRun-Emulation
- Metadata-And-XMLTV
- AI-Agent-And-Containment
- Restart-Safety-Model
- Observability
- Troubleshooting
- Log-Interpretation
- Tunarr-DizqueTV-Integration
- Distribution
- Build-Progress
Operations
Changelog & Migration